GitLab CI Mac Runner 怎麼搭？2026 部署驗收指南

結論：GitLab CI Mac Runner 部署可行，但 Apple 平台工作常用的 Shell executor 隔離能力有限，且 GitLab 將它列為維護模式；先在專用、可信的 Mac 節點試跑，不要直接讓共用或接收不可信程式碼的節點承載正式任務。GitLab 的執行器狀態說明與Shell executor 文件均列出相關限制。

適用對象：
iOS／macOS 開發者：想把現有專案的構建或測試交給 GitLab CI 的 Mac 節點。
DevOps 工程師與研發平台、安全負責人：需要註冊、維護 Runner，並判斷執行與重啟行為是否符合團隊安全要求。

SECTION 01第一步：先判斷哪些工作值得放上 Mac Runner

GitLab Runner 可以安裝在 macOS，Apple 平台構建也可使用 Shell executor。這不表示所有 CI 工作都應搬到 Mac：先把必須呼叫 Xcode、macOS 專屬工具或 Apple 平台測試環境的工作列出，再與可由現有通用 CI 節點處理的工作分開。GitLab macOS Runner 安裝文件說明 macOS 安裝方式；執行器文件則說明 Apple 平台工作可採用 Shell executor。

對既有流水線而言，較容易驗收的起點是保留通用工作原有的執行環境，只把確實依賴 macOS 的 job 指派給帶有專用標籤的 Mac Runner。這能減少不必要的環境遷移，也讓你可以單獨觀察 Apple 平台工作是否通過，而不是把整條流水線改動與工具鏈故障混在一起。

場景案例：若測試、程式碼檢查和一般套件工作原本已在其他節點穩定執行，你可以先只遷移 Xcode 構建與測試 job。若該 job 無法在專用節點上完成倉庫檢出、工具鏈辨識和真實專案構建，就先不要擴大標籤的使用範圍。

Shell executor 的主要好處是直接在 macOS 使用者環境中執行，便於呼叫已安裝的開發工具；代價是它不是隔離容器，工作內容與執行帳戶、工作目錄及節點上可存取的資源有更直接的關係。若工作可能包含不可信程式碼，或必須和高權限簽署資產隔離，就不應把這種 executor 當成安全邊界。

SECTION 02第二步：準備獨立節點與可追溯的工具鏈

不要把共享的個人工作環境直接註冊為執行節點。先決定專用帳戶、節點用途、可執行的專案範圍，以及故障時如何停用 Runner、撤銷憑據並將工作切回原有流程。尤其要先確認倉庫與程式碼來源是否可信；只靠 Runner 標籤本身，不能建立使用者或安全隔離。

接著在節點上記錄實際選用的 Xcode 開發者目錄與工具版本。Apple 的命令列工具參考提供 xcode-select 與 xcodebuild 等工具說明；工具安裝則依Apple 命令列工具安裝文件及你實際的專案需求核對。不要只記錄「已安裝 Xcode」，還要確認工作執行時使用的目錄與版本。

xcode-select -p
xcodebuild -version

把命令輸出保存在節點驗收紀錄中，並確認 Runner 執行帳戶有權讀取預期的開發者目錄、專案檔案和必要資源。若 xcode-select -p 指向非預期位置，或 CI 日誌中的 xcodebuild -version 與團隊基線不一致，先修正工具選擇再註冊正式工作；不要用「本機終端機能構建」代替 Runner 帳戶的驗證。

提醒：Apple 平台的命令列構建能否執行，取決於節點實際安裝和選取的工具鏈。不要只根據 Runner 顯示在線，就推斷 Xcode、專案 Scheme 或簽名環境都已就緒。

SECTION 03第三步：在已登入的 macOS 工作階段安裝與註冊

依照GitLab macOS 安裝流程安裝 Runner，再按照Runner 註冊說明連接 GitLab 專案或群組。註冊時只使用你需要的範圍，將敏感資料以環境變數或安全的機密管理方式提供；以下的 URL、標籤和權杖都只是佔位符，不能把真實權杖提交到程式碼庫。

gitlab-runner register \
  --url "<GITLAB_INSTANCE_URL>" \
  --token "<RUNNER_TOKEN>"

在提示中選擇符合節點用途的 Shell executor，並確認 Runner 的標籤只會匹配預期工作。不要把實際權杖寫進 YAML、操作紀錄或可由其他專案讀取的檔案。完成註冊後，先檢查 Runner 設定和 GitLab 端的專案關聯，再用最小工作驗證它是否真的接受並執行 job。

macOS 的工作階段行為是部署設計的一部分：GitLab 說明此 Runner 以使用者層級的 LaunchAgent 執行，依賴已登入的使用者工作階段，不能當成 LaunchDaemon。GitLab 的 macOS 文件說明這項服務行為。這會影響使用者登出、節點重啟及工作階段恢復後的可調度性；自動登入則可能增加實體存取風險，應先依安全政策評估，不要把它當成預設解法。

SECTION 04第四步：用最小流水線驗證真實 Xcode CI

先建立一個只面向該節點標籤的最小 job，確認倉庫檢出、執行帳戶、標籤匹配和工作日誌都正常，再加入實際專案的構建命令。以下只是示意；請替換專案、標籤、Scheme 與路徑，並按專案類型調整構建目標。

macos_build:
  tags:
    - "<MAC_RUNNER_TAG>"
  script:
    - whoami
    - pwd
    - xcode-select -p
    - xcodebuild -version
    - xcodebuild -project "<PROJECT_PATH>" -scheme "<SCHEME>" -sdk iphonesimulator build

逐項看日誌，而非只看 job 是否啟動。whoami 和 pwd 用來核對執行帳戶與工作目錄；xcode-select -p 和 xcodebuild -version 用來確認實際工具鏈；最後的構建命令則要針對真實專案及預期 Scheme 執行。若專案需要額外的簽署、測試或建置參數，也要在隔離的試跑範圍內逐步加入，避免一次引入多項變數。

驗收時要分清幾種狀態：Runner 顯示在線，只代表它可被 GitLab 看到；job 被指派並開始執行，才表示任務已調度；工具鏈命令輸出符合基線，才表示 Xcode 選擇正確；真實構建通過，才是專案工作有效的證據。這些結果不能互相替代。

SECTION 05第五步：擴大任務前檢查憑據與隔離

執行工作會使用 Runner 帳戶可讀取或可操作的資源，因此正式接入前要逐項確認：

• 倉庫存取範圍是否只涵蓋預期專案；不要讓不相關工作因為共享標籤而被送到此節點。
• 工作目錄與檔案是否可能殘留憑據、建置輸出或簽署相關資料；確認清理方式適合你的安全要求。
• Keychain、簽署資產與相關憑據是否只對必要工作開放；避免讓一般構建 job 取得高權限簽署能力。
• 專案是否只執行可信任的程式碼；若不能確保來源可信，停止將工作派到這個 Shell executor 節點。

GitLab 的自託管 Runner 安全文件與 Shell executor 說明指出，這種執行方式的隔離能力有限；因此不要把它當成隔離容器，也不要假設標籤、工作目錄或 CI 設定會自動阻止程式碼存取 Runner 帳戶可用的資源。

如果團隊需要承載來源不可信的工作，或要求工作間具有更明確的隔離邊界，先評估其他受支援的執行拓撲及其對 macOS 工具鏈的適配性，再決定是否使用共用節點。對高權限簽署任務，若憑據範圍、節點存取方式或工作清理尚未通過審查，就暫停接入，而不是把風險留給上線後處理。

SECTION 06第六步：重啟復測，再決定試跑或正式使用

安裝與首次構建通過後，分別測試使用者登出、系統重啟及 Runner 服務狀態變更後的行為。每次都從 GitLab 端重新觀察 Runner 狀態，送出一個無敏感內容的測試 job，記錄是否恢復連線、是否被調度，以及工具鏈輸出是否仍符合基線。由於此 Runner 依賴已登入的使用者工作階段，重啟復測必須在實際預定的帳戶和節點設定下完成，不能以另一個終端機工作階段的結果代替。

作為上線決策工具，逐項確認以下條件；任一關鍵項未完成，就先維持試跑或調整執行方案：

• [ ] 節點用途、Runner 帳戶、可接收的專案與程式碼信任範圍均已記錄。
• [ ] Runner 已註冊，標籤只匹配預期的 macOS 工作。
• [ ] CI 日誌能核實工作目錄、執行帳戶、開發者目錄及 Xcode 版本。
• [ ] 真實專案的構建或測試已成功，而非只有 Runner 在線或 job 已啟動。
• [ ] Keychain、簽署資產、工作目錄殘留與憑據權限已完成審查。
• [ ] 登出與重啟後的恢復行為已實測；若不能恢復，已有可執行的回退方式。

若專案構建已通過，但使用者退出後 Runner 無法接受任務，這代表持續執行條件仍不成立，不應把它記為完整驗收。若登入會話、安全政策或隔離能力與團隊要求不符，就暫緩共用並調整節點拓撲；若只需短期驗證，則限定專案和工作範圍，先保留原有 CI 路徑作為回退。

SECTION 07常見問題

GitLab Runner 可以安裝在 macOS 嗎？

可以，GitLab 有 macOS Runner 的安裝與設定文件。部署成功後仍要確認執行帳戶、工作階段、倉庫信任範圍和 Xcode 工具鏈；最小 CI job 通過真實專案構建後，才有足夠證據考慮擴大使用。

Apple 平台工作該選哪種 executor？

Shell executor 是 macOS Apple 平台工作常見的選擇，但它不是隔離容器，且處於維護模式。只在專用、可信的節點試跑；如果工作來源不可信或需要更強隔離，應先評估其他受支援的執行拓撲，不要把 Shell executor 誤當安全邊界。

Mac 登出或重新啟動後，Runner 會自動工作嗎？

不能一概而論。macOS Runner 以使用者層級的 LaunchAgent 運行，依賴登入中的使用者工作階段；登出或重啟後是否恢復，要在目標節點驗證。自動登入有安全取捨，不應未經審查就啟用。

怎樣確認工作使用預期的 Xcode？

在 CI 日誌中執行 xcode-select -p 與 xcodebuild -version，核對開發者目錄和工具版本，再執行實際專案的構建命令。只有真實工作使用預期 Scheme 並成功完成，才能確認工具鏈可用；Runner 在線不等於 Xcode 構建已驗收。

如果你現有的 CI 節點不是 Mac，直接在共用個人電腦上執行會增加工作環境與憑據混用的風險；自購 Mac 則需要承擔前期硬體投入和後續節點維護。若只是短期試跑、驗證 Apple 平台工作或暫時補足 Mac 執行環境，租用真實 Mac 可避免先購置專用硬體；但長期穩定的高負載工作、必須使用實體介面的任務，仍應先比較自有設備與其他合適方案。你可以先查看 MACNOX 的方案與費用資訊，確認實際可用選項，再由 MACNOX 訂購頁面了解租用流程；安全邊界尚未驗收前，先不要擴大 CI 任務範圍。

SECTION 08常見問題 FAQ