GitLab Runner macOS 自託管怎麼部署?2026 指南
GitLab Runner macOS 自託管部署的可行方案,是在實際執行作業的 Mac 上使用 shell executor,並依 GitLab 官方要求以使用者層級 LaunchAgent 執行;不可將它改設為系統級 LaunchDaemon。這項服務模式限制見於GitLab 的 macOS Runner 安裝文件。部署前還要確認 shell executor 的隔離能力符合團隊風險要求,並且只讓可信任的專案派送工作到該節點。
這篇內容適合需要讓 GitLab CI/CD 執行 Xcode 建置或 iOS 測試、但尚未建立 macOS Runner 的工程師;也適合從 Windows 或 Linux 維護 Apple 平台建置節點的 DevOps 人員,以及正在評估遠端 Mac 能否承載持續整合工作的團隊。
先核對執行環境:Runner 是否安裝在真正的 macOS 節點
GitLab Runner 必須安裝在「實際執行作業」的 macOS 主機上,作業所需的 Xcode、命令列工具、相依套件與專案資料也必須能在該主機上取得。只在另一台主機上設定 GitLab,並不會讓作業自動擁有 macOS 工具鏈。
需要分清兩件事:GitLab CI/CD 服務負責管理專案與派送工作;Runner 則負責在註冊的執行節點上執行工作。若團隊已有 GitLab 平台,只是缺少 Apple 平台建置能力,通常需要準備的是 macOS Runner 節點,而非把整套 GitLab 服務搬到 Mac 上。
部署前,逐項確認以下條件:
- [ ] 目標主機確實執行 macOS,且 Runner 安裝在預期的執行節點。
- [ ] Xcode 與專案相依工具安裝於該主機,而非只存在於工程師的本機。
- [ ] Runner 已註冊至正確的專案、群組或執行範圍;範圍設定可參考管理 Runner 的官方說明。
- [ ] CI 設定使用專用標籤,能將 Apple 平台作業導向此 macOS 節點。
- [ ] 團隊已確認作業使用的帳戶、檔案路徑與憑據來源。
註冊時應使用 GitLab 提供的 Runner 註冊流程,將憑據視為機密處理,不要把註冊權杖寫入公開程式碼或可下載的建置產物。註冊方式與所需資訊可對照Runner 註冊文件。
會話與服務模式:以使用者層級 LaunchAgent 運行
macOS Runner 的服務模式不是單純的開機啟動選項。GitLab 文件指定使用者層級 LaunchAgent,並說明不支援系統級 LaunchDaemon;因此,不應以管理員權限把 Runner 安裝成系統服務,再假設它仍具有與登入使用者相同的工作環境。Apple 對使用者代理與系統守護進程的差異亦有說明。
這項差異會影響作業能否取得登入使用者的環境、鑰匙圈及圖形工作階段。若 CI 工作只呼叫命令列建置,依然要檢查 Runner 執行帳戶可否讀取專案與必要憑據;若工作涉及模擬器或需圖形工作階段的操作,則必須另外確認登入狀態與實際執行行為,不能只用 Runner 顯示在線上作為證明。
GitLab 的 macOS 安裝說明也要求評估重啟後 Runner 如何恢復,並涉及自動登入設定。自動登入可能讓使用者工作階段在主機重新啟動後恢復,但也會改變實體主機的安全風險;若節點存放簽名憑據或可存取內部程式碼,應先由維運與資安人員確認此取捨,而非為了自動啟動直接套用設定。
Xcode 工具鏈:讓 CI 確認呼叫的是預期環境
主機上「已安裝 Xcode」不代表 CI 作業一定呼叫到預期的工具鏈。安裝狀態、活動開發者目錄、首次啟動所需元件與 Runner 使用者的環境,都可能造成互動式終端與 CI 執行結果不同。
先在目標 Mac 上檢查活動開發者目錄與工具版本,再透過 CI 日誌記錄同一組資訊。以下命令可作為基本核對方式:
xcode-select -p
xcodebuild -version
若專案依賴模擬器,可再檢查模擬器裝置是否可用;但不能由「裝置清單可讀取」推定測試、簽名或發布流程已完成驗證。Apple 的命令列工具安裝說明及Xcode 額外元件安裝文件可用來核對工具與元件要求。
驗收時,選擇一個能代表團隊日常工作的建置目標,從 CI 作業中執行並保存日誌。日誌至少要能辨認執行節點、活動開發者目錄、Xcode 工具版本、建置結果與產物位置。若實際部署還需要模擬器、程式碼簽名或封裝發布,應把這些能力分別列為驗收項目,不要用一次普通建置成功代替。
隔離與權限:確認 shell executor 的風險可接受
macOS shell executor 會在 Runner 主機本機執行作業,因此使用者權限和本機檔案存取範圍是安全邊界的重要部分。GitLab 對shell executor 的執行方式與限制有明確說明;其安全文件亦提醒,自託管 Runner 需要依信任程度管理作業與執行節點,不能把 shell executor 描述成容器式隔離。
部署前應評估:
- Runner 是否只接收已審核、可信任專案的作業;若外部貢獻者可觸發工作,需先確認派送規則與權限。
- 作業帳戶是否遵循最小權限原則,避免以日常管理帳戶執行一般建置。
- 同一帳戶可讀取的鑰匙圈、環境變數、暫存檔及簽名憑據,是否可能被其他作業讀取。
- 是否有清理工作目錄與機密資料的流程,以及作業失敗後如何檢查殘留檔案。
- 風險是否足以要求改用不同執行架構或拆分執行節點,而不是只調整 CI 標籤。
若專案需要不同信任等級的工作共用 Runner,應先重新評估隔離設計。單靠增加標籤並不能建立安全隔離;標籤負責路由,並不會改變作業在主機本機執行的權限邊界。
常見部署疑問
GitLab Runner 可以直接安裝在 macOS 主機上嗎?
可以,前提是 Runner 安裝於真正執行作業的 Mac,且作業依賴的工具也在該節點可用。這與是否將 GitLab 服務本身部署在 macOS 是不同的架構決定;註冊後仍要以一項最小 CI 工作確認路由與執行環境。
macOS Runner 應採用哪種 executor?
需要在主機上直接呼叫 Xcode 或 Apple 平台工具鏈時,可評估 shell executor。它會使用 macOS 節點本機環境,但隔離有限,因此適用與否還取決於專案信任度、帳戶權限與憑據管理,而不是只看建置指令能否執行。
為什麼不能把 macOS Runner 設為 LaunchDaemon?
GitLab 的 macOS 安裝文件指定使用者層級 LaunchAgent,並列明不支援系統級 LaunchDaemon。這是部署支援條件,不應透過改用系統服務來規避。若作業依賴登入工作階段、鑰匙圈或圖形環境,也要按實際需求驗證使用者會話。
如何在遠端 Mac 驗證 Xcode 建置工作?
讓 CI 工作輸出 Xcode 版本與活動開發者目錄,再執行代表性專案建置,確認工作確實落在預定的 macOS Runner。檢查日誌、產物與錯誤資訊是否可追溯;若流水線還需模擬器測試、簽名或發布,應逐項測試,不要以普通建置成功代替。
路由與結果:用專用標籤確認作業落點
將 macOS Runner 設定為專用標籤,並在相關 CI 工作中明確指定該標籤。這能讓團隊檢查作業是否派送至預期節點,也降低 macOS 工作誤落到其他 Runner 的可能。標籤只協助選擇執行節點,不能取代權限控管或作業隔離。
可用精簡的 CI 工作做路由驗收,並把需要的識別資料寫入日誌:
macos-check:
tags:
- macos
script:
- sw_vers
- xcode-select -p
- xcodebuild -version
- xcodebuild -project "範例專案.xcodeproj" -scheme "範例Scheme" build
將範例專案與 Scheme 換成實際值,並確認程式碼使用的名稱與大小寫符合專案設定。驗收時查看 Runner 名稱、執行環境、工具鏈輸出、建置結果及產物位置;若作業失敗,應能從日誌判斷是路由、工具鏈、相依套件還是建置本身出錯。模擬器、簽名與發布仍需分開測試。
節點可用性:驗證登出、重啟與維護後的恢復
自託管 Runner 是否適合承載持續流水線,不只取決於單次建置能否成功,也取決於節點維護後能否按預期恢復。用團隊可接受的維運流程測試使用者登出與主機重新啟動,確認 Runner 狀態、使用者會話、工具鏈與作業日誌是否符合預期。
建立一份交接檢查清單:
- [ ] 服務由預期的 macOS 使用者啟動,且沒有被改裝成 LaunchDaemon。
- [ ] 主機重啟後,Runner 的恢復方式與自動登入風險已經過團隊審核。
- [ ] 維護工具鏈或更新 Xcode 後,CI 日誌仍能辨認所用環境。
- [ ] 失敗作業的日誌與產物能協助定位問題,且機密資料不會因除錯而外洩。
- [ ] 團隊已決定此節點只用於個人試用、受控團隊作業,或承擔關鍵流水線。
若目前只完成基本建置測試,適合先視為有限用途節點;要提升到團隊或關鍵流水線使用,還需要完成會話恢復、權限、工具鏈變更與故障處理驗證。操作介面與連線方式等服務資訊,應在確認實際需求時核對KuzCloud 控制台說明;若有存取或使用上的疑問,可再參考KuzCloud 說明中心。
選擇遠端 Mac 前,先對照目前的建置方式
個人 Mac 作為 Runner 的優點是工具鏈與日常開發環境接近,但主機重啟、使用者登出或個人工作占用,都可能影響流水線可用性;自行購買專用 Mac 則需要承擔硬體採購、維護與更新安排。兩者都不一定適合需要獨立、可遠端管理的建置節點。
| 選項 | 適合情況 | 主要限制 | 部署判斷 |
|---|---|---|---|
| 個人 Mac | 先驗證 CI 設定,且可接受個人主機狀態影響作業 | 登出、重啟與日常使用可能干擾節點可用性 | 先用可信任專案試跑,未驗證恢復前不承擔關鍵流水線 |
| 自行維護的專用 Mac | 團隊需要固定節點,並能負責硬體與維護 | 採購、維護、工具鏈更新及安全設定由團隊承擔 | 適合已有維運能力、可管理主機生命週期的團隊 |
| 遠端 Mac | 需要遠端存取 macOS,且不打算先購置實體主機 | 仍須自行驗證 LaunchAgent、使用者會話、工具鏈與安全邊界 | 先核對連線方式、可用週期與 CI 要求,再決定用途 |
如果現有 Linux 節點無法執行 Xcode,個人 Mac 又容易因登出或其他工作中斷,而自購主機會增加維護負擔,租用遠端 Mac 可作為補上 macOS 執行節點的選項。KuzCloud 提供遠端 Mac 租用服務;在派送正式作業前,仍應依本文清單驗證存取方式、Runner 會話、工具鏈與隔離條件。若需求是長期高負載、要求特定實體介面,或不能接受遠端節點與使用者工作階段的限制,自行維護實體 Mac 可能更合適;若只需臨時取得 macOS CI 測試環境,可先比較遠端 Mac 與現行方案,再決定是否租用。
為持續整合流程配置專屬遠端 Mac
KuzCloud 提供 M4 實體獨占節點,讓 macOS 建置作業使用專屬硬體,避免與他人共享算力。
享有完整管理權限,可按流水線需求安裝工具、設定服務及執行建置。