流水線一直 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。