流水线一直 pending 最常见原因？

通常是 tags 与 Runner 注册标签不一致，或 Runner 未对该仓库可见层级注册；其次为 Runner 离线或 concurrent 已满。

为何建议从 concurrent=1 或 2 起步？

macOS 上多路 xcodebuild 易争用内存、DerivedData 与钥匙串会话；先压低并行建立磁盘与失败分层基线，再按观测上调。

何时应水平增加 Mac 云节点而非加并发？

当排队持续超窗、磁盘或内存告警频繁、或需要分区域/分环境隔离池时，应复制 Runner 标签策略加机，而不是单机堆高 concurrent。

2026 年在 Mac 云上架 GitLab Runner（macOS）：注册 Token、Executor 与并行上限落地指南

你已经用惯了 Linux 上的 GitLab Runner，却在 iOS 流水线面前卡在「没有 Apple 硬件」；好不容易租到可 SSH 的 Mac 云节点，又遇到注册失败、tags 对不上、三个 job 一起跑就把磁盘打满。本文写给要把 macOS 当「和 VPS 一样可控」构建面的平台工程与移动端负责人：先拆四条典型痛点，再给 Executor 与并行策略对照表，随后是五步可复现注册与验收，以及可写进容量规划的硬指标与 FAQ 结构化数据，帮助你在 2026 年把 GitLab CI 与 xcodebuild 稳定对齐。

1. 导语摘要：macOS Runner 与 Linux 习惯差在哪里

Linux 上常用 Docker executor：镜像干净、cgroup 限资源即可。macOS 上 Apple 工具链与钥匙串让隔离语义不同：并行 xcodebuild 易争用 DerivedData 与登录钥匙串；concurrent 盲目拉高常致随机链接失败或 OOM。须核对 GitLab 与 Runner 兼容矩阵，Apple Silicon 用 darwin-arm64 包。本文场景：可 SSH 的 Mac 云（可水平扩展），跑 iOS/macOS 或混合脚本；目标让 YAML tags 与注册标签一致，并把并发与清理写进 config.toml，避免口头约定。

2. 痛点拆解：注册、标签、钥匙串与磁盘争用

从 Linux 迁 Mac 云时，评审会上反复出现以下冲突，可逐条对照你们现状：

注册与 Token：实例级 registration token 与项目级 token 混用会导致 Runner 出现在错误层级；撤销或轮换后未同步 config.toml 会表现为「在线但不接 job」。
标签漂移：YAML 写 tags: [macos, ios]，Runner 只打了 macos-arm64，流水线永远 pending；或多人手工改标签导致环境与文档不一致。
钥匙串与无人值守：证书与 Provisioning Profile 依赖交互式解锁时，shell executor 下的非登录会话可能拿不到签名身份；需要明确的钥匙串分区策略或专用构建用户。
磁盘与缓存：DerivedData、CocoaPods、Swift Package 缓存与制品在同盘叠加，数日内可吃掉数十 GB；并行 job 共享同一清理窗口时易出现「A job 删了 B job 正在用的中间产物」。

3. 决策矩阵：shell 与 custom executor 怎么选

在 macOS 上，多数团队从 shell executor 起步；需要更强隔离时再评估 custom 或外部编排。下表可直接贴进架构说明。

维度	shell executor	custom / 外部隔离
上手成本	低，贴近 SSH 手工命令	高，需要维护运行器脚本或 VM 镜像
隔离强度	弱，共享同一用户环境	可接近「净机」或分卷
钥匙串与签名	与登录会话一致时最简单	需额外设计证书注入与解锁
并行策略	必须严格限 `concurrent` 与标签分池	可按池映射到不同工作目录或主机
磁盘管理	依赖约定路径与定时清理	可在 job 结束钩子中快照或删卷
典型适用	中小团队、单仓或少仓、以 xcodebuild 为主	多租户、强合规、需可复现净环境

                实践提示：若尚未有 custom 运维能力，优先用「标签分池 + 低并发 + 固定 DerivedData 根路径」把稳定性拉到基线，再考虑引入额外隔离层；否则容易在排障上消耗比省下的镜像时间更多的工程小时。
            

4. 落地步骤：注册到最小 green job 的五步

假设 Mac 云已可 SSH，GitLab 与 Runner 版本满足官方矩阵。

安装与架构校验：下载 darwin-arm64 的 gitlab-runner，gitlab-runner --version 与 uname -m 核对；避免 Rosetta 下混用 amd64 工具链。
注册：用实例或项目 registration token 执行 gitlab-runner register，tags 与后续 YAML 一致；检查 config.toml 中 [[runners]]。
executor 与并发：executor = "shell"，concurrent 从 1～2 起步；PR 与 Release 分 Runner 名与标签，避免钥匙串会话被抢满。
最小 YAML 验收：先跑 sw_vers 与 xcodebuild -version，再接入真实构建。
清理与监控：约定 DerivedData/缓存路径，定时或流水线尾部清理，磁盘阈值告警；失败按签名/依赖/OOM/磁盘分类。

示例：最小 .gitlab-ci.yml 片段（标签需与注册一致）。

stages: [verify]

mac-smoke:
  stage: verify
  tags: [macos-arm64, ci-pool-dev]
  script:
    - sw_vers
    - xcodebuild -version

config.toml 片段（示意，勿直接复制 token）：

concurrent = 2
check_interval = 0

[[runners]]
  name = "mac-cloud-pool-dev"
  url = "https://gitlab.example.com/"
  token = "REDACTED"
  executor = "shell"
  [runners.custom_build_dir]
  builds_dir = "/Users/gitlab-ci/builds"
  cache_dir = "/Users/gitlab-ci/cache"

5. 可引用技术信息：并行与磁盘硬指标

以中型 Swift/iOS 工程为参照（实测因模块而异）：

内存峰值：单路 Archive 常见约 12～18GB；三 job 同机全量编译时 32GB 节点易抖动。
磁盘阈值：建议 ≥40GB 连续可用缓冲；<10GB 时链接失败概率显著上升。
并发建议：无 custom 隔离时每机常从 1～2 路 xcodebuild 起步；PR 与 Archive 分标签池。
版本与网络：Runner 与 GitLab 主版本需对齐；依赖拉取与 Git 区域过远会线性拉长耗时，PoC 记录拉取子阶段。
可观测性：job 内打印 df -h、DerivedData 根与结果路径，对照磁盘竞态。

6. 纯 Linux 构建面为何不够，以及何时上专用 Mac 云

纯 Linux 池做不了真机签名与原生 Xcode；用办公室 Mac 或笔记本当 Runner 则有可用性与审计风险。非苹果硬件或灰色虚拟化常触许可与工具链缺口，排障成本高于租金。需要无人值守签名、锁定 Xcode 小版本、对齐企业出口与内网 registry 时，把可 SSH、可打标签、可水平扩容的专用 Mac 云纳入 GitLab 池更划算。租赁交付接近「像买 VPS 一样」自助开通；要与 API 与模板库标准化时，可读站内 Mac 云 90 秒 API 与 CI/CD 对接实践，贯通下单到 green job。