CI/CD / DevOps

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 建置作業使用專屬硬體,避免與他人共享算力。

享有完整管理權限,可按流水線需求安裝工具、設定服務及執行建置。