在 macOS 上安装 GitLab Runner

当前文档来源：https://docs.gitlab.com/runner/install/osx/。本文档旨在为中文用户提供一份内容准确、结构清晰的安装与配置指南。

版本级别：免费版、高级版、旗舰版
服务形式： GitLab.com、GitLab 自托管版、GitLab 专属版

本页面包含了在 macOS（Apple Silicon 和 Intel x86-64）上安装 GitLab Runner 的说明。

在 macOS 上安装 GitLab Runner 的用户，通常会在本地或远程运行的容器或虚拟机上安装 GitLab。

1. 下载二进制文件

根据你的系统架构下载对应的二进制文件。

对于基于 Intel 芯片的系统：

sudo curl --output /usr/local/bin/gitlab-runner "https://s3.dualstack.us-east-1.amazonaws.com/gitlab-runner-downloads/latest/binaries/gitlab-runner-darwin-amd64"

对于基于 Apple Silicon (Arm) 芯片的系统：

sudo curl --output /usr/local/bin/gitlab-runner "https://s3.dualstack.us-east-1.amazonaws.com/gitlab-runner-downloads/latest/binaries/gitlab-runner-darwin-arm64"

提示：你可以按照 Bleeding Edge - 下载任何其他标记版本 中的说明，下载每个可用版本的二进制文件。

2. 授予执行权限

下载后，需要为二进制文件添加可执行权限。

sudo chmod +x /usr/local/bin/gitlab-runner

3. 注册与配置 Runner

在运行 GitLab Runner 应用程序的用户帐户中执行以下操作：

注册 Runner 配置：运行 gitlab-runner register 命令进行注册。在注册过程中，请选择 shell 执行器 (executor)。 > 重要说明：在 macOS 上构建 iOS 或 macOS 应用程序时，作业 (jobs) 直接在主机上运行，并使用已认证用户的身份。这些作业不在容器中运行，因此安全性低于使用容器执行器。有关详细信息，请参阅安全影响文档。
打开终端并切换到当前用户。 bash su - <用户名>

4. 安装并启动服务 (用户模式)

安装 GitLab Runner 为服务并启动它。

cd ~
gitlab-runner install
gitlab-runner start

注意：有关运行这些命令时解决潜在错误的详细信息，请参阅下面的故障排除部分。

重启系统。

如果按照上述步骤操作，GitLab Runner 的配置文件 (config.toml) 将位于 /Users/<用户名>/.gitlab-runner/。了解更多关于配置 Runner 的信息。

5. 已知问题与限制

5.1 服务安装与管理

必须从以当前用户身份登录的终端窗口安装服务，之后才能管理该服务。
- 要以当前用户身份登录，请在终端中运行 su - <用户名> 命令。你可以通过运行 ls /users 命令来获取你的用户名。
在 macOS 上唯一被证实有效的方式是以用户模式 (user-mode) 运行服务。
- 由于服务仅在用户登录时运行，因此你应在 macOS 机器上启用自动登录。

5.2 LaunchAgent 与 LaunchDaemon

该服务作为 LaunchAgent 启动。使用 LaunchAgent 使得构建作业能够执行 UI 交互，从而可以在 iOS 模拟器中运行和测试。
值得注意的是，macOS 也有 LaunchDaemon（在后台完全运行的服务）。LaunchDaemon 在系统启动时运行，但它们没有与 LaunchAgent 相同的 UI 交互访问权限。你可以尝试将 Runner 服务作为 LaunchDaemon 运行，但不支持此操作模式。
执行 install 命令后，可以通过检查 ~/Library/LaunchAgents/gitlab-runner.plist 文件来验证 GitLab Runner 是否已创建服务配置文件。

5.3 Git 凭证助手配置

如果使用 Homebrew 安装 git，它可能添加了一个 /usr/local/etc/gitconfig 文件，其中包含：

[credential]
  helper = osxkeychain

这会告诉 Git 在钥匙串中缓存用户凭证，这可能不是你想要的行为，并可能导致获取 (fetch) 操作挂起。

解决方案 1：从系统 gitconfig 中删除该行。 bash git config --system --unset credential.helper
解决方案 2：仅为 GitLab 用户禁用 credential.helper。 bash git config --global --add credential.helper ''
检查 credential.helper 的状态： bash git config credential.helper

6. 升级 GitLab Runner

6.1 升级二进制文件

停止服务。 bash gitlab-runner stop
下载二进制文件替换现有的 GitLab Runner 可执行文件。
- Intel 系统： bash sudo curl -o /usr/local/bin/gitlab-runner "https://s3.dualstack.us-east-1.amazonaws.com/gitlab-runner-downloads/latest/binaries/gitlab-runner-darwin-amd64"
- Apple Silicon 系统： bash sudo curl -o /usr/local/bin/gitlab-runner "https://s3.dualstack.us-east-1.amazonaws.com/gitlab-runner-downloads/latest/binaries/gitlab-runner-darwin-arm64"
授予执行权限。 bash sudo chmod +x /usr/local/bin/gitlab-runner
启动服务。 bash gitlab-runner start

6.2 升级服务文件 (LaunchAgent)

要升级 LaunchAgent 配置，必须卸载并重新安装服务。

gitlab-runner uninstall
gitlab-runner install
gitlab-runner start

7. 配合 GitLab Runner 服务使用 codesign

如果你通过 Homebrew 在 macOS 上安装了 gitlab-runner，并且你的构建调用 codesign，则可能必须设置 <key>SessionCreate</key><true/> 才能访问用户钥匙串。

注意：GitLab 不维护 Homebrew 安装包。建议使用官方二进制文件安装 GitLab Runner。

以下示例展示了如何以 gitlab 用户身份运行构建，并希望访问该用户为代码签名安装的证书。

<?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>SessionCreate</key><true/>
    <key>KeepAlive</key>
    <dict>
      <key>SuccessfulExit</key>
      <false/>
    </dict>
    <key>RunAtLoad</key><true/>
    <key>Disabled</key><false/>
    <key>Label</key>
    <string>com.gitlab.gitlab-runner</string>
    <key>UserName</key>
    <string>gitlab</string>
    <key>GroupName</key>
    <string>staff</string>
    <key>ProgramArguments</key>
    <array>
      <string>/usr/local/opt/gitlab-runner/bin/gitlab-runner</string>
      <string>run</string>
      <string>--working-directory</string>
      <string>/Users/gitlab/gitlab-runner</string>
      <string>--config</string>
      <string>/Users/gitlab/gitlab-runner/config.toml</string>
      <string>--service</string>
      <string>gitlab-runner</string>
      <string>--syslog</string>
    </array>
    <key>EnvironmentVariables</key>
    <dict>
      <key>PATH</key>
      <string>/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
    </dict>
  </dict>
</plist>

8. macOS 故障排除

以下是与 macOS 相关的故障排除。有关一般故障排除的更多信息，请参阅故障排除 GitLab Runner。

8.1 `killed: 9` 错误

问题：在基于 Apple Silicon 的系统上，运行 gitlab-runner install、gitlab-runner start 或 gitlab-runner register 命令时，可能会遇到此错误。
解决方案：确保 ~/Library/LaunchAgents/gitlab-runner.plist 中 StandardOutPath 和 StandardErrorPath 值指定的目录可写。
示例：在下面的示例中，/Users/USERNAME/Library/LaunchAgents/gitlab-runner.plist 文件已编辑，包含一个用于日志文件的新可写目录 gitlab-runner-log。 xml <key>StandardErrorPath</key> <string>/Users/USERNAME/gitlab-runner-log/gitlab-runner.err.log</string> <key>StandardOutPath</key> <string>/Users/USERNAME/gitlab-runner-log/gitlab-runner.out.log</string> </dict>

8.2 错误：`"launchctl" failed: exit status 112, Could not find domain for`

问题：尝试在 macOS 上安装 GitLab Runner 时可能出现此消息。
解决方案：确保你从 GUI 终端应用程序（而非 SSH 连接）管理 GitLab Runner 服务。

8.3 消息：`Failed to authorize rights (0x1) with status: -60007.`

问题：在 macOS 上使用 GitLab Runner 时，如果卡在上述消息，有两个可能原因：
解决方案 1：确保你的用户可以执行 UI 交互。 bash DevToolsSecurity -enable sudo security authorizationdb remove system.privilege.taskport is-developer
- 第一条命令为你的用户启用对开发者工具的访问。
- 第二条命令允许属于开发者组成员的用户进行 UI 交互（例如，运行 iOS 模拟器）。
解决方案 2：确保你的 GitLab Runner 服务没有使用 SessionCreate = true。
- 之前，当将 GitLab Runner 作为服务运行时，我们使用 SessionCreate 创建 LaunchAgent。在当时（OS X Mavericks），这是使代码签名工作的唯一解决方案。但后来随着 OS X El Capitan 引入了许多新的安全功能，改变了这一行为。
- 从 GitLab Runner 1.8 开始，默认情况下 SessionCreate 为 false。但是，要升级，你必须手动重新安装 LaunchAgent 脚本。 bash gitlab-runner uninstall gitlab-runner install gitlab-runner start
- 然后，你可以验证 ~/Library/LaunchAgents/gitlab-runner.plist 中的 SessionCreate 是否已设置为 false。

8.4 作业错误：`Failed to connect to path port 3000: Operation timed out`

问题：如果某个作业因此错误而失败。
解决方案：确保 Runner 可以连接到你的 GitLab 实例。连接可能被以下因素阻止：
- 防火墙
- 代理
- 权限
- 路由配置

8.5 错误：`FATAL: Failed to start gitlab-runner: exit status 134`（执行 `gitlab-runner start` 命令时）

问题：此错误表明 GitLab Runner 服务未正确安装。
解决方案： bash gitlab-runner uninstall gitlab-runner install gitlab-runner start
如果错误仍然存在，请执行图形登录 (graphical login)。图形登录会启动 LaunchAgent，这是启动服务所必需的。更多信息，请参见上文的已知问题。
- 针对 AWS 托管的 macOS 实例：必须执行额外步骤来连接到实例的 GUI。使用 ssh -L 选项启用 SSH 端口转发，以允许远程桌面客户端（如 VNC）连接到远程实例。还必须在 AWS 托管的 macOS 实例上的 /private/etc/ssh/sshd_config 中配置 AllowTcpForwarding yes。重启实例以将更改应用于 sshd 配置。登录 GUI 后，在 GUI 的终端中重复 GitLab Runner 故障排除步骤以解决错误。

8.6 错误：`"launchctl" failed with stderr: Load failed: 5: Input/output error`

问题：运行 gitlab-runner start 命令时遇到此错误。
解决方案：确保 ~/Library/LaunchAgents/gitlab-runner.plist 中 StandardOutPath 和 StandardErrorPath 值指定的目录存在。 xml <key>StandardOutPath</key> <string>/usr/local/var/log/gitlab-runner.out.log</string> <key>StandardErrorPath</key> <string>/usr/local/var/log/gitlab-runner.err.log</string>
- 如果目录不存在，请创建它们，并确保 Runner 服务用户具有读写它们的适当权限。

8.7 错误：`Error on fetching TLS Data from API response... error=couldn‘t build CA Chain`

问题：如果将 GitLab Runner 升级到 v15.5.0 或更高版本，可能会出现以下错误： Certificate doesn‘t provide parent URL: exiting the loop Issuer=Baltimore CyberTrust Root IssuerCertURL=[] Serial=33554617 Subject=Baltimore CyberTrust Root context=certificate-chain-build Verifying last certificate to find the final root certificate Issuer=Baltimore CyberTrust Root IssuerCertURL=[] Serial=33554617 Subject=Baltimore CyberTrust Root context=certificate-chain-build ERROR: Error on fetching TLS Data from API response... error error=couldn‘t build CA Chain: error while fetching certificates from TLS ConnectionState: error while fetching certificates into the CA Chain: couldn‘t resolve certificates chain from the leaf certificate: error while verifying last certificate from the chain: x509: “Baltimore CyberTrust Root” certificate is not permitted for this usage runner=x7kDEc9Q
解决方案：
1. 升级到 GitLab Runner v15.5.1 或更高版本。
2. 或在配置中将 FF_RESOLVE_FULL_TLS_CHAIN 设置为 false。例如，在 config.toml 中： toml [[runners]] name = "example-runner" url = "https://gitlab.com/" token = "TOKEN" executor = "docker" [runners.feature_flags] FF_RESOLVE_FULL_TLS_CHAIN = false > 注意：禁用此功能标志可能会修复使用 SHA-1 签名或其他已弃用根证书签名的 HTTPS 端点的 TLS 连接问题。

文档来源：GitLab 官方文档 - Install GitLab Runner on macOS 整理日期：2026年1月2日
归档说明：此中文 Markdown 文档为官方英文文档的忠实翻译与整理，用于技术存档与参考。

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search