macOS Gitea Runner 安装指南

2026年9月21日 · 阅读需 8 分钟

适用：macOS（Intel / Apple Silicon M 系列），自托管 Gitea 实例，支持 host 模式，可用于 iOS/Android CI 构建；普通用户运行，无需 root/sudo。

一、前置条件

1.1 硬件配置要求

配置项	最低要求	推荐配置
CPU	4 核	8 核（Apple Silicon M1/M2/M3 更佳）
内存	8 GB	16 GB 及以上
磁盘空间	44 GB	70 GB 及以上（SSD）
芯片架构	Intel x64 或 Apple Silicon arm64	Apple Silicon（M系列构建 Android 速度提升约 50%）

重要提示： 双端同时构建对内存和磁盘 I/O 要求较高，8GB 内存容易因内存不足触发页面交换，导致构建失败。

1.2 Gitea 版本要求

Gitea 1.19.0 及以上版本支持 Actions 功能，1.21.0 及以上版本默认启用。

如果你使用的是 1.21.0 之前的版本，需在 Gitea 配置文件 app.ini 中手动启用：

[actions]
ENABLED = true

修改后重启 Gitea 服务。

仓库开启 Actions：进入对应仓库设置，勾选Enable Repository Actions。

二、安装 Gitea Runner

由于 iOS 构建强制依赖 macOS 宿主机环境（Xcode、钥匙串、签名证书等），必须使用二进制方式安装 Runner 并配置为 host 模式，使 Job 直接在宿主机上执行而非 Docker 容器中。

2.1 下载 Runner 二进制文件

预构建的二进制文件可从 Gitea Runner 下载页面获取。
该发布也可从 Gitea Runner 发布页面获取。
Apple Silicon 选择darwin‑arm64，Intel Mac 选择darwin‑amd64

每个文件旁边都会发布一个.sha256校验和以及一个.xz压缩版本：

VERSION=3.5.0   # any 3.x release, see the release page
curl -sSLO "https://dl.gitea.com/gitea-runner/$VERSION/gitea-runner-$VERSION-darwin‑arm64"
curl -sSLO "https://dl.gitea.com/gitea-runner/$VERSION/gitea-runner-$VERSION-darwin‑arm64.sha256"
sha256sum -c "gitea-runner-$VERSION-darwin‑arm64.sha256"
install -m 0755 "gitea-runner-$VERSION-darwin‑arm64" /usr/local/bin/gitea-runner

2.2 确认二进制文件与您的平台匹配：

gitea-runner --version

⚠️ 重要：首次运行 gitea-runner，macOS 会提示 “无法打开，因为来自未识别开发者”
解决：系统设置 → 隐私与安全性，页面下方点击「仍要打开」放行二进制程序。

三、注册 Gitea Runner

3.1 生成并修改配置文件

mkdir -p ~/gitea-runner && cd ~/gitea-runner
gitea-runner config generate > config.yaml

编辑 config.yaml，将 labels 部分修改为 host 模式：

# 关键：将默认的 docker 模式改为 host 模式
labels:
  - "macos-latest:host"
  - "macos-26.5:host"

说明：后缀:host代表任务直接在 macOS 宿主机执行，可以访问本机 Xcode、Android SDK、钥匙串；默认:docker://xxx为容器模式，无法做 iOS 签名打包。
性能调优：可在 config.yaml 修改capacity控制并发 job 数量；Flutter 双端并行构建建议 capacity=2。

3.2 获取注册 Token

Runner 注册到 Gitea 实例需要 Token，Token 有三种级别：

级别	获取路径	适用范围
实例级	`<Gitea地址>/admin/actions/runners`	所有仓库可用
组织级	`<Gitea地址>/<org>/settings/actions/runners`	该组织下仓库可用
仓库级	`<Gitea地址>/<owner>/<repo>/settings/actions/runners`	仅该仓库可用

将Token写入环境变量到 .zshenv

# 写入环境变量
echo 'export GITEA_RUNNER_REGISTRATION_TOKEN="令牌值"' >> ~/.zshenv
# 生效配置
source ~/.zshenv
# 验证是否写入成功
echo $GITEA_RUNNER_REGISTRATION_TOKEN

⚠️ 一个令牌可以注册任意数量的运行器，并且只要在用户界面或通过 API 未重置之前，它一直有效。

3.3 注册 Runner 到 Gitea 实例

方式 1：交互式注册

gitea-runner register
# or with a config file
gitea-runner -c config.yaml register

依次输入：

Gitea 实例地址（域名 / 局域网 IP）
Runner Token
Runner 名称，例如macos‑latest‑runner，默认为主机名；
labels 标签：macos-latest:host，默认为内置列表，或在配置文件设置时为 runner.labels
工作目录直接回车默认./work

方式 2：非交互脚本注册（自动化部署推荐）

gitea-runner register --no-interactive \
  --instance <instance_url> \
  --token <registration_token> \
  --name <runner_name> \
  --labels <runner_labels> \
  --config config.yaml

关键参数说明：

--instance：必须使用局域网 IP 或域名，禁止使用 127.0.0.1 或 localhost
--labels：设置 Runner 标签，工作流中通过 runs-on 匹配该标签

注册信息保存到目录下.runner文件，不要手动编辑该文件。
注册完成后，Gitea 后台 Runner 列表可以看到该 Runner，状态此时还未在线。

四、启动 Gitea Runner

4.1 前台调试启动（关闭终端就停止，仅调试）

gitea-runner -c config.yaml daemon

daemon 命令在前台运行。它读取相对于其工作目录的注册文件（默认为 runner.file 、 .runner ），因此重启时请保持工作目录稳定。
观察 Gitea 后台，Runner 状态变为在线代表注册成功。

4.2 macOS 开机自启守护：launchd 配置（生产常驻）

使用用户级 LaunchAgent，普通用户运行，不需要 sudo/root；launchd 不会读取 shell 的 zshrc 环境变量，全部使用绝对路径。

创建 plist 配置文件

touch ~/Library/LaunchAgents/com.gitea.runner.plist

写入下面 xml，将YOUR_USER_NAME替换为本机用户名（执行whoami获取）

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.gitea.runner</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/gitea-runner</string>
        <string>daemon</string>
        <string>--config</string>
        <string>/Users/YOUR_USER_NAME/gitea-runner/config.yaml</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>WorkingDirectory</key>
    <string>/Users/YOUR_USER_NAME/gitea-runner</string>
    <key>StandardOutPath</key>
    <string>/Users/YOUR_USER_NAME/gitea-runner/runner.log</string>
    <key>StandardErrorPath</key>
    <string>/Users/YOUR_USER_NAME/gitea-runner/runner.err.log</string>
    <key>EnvironmentVariables</key>
    <dict>
        <key>PATH</key>
        <string>/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
        <key>HOME</key>
        <string>/Users/YOUR_USER_NAME/gitea-runner</string>
        <key>ANDROID_HOME</key>
        <string>/Users/YOUR_USER_NAME/Library/Android/sdk</string>
    </dict>
    <key>UserName</key>
    <string>_gitea-runner</string>
</dict>
</plist>

加载并启动服务

# 校验plist语法
plutil ~/Library/LaunchAgents/com.gitea.runner.plist

# 加载agent
launchctl load ~/Library/LaunchAgents/com.gitea.runner.plist
# 启动
launchctl start com.gitea.runner
# 查看运行状态
launchctl list | grep com.gitea.runner

launchctl 常用管理命令

# 停止runner
launchctl stop com.gitea.runner
# 修改plist配置后重载
launchctl unload ~/Library/LaunchAgents/com.gitea.runner.plist && launchctl load ~/Library/LaunchAgents/com.gitea.runner.plist
# 彻底卸载开机自启
launchctl unload ~/Library/LaunchAgents/com.gitea.runner.plist

日志查看

tail -f ~/gitea-runner/runner.log
tail -f ~/gitea-runner/runner.err.log

五、Runner 版本更新流程

# 停止后台服务
launchctl stop com.gitea.runner
# 删除旧二进制
rm /usr/local/bin/gitea-runner

# 下载安装最新版本
参考：2.1 下载 Runner 二进制文件

# 重启服务
launchctl start com.gitea.runner

2.1 下载 Runner 二进制文件

六、卸载 Runner 完整步骤

# 停止并卸载launch agent
launchctl stop com.gitea.runner
launchctl unload ~/Library/LaunchAgents/com.gitea.runner.plist
rm ~/Library/LaunchAgents/com.gitea.runner.plist

# 删除runner全部文件
rm -rf ~/gitea-runner

# 删除二进制文件
rm /usr/local/bin/gitea-runner

同时登录 Gitea 网页后台，删除对应的 Runner 记录。

七、验证 Runner 工作正常

在仓库创建测试工作流：.gitea/workflows/test-runner.yml

name: macOS Runner 连通测试
on: [push]
jobs:
  test-job:
    runs-on: macos-latest
    steps:
      - name: 输出环境信息
        run: |
          echo "Runner host模式运行成功"
          uname -a

推送代码，在 Gitea Actions 页面观察任务是否正常执行。

⚠️注意：runs‑on标签必须和 runner 配置的 labels 完全匹配，本例中runs‑on: macos‑latest对应标签macos‑latest:host。

八、常见故障排查汇总

表格

现象	根因	解决方案
macOS 提示无法打开 gitea-runner	苹果公证安全隔离	设置‑隐私与安全性点击「仍要打开」放行
workflow Job 一直排队卡住	workflow `runs‑on`与 runner labels 不匹配	核对 yaml 的 runs‑on 名称与 config.yaml labels 保持一致
launchd 启动失败，日志无输出	plist 使用相对路径；缺少 config 入参	plist 全部填写绝对路径，校验 plist 语法`plutil`；ProgramArguments 补充`--config`参数
自签名 HTTPS Gitea 连接报错	macOS 不信任证书	内网测试增加环境变量`INSECURE=true`；生产环境导入可信根证书
host 模式构建 iOS 失败	runner 使用 docker 模式	labels 后缀必须是`:host`，不能用 docker 容器标签

九、安全注意事项

host 模式无容器沙箱隔离，job 可直接读写宿主机文件系统，仅给可信仓库开启 Actions；关闭 fork PR 自动执行流水线。
定期审查工作流 yaml 文件，避免恶意脚本执行。
Token、密钥不要硬编码写入配置文件，全部使用 Gitea 仓库 Secrets 存储。

一、前置条件​

1.1 硬件配置要求​

1.2 Gitea 版本要求​

二、安装 Gitea Runner​

2.1 下载 Runner 二进制文件​

2.2 确认二进制文件与您的平台匹配：​

三、注册 Gitea Runner​

3.1 生成并修改配置文件​

3.2 获取注册 Token​

3.3 注册 Runner 到 Gitea 实例​

方式 1：交互式注册​

方式 2：非交互脚本注册（自动化部署推荐）​

四、启动 Gitea Runner​

4.1 前台调试启动（关闭终端就停止，仅调试）​

4.2 macOS 开机自启守护：launchd 配置（生产常驻）​

五、Runner 版本更新流程​

六、卸载 Runner 完整步骤​

七、验证 Runner 工作正常​

八、常见故障排查汇总​

九、安全注意事项​

一、前置条件

1.1 硬件配置要求

1.2 Gitea 版本要求

二、安装 Gitea Runner

2.1 下载 Runner 二进制文件

2.2 确认二进制文件与您的平台匹配：

三、注册 Gitea Runner

3.1 生成并修改配置文件

3.2 获取注册 Token

3.3 注册 Runner 到 Gitea 实例

方式 1：交互式注册

方式 2：非交互脚本注册（自动化部署推荐）

四、启动 Gitea Runner

4.1 前台调试启动（关闭终端就停止，仅调试）

4.2 macOS 开机自启守护：launchd 配置（生产常驻）

五、Runner 版本更新流程

六、卸载 Runner 完整步骤

七、验证 Runner 工作正常

八、常见故障排查汇总

九、安全注意事项