Buildkite 企業 iOS CI 接入應由 Buildkite 編排流水線、Mac Agent 執行依賴 Xcode 的建置與測試；Linux 可執行的檢查則按實際依賴留在其他節點。若涉及生產簽署或不受信任程式碼，必須另行設計信任邊界，不能把佇列路由當成主機隔離。
這篇指南適合正在遷移 iOS 流水線、需要設計任務路由的 平台工程師。
負責 Mac 建置節點、執行帳號與維護責任的 企業 IT 主管，也可按步驟核對。
管理發布權限、簽署憑證及不受信任程式碼的 團隊負責人，可參考安全與驗收部分。
[ SECTION_01 ] 立項階段：先劃清 Mac 工作負載邊界
先按工作所需的作業系統與工具鏈拆分工作，不要把整條流水線一概搬到 Mac。Buildkite 負責編排工作；自託管 Agent 在所屬主機上接收並執行已路由的工作。可從 Buildkite Agent 工作方式與任務路由說明核對這項職責分工。
把每個步驟分成下列類型，再決定執行位置：
- Apple 平台專屬：需要 macOS、Xcode、模擬器或 Apple 簽署工具的建置、測試及發布工作，路由至 Mac。
- 平台無關：若程式碼格式檢查、部分靜態分析或文件檢查不依賴 macOS 與 Xcode，可留在現有執行環境。
- 需進一步驗證：依賴特定作業系統行為、工具版本或私有憑證的工作，先以真實專案確認依賴，再決定是否分流。
如此可避免不必要的 Mac 負載，也能把工具鏈問題與一般程式碼檢查分開排查。Apple 的 Xcode 命令列工具設定文件說明，命令列建置會使用所選定的開發工具目錄；因此，節點標籤或佇列名稱本身不能證明實際使用了哪套 Xcode。
[ SECTION_02 ] 準備階段：確認主機、使用者與憑證
在安裝前建立節點紀錄，至少保存 macOS 版本、晶片架構、Xcode 版本及目前選用的開發工具路徑。這些是後續定位「工作已派送，但找不到工具或建置結果不同」時的重要核對項目。請依 Apple 的 Xcode 命令列工具設定說明核對工具選擇方式，並在實際建置日誌中保存檢查結果。
同時明確指定 Agent 的 macOS 執行使用者。該帳號必須能讀寫工作目錄、存取必要的建置產物，並只取得工作所需的鑰匙圈權限。不能只因管理員帳號在互動式桌面上能成功建置，就推定背景 Agent 也有相同權限。
Buildkite 自託管 Mac Agent 應使用哪個 macOS 使用者？
應使用由團隊管理、權限符合工作需求的專用執行帳號；是否需要存取簽署材料，則按任務分開授權。不要直接沿用個人日常帳號，也不要讓所有工作都繼承管理員權限。這是架構建議，實際可讀寫路徑仍須以團隊主機政策和建置日誌驗證。
Agent Token、原始碼庫存取憑證與簽署材料也要分開管理。將各自的負責人、存放位置、可用範圍與撤銷流程記錄在團隊維運文件中；不得把祕密寫入設定檔、流水線程式碼或可能被保存的輸出。Buildkite 對 Agent Token 的用途與管理方式有專門說明，可用來核對接入時的 Token 管理責任。
[ SECTION_03 ] 安裝階段：設定 Agent 並證明它能持續工作
安裝步驟應以 Buildkite 當時的官方 macOS 文件為準，避免複製過期命令。依照自託管 macOS Agent 安裝指引完成安裝後，逐項確認：
- 安裝位置與設定檔由預期的管理者維護。
- Agent 使用預定的 Token 與佇列設定，沒有把祕密直接放入可提交的專案檔案。
- Agent 以準備階段確認的 macOS 使用者執行。
- Agent 啟動後能在 Buildkite 顯示預期的狀態，並能接收一項無敏感資料的測試工作。
手動在終端機啟動的 Agent，與由 launchd 管理的背景服務，不是相同的維運方式。前者依賴啟動它的工作階段；後者則須依照安裝文件設定服務管理。無論採用哪種方式，都要安排主機重新啟動後的實際工作驗證：畫面上仍有程序，不能單獨作為服務已恢復、佇列能正常派工及工作目錄可用的證據。
[ SECTION_04 ] 路由階段：用佇列和工作結果確認派送
把 macOS 建置節點放入團隊規劃的佇列，再為需要 Xcode 的步驟設定相符的路由條件。對照 Buildkite 佇列管理文件確認佇列配置；同時在建置記錄中查驗實際接單的 Agent 與任務執行環境。
Buildkite Mac Agent 如何接上企業 iOS 專案？
先讓專案能在 Agent 所屬節點完成原始碼檢出，再將 iOS 建置或測試步驟路由至 Mac 佇列。之後用一項代表性工作確認 Agent 接單、Xcode 可用、建置結果符合預期。只有佇列上線，並不能證明憑證可用、Xcode 選擇正確或產物已保留。
可用以下對照評估分流方式，評分是相對適配度，不是效能實測：
- 平台無關工作留在原有環境：適配度高於完全搬遷；可保留現有執行位置，減少不必要的 Mac 工作。
- 只把 Apple 專屬步驟送至 Mac：對多數需要 Xcode 的流水線較合適；路由設定必須與實際依賴一致。
- 只靠佇列名稱區分正式簽署和一般測試：安全適配度低；佇列描述任務分流，不代表主機、使用者、憑證或檔案系統已隔離。
注意：不要從佇列名稱推斷 macOS 版本、Xcode 版本或主機隔離狀態。這些資訊必須分別從節點設定、Agent 身分與實際工作結果核實。
[ SECTION_05 ] 治理階段：把一般測試、外部程式碼與正式簽署分開
先列出不同工作可以取得的資料與憑證，再決定能否共用執行環境：
- 一般建置與測試：只提供完成工作所需的來源碼及建置權限，檢查輸出是否意外包含憑證或其他祕密。
- 不受信任的拉取請求：限制其可取得的倉庫憑證與主機資源。若無法確認同機工作之間的隔離程度，不應讓它與持有正式簽署材料的工作共用敏感執行環境。
- 生產簽署與發布：另訂授權、簽署材料可用範圍、審批和日誌遮罩要求。將發布證據與一般測試結果分開保存。
Buildkite 佇列能否隔離 iOS 測試與生產簽署工作？
佇列可用來控制工作路由，但不能單獨視為主機級隔離。需要隔離的團隊還須檢視主機、執行使用者、憑證存取與工作間的邊界。可參照 Buildkite 安全檢查清單，再按企業實際安全政策確認控制項是否落實。
[ SECTION_06 ] 驗收階段：以完整 iOS 工作流作為放行依據
選一個能代表團隊實際工作的專案，按以下條件完成端到端驗收：
- 檢出：確認來源碼能由預定 Agent 取得，並核對使用的倉庫憑證與權限範圍。
- 工具鏈：檢查工作日誌，證明實際選用的 Xcode 與 macOS 符合專案需求。
- 建置：執行專案的
xcodebuild工作，保存命令、退出結果與可供追查的建置記錄。 - 測試：確認測試確實執行，而不是只看工作啟動成功；保留結果資料與失敗細節。Apple 的執行測試及解讀結果文件可協助核對測試結果的處理方式。
- 產物與簽署：確認建置產物有預期的保存位置；若流程包含歸檔與簽署，另行核對簽署身分、授權紀錄及發布審批。
- 恢復與維運：驗證主機重新啟動後 Agent 能恢復接單，並記錄日誌位置、工具鏈升級責任與故障聯絡方式。
如何確認 Buildkite 的 Mac Agent 使用了預期的 Xcode？
不要只檢查節點名稱或佇列設定。應在真實工作中記錄當前開發工具路徑與 Xcode 版本，並檢視 xcodebuild 的執行結果。若工作記錄與節點預期不一致，先修正工具選擇，再將驗收結果作為放行依據。
若現有流程只依靠 Linux 節點，限制在於它無法直接承擔依賴 macOS 與 Xcode 的工作；若改為自行採購 Mac，則須由企業承擔設備、更新、故障處理與存取管理。當工作量或節點需求仍在變動時，可把租用遠端 Mac 納入承載方式評估；它不會取代憑證治理或驗收流程，也不一定適合需要長期固定負載、實體介面或完全自主管理硬體的團隊。需要比較時，可先查閱 NOVAKVM 遠端 Mac 方案資訊，並在決策前核實當前交付、存取與維運條件；也可由 NOVAKVM 服務入口查看相關服務資訊。