GitLab Runner macOS 自托管怎么部署?2026 指南
CI 作业已经排队,但没有 Mac 节点接手;或者 Runner 显示在线,Xcode 作业仍因会话或工具链失败。
最快判断:GitLab Runner 可以部署在远程 Mac 上,macOS 构建通常使用 shell executor,并按 GitLab 官方支持的方式作为当前用户的 LaunchAgent 运行;不要配置成系统级 LaunchDaemon。由于 shell executor 的作业隔离有限,只应让可信项目进入该节点。
适合需要在 GitLab CI/CD 中执行 Xcode 构建或 iOS 测试、尚未搭建 macOS Runner 的工程师。
也适合从 Windows 或 Linux 维护构建节点的 DevOps 人员,以及评估远程 Mac 是否能承载流水线的团队。
先确认:执行作业的主机确实是 Mac
macOS Runner 不是 GitLab 服务本身。GitLab 服务可以在别的主机上,Runner 则需要安装在实际执行 CI 作业的 Mac 上;使用 shell executor 时,作业脚本会在这台 Mac 本地运行,因此它必须具备作业依赖的工具、凭据和项目环境。关于 Runner 注册,可参阅 GitLab Runner 注册说明;执行方式则见 shell executor 文档。
先把执行环境划分清楚:
- GitLab 服务端:托管仓库、CI 配置和作业队列,不必与 macOS Runner 同机。
- macOS Runner:领取任务并运行脚本;需要 Xcode 的步骤必须真正落到这台 Mac。
- 其他操作系统 Runner:可继续承接与 macOS 工具链无关的作业,避免把整条流水线不必要地迁移到 Mac。
| 方案 | 实际执行环境 | Xcode / Apple 工具链 | 隔离与适用条件 |
|---|---|---|---|
macOS 主机上的 shell executor |
安装 Runner 的 Mac 本地 | 可使用该账户已准备好的工具链 | 作业共享宿主机权限,只适合可信项目和受控节点 |
| 仅使用 Linux Runner | Linux 主机本地 | 不能直接使用 macOS 上的 Xcode 工具链 | 适合非 Apple 平台任务;需要 macOS 构建时须另行路由 |
| 分层流水线:现有 Runner 加 macOS Runner | 按作业标签分配到相应节点 | 仅将 Apple 平台步骤交给 Mac | 需要维护标签和依赖边界,但可缩小 Mac 节点的任务范围 |
GitLab 的 macOS 安装文档建议 iOS 和 macOS 构建使用 shell executor;这种执行器会在安装 Runner 的主机本地运行作业,因此 Xcode 环境可直接使用。它并不提供容器级隔离,选择时需要同时接受这一权限边界。
核对会话:用用户级 LaunchAgent,而非系统级服务
Runner 的启动身份会决定它能否看到用户环境。GitLab 的 macOS 文档规定,Runner 以当前登录用户身份作为 LaunchAgent 运行;该模式在用户登录时启动、登出时停止,并能访问该用户的钥匙串和图形会话。系统级 LaunchDaemon 则以系统上下文运行,GitLab Runner 不支持将其作为 macOS 服务模式。
这一区别会影响实际任务,不只是配置文件放在哪里:
- 代码签名若依赖用户钥匙串,Runner 的执行身份必须能访问相应钥匙串。
- 需要启动 iOS 模拟器或依赖图形会话的作业,不能仅凭 Runner 进程存在就认定环境可用。
- 用户登出后,用户级 Runner 会停止;如果团队要求重启后自动恢复,GitLab 文档提出的条件是开启 macOS 自动登录。自动登录会改变主机登录安全边界,应由团队评估是否可接受,而不是为追求在线状态直接启用。
Apple 对 用户代理与系统守护进程的说明也区分了用户会话中的代理与系统级作业。配置时应按 GitLab 对 Runner 服务模式的要求执行,不能将系统服务与用户代理视为可互换。
⚠️ 自动登录可以解决重启后没有用户会话的问题,但会让主机在启动时自动进入指定账户。若节点可接触签名材料或项目机密,先评估账户权限、磁盘访问和物理访问控制,再决定是否采用。
验收工具链:CI 调用的 Xcode 必须与预期一致
Runner 在线只证明它能联系 GitLab,不代表 CI 使用了正确的开发者目录,也不代表首次启动所需的组件已经安装。Apple 的 命令行工具安装说明介绍了工具安装与开发者目录相关要求;需要 Xcode 组件时,可按 Apple 的 下载与安装 Xcode 组件说明核对配置。
先在Runner 实际运行的账户下检查环境,避免只在管理员的交互终端里验证:
xcode-select -p
xcodebuild -version
xcodebuild -runFirstLaunch
xcodebuild -runFirstLaunch 是否需要执行,应以该机器的 Xcode 安装状态和 Apple 当前说明为准;不要把别的账户终端里成功的结果当作 Runner 账户的验证。单独安装命令行工具包并不等同于完整 Xcode;需要 xcodebuild 的任务,应按构建要求准备正确的软件。
验收时,把 CI 日志中的工具链识别结果与交互终端输出对照,并至少运行一项真实项目的代表性构建。普通编译、模拟器启动和签名发布是不同能力,成功完成其中一项,不应自动视为其他能力也已通过。团队可参考远程 Mac 的 Xcode 环境准备说明,逐项核对访问方式与工具链边界。
评估隔离:把 shell executor 当作宿主机权限,而非容器
shell executor 会在 Runner 主机本地运行脚本,作业以 Runner 用户的权限执行;GitLab 的 shell executor 安全文档指出,它对不同作业的隔离有限,作业可能访问同一服务器上其他项目的代码或影响宿主机。因此,不能将它描述成隔离容器,也不能仅靠项目标签来替代权限控制。
上线前逐项检查:
- [ ] Runner 只接收团队信任的项目作业;不把不受信任的合并请求任务路由到该节点。
- [ ] 运行账户不拥有超出构建需要的系统权限;避免让普通构建脚本可随意执行高权限操作。
- [ ] 评估不同项目是否会共享文件、缓存、钥匙串和本地凭据;共享宿主机下的权限边界不能假定为彼此隔离。
- [ ] 对签名密钥、访问令牌等凭据限制可见范围,并把 Runner 配置文件纳入主机访问控制。GitLab 的 自托管 Runner 安全说明指出,本地 Runner 配置文件被未授权读取时,认证令牌也可能暴露。
- [ ] 若业务需要更强的作业隔离,先评估适用的执行架构;若没有满足 Apple 工具链要求且经过验证的隔离方案,不要用“换个 executor 名称”来假装隔离已解决。
FAQ:把部署问题和能力验证分开
GitLab Runner 可以直接安装在 macOS 上吗?
可以。Runner 安装在执行作业的 Mac 上,作业依赖也由该 Mac 提供;这与 GitLab 服务本身是否部署在 Mac 上是两回事。GitLab 的 macOS 安装说明给出了针对 Mac 的服务安装方式,并要求使用用户级 LaunchAgent。
macOS Runner 应选择哪种 executor?
需要调用 Xcode 执行 iOS 或 macOS 构建时,优先按 GitLab 文档使用 shell executor。它会在安装 Runner 的本机执行,因此依赖必须预先装在该主机;同时,作业共享宿主机权限,运行范围应限于可信项目。
为什么不能把 macOS Runner 配置为 LaunchDaemon?
GitLab 把 macOS LaunchAgent 作为支持的服务模式,并明确表示不支持系统级 LaunchDaemon。用户级代理关联登录用户;模拟器或签名任务也可能依赖该用户的钥匙串与图形会话。主机重启后能否恢复,应连同登录状态和团队的自动登录安全决策一起测试。
怎么确认远程 Mac 真能完成 Xcode 构建?
在 Runner 实际运行账户下核实活动开发者目录和 Xcode 版本,并在 CI 作业中输出可审计的工具链信息,再运行代表性构建。构建成功之后,模拟器、签名等需要额外环境的能力仍要单独验收;Apple 的 Xcode 组件说明可用于判断当前机器是否还缺少构建所需组件。
验证路由:用专用标签确认作业落到预期节点
Runner 注册成功不代表目标作业一定由它执行。GitLab 根据作业标签筛选可用 Runner;为 macOS 节点设置专用标签,并在 .gitlab-ci.yml 中显式引用,可避免把依赖 Xcode 的任务误派给其他执行环境。标签与 Runner 范围的配置方式,可参阅 GitLab 管理 Runner 的说明。
注册时按 GitLab 当前界面创建 Runner 并取得认证令牌,再从 macOS 用户会话中的终端注册;GitLab 的 macOS 安装说明要求在本机 GUI 终端、以运行作业的账户执行安装流程。安装并启动用户级服务后,按官方记录的配置路径和日志位置检查状态。注册命令及认证流程应以当前 GitLab 页面提示为准,不要将令牌写入仓库或公开日志。
可以先用最小作业验证标签和执行环境,再扩大到项目构建:
macos-check:
tags:
- macos
script:
- echo "Runner shell: $SHELL"
- xcode-select -p
- xcodebuild -version
将 macos 替换为团队在 Runner 中实际配置的标签。检查作业日志里报告的 shell、开发者目录与 Xcode 版本,并确认作业的产物、失败原因和 Runner 身份能够追溯。标签只负责路由,不负责隔离;若同一节点接收多个项目,仍需按前述权限清单控制范围。
验收节点:把重启、登出和维护纳入发布判断
Runner 在线、最小脚本通过、Xcode 构建成功,是不同层次的证据。上线前按团队预期检查以下项目:
- [ ] 用户登出后,团队能接受 Runner 停止接单;若不能,先重新评估运行模式和任务设计,而不是改成不受支持的系统级服务。
- [ ] 主机重启后,确认用户会话、Runner 服务状态和日志都符合预期;若依赖自动登录,记录相应安全审批。
- [ ] 在 Xcode 或系统工具链更新后,重新核对活动开发者目录,并运行代表性构建。
- [ ] 节点发生维护或中断时,明确由谁检查服务、恢复任务并判断失败作业是否需要重跑。
- [ ] 分别记录编译、模拟器和签名验证结果,避免把一次绿色流水线误当成所有 Apple 平台能力均已验收。
部署时应以实际主机上的服务和日志为准,并将恢复步骤纳入团队运维说明;GitLab macOS 安装文档列出了 Runner 配置文件及标准输出、错误日志的默认位置。
如果团队现阶段依赖个人电脑,常见短板是电脑关机或登出后节点不可用、工具链更新难以统一,以及本地开发工作与 CI 作业争用同一环境;自购 Mac 能让团队自行控制主机与物理接口,但也需要自行承担硬件维护和节点管理。远程 Mac 可作为按需获得真实 macOS 执行环境的另一种方案,但是否适合长期关键流水线,仍取决于可用周期、接入方式、工具链条件和安全策略。对需要先验证部署边界的团队,可查阅 KuzCloud 的远程 Mac 接入说明,再到套餐页面核对租期与计费条件;若流水线需要长期稳定重负载或依赖本地物理接口,应优先评估自有设备是否更合适。
下一步:在将流水线迁到远程 Mac 前,先对照帮助说明确认接入方式,再核对套餐页面所列的租期与条件;确认 Runner 用户会话、Xcode 工具链和可信项目范围都符合要求后,再安排代表性作业验收。
用专属 Mac 节点运行 macOS 构建任务
KuzCloud 提供独占的 Apple Silicon M4 裸金属 Mac,适合部署自托管 Runner 与执行 Xcode 构建。
拥有完整 root 权限,可按项目需要安装 Xcode、Fastlane 及其他 CI 工具链。