Bitbucket Pipelines macOS Runner：2026 企業上線標準

macOS Runner 的關鍵風險，不是控制台上是否顯示「Online」，而是任務是否能在宿主機直接執行 Bash。官方的 macOS Runner 設定說明 應作為能力邊界的起點：Runner 可執行工作，但不等於每次工作都在全新、不可寫入的環境中執行。

假設某個前序任務把工具安裝到全域路徑、啟動常駐服務，或修改登入帳號的 Keychain。任務完成後，下一個工作可能讀到這些狀態。即使原始碼目錄已經清空，污染仍可能留在：

• 工作目錄以外的工具與設定檔；
• DerivedData、依賴快取與暫存目錄；
• 殘留的背景程序、網路服務與排程；
• 登入帳號的 Keychain、環境變數或 SSH 設定；
• 前一項工作的歸檔檔案與簽名輸出。

你要把「平台自動清理」和「團隊自行負責的清理」分開記錄。只驗證工作區被刪除，不能證明宿主機已恢復到可重複狀態。

遇到不可信倉庫或外部貢獻程式碼時，應如何處理？
不要只依賴一段清理 Shell。把不可信工作送到獨立 Runner 池；測試、歸檔與正式簽名也應按信任邊界拆分。若任務必須具備較高的檔案、Keychain 或發布權限，就不應與一般測試共用同一台可寫入的 Mac。

注意： 清理是殘留控制，不是安全隔離。只要任務能在宿主機取得更高權限，清理失敗或遺漏一次，就可能影響後續工作。

Runner 的範圍決定「誰可以呼叫這台 Mac」。Repository Runner 的授權半徑較窄，適合單一程式庫或單一產品線；Workspace Runner 可供工作區內多個程式庫使用，因此必須先確認哪些倉庫有資格使用它。註冊時可參考 新增 Runner 的官方流程，但不要把完成註冊誤當成完成授權設計。

建議至少建立以下節點池：

• 一般測試池：執行單元測試、靜態分析和不涉及發布的工作；
• 受控歸檔池：具備固定 Xcode、依賴和輸出留存規則；
• 正式簽名池：只接受已審核的倉庫與分支；
• 不可信工作池：不接觸正式憑證、發布權限或其他倉庫快取。

標籤必須表達信任邊界，而不是只表達硬體名稱。下列片段只保留路由驗收所需的最小結構：

pipelines:
  branches:
    main:
      - step:
          name: Archive
          runs-on:
            - self.hosted
            - macos
            - signing

實際標籤語法與可用標籤，應以 YAML Runner 路由文件及目前註冊介面為準。你要測試三種負面情況：錯誤標籤、目標節點忙碌、沒有匹配節點。每次都要確認工作是等待、失敗或被拒絕，而不是靜默轉到權限較高的節點。

Workspace Runner 要怎樣避免不同程式庫互相越權？
先限制 Workspace Runner 的可使用範圍，再以標籤劃分工作類型。對每個倉庫建立允許使用的節點池清單，並用一條故意使用錯誤標籤的流水線驗證拒絕結果。若無法提出倉庫、標籤、節點池三者的對應證據，就不應把它用於正式簽名。

macOS、Xcode、SDK、依賴工具與執行帳號必須形成一份可核對的環境基線。Xcode 命令列工具的可用指令與行為，應對照 Apple 官方命令列工具參考確認；不要只保存一張桌面截圖或一個模糊的「最新版本」標籤。

每台候選節點至少要記錄：

• macOS 與 Xcode 的實際版本；
• SDK、Swift／Objective-C 工具鏈和套件管理器狀態；
• 執行帳號、Shell、環境變數和權限；
• 依賴解析來源、快取位置與失效條件；
• 可用的 Apple Silicon 架構與必要的模擬器配置；
• 清理前後的工作目錄、DerivedData 和背景程序狀態。

Bitbucket macOS Runner 能否用於 iOS 發布？
可以，但前提是發布任務被送到受控的專用節點，並通過簽名、清理、權限和恢復驗收。Runner 能執行工作，不代表 Xcode 環境、Apple 憑證、輸出保管和取消任務處理已達到發布要求。

用同一個提交執行重複構建，至少觀察四項證據：依賴是否重新解析、快取是否命中、產物是否符合團隊定義的一致性、清理後重新執行是否仍可完成。不要把 Linux 或其他雲端 Pipeline 的設定直接複製到 macOS；檔案路徑、Keychain、Xcode 工具和簽名流程都可能不同。

Runner 註冊憑證、程式碼存取憑證、Apple 簽名材料與發布權限必須分開管理。Bitbucket 的 變數與密鑰文件可用於核對秘密注入方式，但秘密不應直接寫入倉庫、YAML 或通用 Shell。

簽名材料的驗收重點不是「能否成功打包」，而是生命周期是否可追蹤：

1. 憑證如何匯入；
2. 哪個帳號可以使用；
3. 任務完成後如何清除；
4. 何時輪換；
5. 發現外洩時如何撤銷；
6. 誰可以查閱操作記錄。

Apple 對程式碼簽名憑證的結構與信任關係，可參考 TN3161 技術說明；發布產物則應按 Apple 的簽名文件核對實際流程。

你要特別驗證不同標籤、不同倉庫的任務無法讀取其他節點池的 Keychain、環境變數、快取和歸檔產物。若簽名池的工作可以看到一般測試池殘留資料，這不是清單上的小缺口，而是正式放量的阻斷項。

經驗： 「密鑰沒有出現在日誌」只代表一種洩漏路徑被遮蔽。你仍須驗證檔案、程序、快取、歸檔目錄和取消任務後的清除結果。

無人值守恢復必須用故障注入驗證，而不是查看服務啟動項目。你應分別測試 Runner 程序退出、Runner 離線、Mac 重啟、網路中斷和任務取消。每項測試都要記錄事件時間、日誌、重新連線狀態、遺留程序與下一項任務的接單結果。

自託管 Runner 離線後怎樣判定已恢復？
不能只看狀態重新顯示線上。你還要確認它能接收預期標籤的工作、未重播被取消的任務、沒有帶入上一項工作的檔案與憑證，並能在無人登入桌面的條件下完成必要服務啟動。排隊和並行行為應對照官方併發與步驟佇列說明核對。

容量也不能按開發者人數或晶片宣傳參數直接採購。你需要從實際任務取得：

• 構建時長分布；
• 歸檔與簽名工作的峰值佇列；
• 每個節點可接單的有效產能；
• Xcode 或依賴下載造成的等待；
• 節點故障時剩餘池的承載能力；
• 恢復期間允許的佇列延遲。

放量條件分支

• 若工作可修改宿主機，且沒有專用節點與清理證據，則回退到隔離的非生產節點，不得進入正式簽名。
• 若Workspace Runner 的授權倉庫、標籤和拒絕測試均有記錄，則可進行受控歸檔；否則改用 Repository Runner。
• 若清理、憑證撤銷、重啟和網路中斷測試全部通過，則先限量放量；任一項失敗就退回整改。
• 若峰值佇列與故障冗餘尚未由真實任務證明，則不要按預估團隊規模直接增加 Mac 節點。
• 若發布任務需要物理介面、特殊周邊或本地人工操作，則先保留本地設備方案，不要強行改成遠端 Runner。

以下表格用於決定節點應停留在哪個階段。它不是安裝清單；每個「通過」都必須附上日誌、設定快照、任務輸出或存取記錄。

固定節點與遠端 Mac 的取捨

對企業來說，當前的自購方案常見缺點是資本支出先發生、容量擴充速度受採購流程限制，而且故障重啟、硬體盤點和 macOS 環境維護會持續佔用 IT 人力。若你現在缺的是可審核的試點節點或短期構建容量，CALMVPS 的遠端 Mac 更適合先承接這一段工作；你仍應依本文驗收隔離、憑證清除與恢復能力，而不是因為遠端形式就跳過生產准入。

建議你先在隔離的 Mac 節點跑一條非生產流水線，保存路由、清理、簽名和故障測試證據。若共享環境、憑證清除與無人值守恢復均已通過，再評估固定節點或 CALMVPS 的遠端 Mac 方案；如果工作是長期穩定的高負載，或必須接觸實體介面，自購設備可能仍更合理。你也可以先查看 CALMVPS 的方案與週期資訊，再按驗收結果決定容量，而不是先把正式發布任務一次性遷移過去。