CircleCI Machine Runner 3 遷移：2026 macOS 驗收清單

直接停掉舊服務再安裝新 Runner，至少會暴露以下幾個獨立風險：

• 服務殘留：舊 launch agent 的服務檔案、安裝目錄或背景進程仍在，可能與新服務爭搶任務，亦可能讀取不同的設定檔。
• 配置語意改變：舊有 config.yaml 能夠載入，不代表 working_directory、清理策略、命令前綴、執行使用者或快取行為完全一致。
• 路由錯誤：namespace、resource class、認證令牌或專案設定對錯位置，會令普通測試任務進入承載生產簽名材料的 Mac。
• 權限與殘留：工作目錄、SSH checkout key、臨時 Keychain、Provisioning Profile 和建置產物若未清理，下一個任務可能讀取前一個任務的資料。
• 恢復失敗：服務重啟後未重新接單，或網路短暫中斷後留下不完整任務；若沒有備用節點，回退只能靠人工臨時處理。

試點前至少建立一張責任盤點表，列出遷移對象、依賴它的流水線、維護窗口、負責回退的人員、備用節點和驗收證據位置。這一步不是行政工作，而是把「切換失敗時誰能在什麼條件下恢復」變成可執行決策。

CircleCI 官方將 Machine Runner 3 列為舊版 launch agent 的替代方案，但官方遷移指引並沒有把「可替代」解釋成零風險原地升級；企業仍須依文件停止及移除舊服務，再依 macOS 安裝步驟建立新 Runner。

驗收時只保留理解流程所需的最小操作：

1. 凍結試點範圍：先選一台不承載正式發佈的 Mac，暫停把新專案導入，並記錄目前執行中的流水線與簽名用途。
2. 停止舊 launch agent：依官方遷移文件停用舊服務，確認服務檔案、安裝目錄和背景進程不再存在；不要把舊啟動方式留作「備用」而與新服務並行。
3. 安裝新 Runner：依官方 macOS 安裝指南取得安裝產物，記錄二進位檔來源、版本、檔案雜湊、簽名與 notarization 檢查結果，以及完整安裝日誌。
4. 確認執行身份：核對服務實際使用的帳號、工作目錄擁有者、Keychain 存取權和私有網路權限；不要假設互動式登入帳號與背景服務帳號相同。
5. 驗證服務狀態：重啟服務後同時查閱 Runner 狀態與本機服務日誌。只有在能夠穩定接收測試任務時，才進入配置和路由驗收。

安裝產物的簽名與 notarization 是供應鏈驗證項目，不是 CircleCI 服務「在線」狀態的替代指標。若版本、安裝方式或支援平台條件在官方 changelog 發生變更，企業應重新核對，不應沿用舊有內部文件。

Machine Runner 3 的設定應以官方配置參考逐項比對。重點不是把舊檔案複製過去，而是找出舊配置依賴了哪些未明寫出的環境假設。

驗證清單如下：

• [ ] working_directory 指向試點專用路徑，且執行帳號可讀寫。
• [ ] cleanup_working_directory 的行為符合企業清理政策，並實際測試成功、失敗和中斷任務。
• [ ] Runner mode、command_prefix 和任務最長執行時間均已對照目前官方欄位說明。
• [ ] 舊配置中的路徑替換、環境變數和檔案權限，已在新服務帳號下重新驗證。
• [ ] task-agent 快取不會把程式碼、簽名材料或跨專案產物留在共用位置。
• [ ] 基準任務不含生產令牌，只驗證 checkout、建置、日誌、退出碼和產物回傳。

基準任務應故意保持簡單，因為其目的是隔離 Runner 行為，不是測量整個 iOS CI/CD 的效能。若基準任務成功但正式流水線失敗，應回到環境變數、Xcode 工具鏈、Keychain、私有網路和產物權限逐項排查，而不是立即判定 Runner 安裝失敗。

路由驗收必須同時測試「應該允許」和「應該拒絕」的情況。企業可把可呼叫 macOS resource class 的專案範圍收窄至可信發佈流水線，再以組織級策略限制一般測試專案；相關控制方式應對照 CircleCI 自託管 Runner 配置策略文件。

注意： 若同一台 Mac 同時承載正式簽名與一般測試，清理失敗的影響不只是殘留檔案，而可能擴大成跨專案讀取或簽名材料外洩。生產簽名應優先使用專用執行帳號和專用 resource class。

兩個隔離測試專案是最低限度的交叉驗證方式：第一個建立可辨識但不敏感的檔案與環境標記，第二個在新任務開始時嘗試讀取；測試必須確認讀不到前一任務的程式碼、變數、SSH checkout key、臨時 Keychain、Provisioning Profile 和產物。若節點保留快取，還要區分「可重用的公開依賴」與「不可跨專案保留的機密資料」。

服務顯示在線只是起點，生產驗收還要證明故障後能恢復，而且不會造成重複發佈。建議在維護窗口依下列順序執行：

1. 從遠端執行正常重啟，確認服務可重新載入配置並接收測試任務。
2. 終止 Runner 進程，確認服務管理機制能否恢復；若不能，記錄需要的人工動作和權限。
3. 暫時中斷網路連線，再恢復連線，觀察任務是否正確失敗、重試或回到佇列。
4. 執行超時任務，確認工作目錄、子進程和暫存簽名材料在結束後均被清理。
5. 執行一次完整但不觸發正式發佈的基準流水線，記錄排隊、執行結果、失敗原因和人工恢復動作。
6. 模擬試點失敗，實際走過「回復舊服務」或「切換備用節點」其中一條路徑，並由指定責任人確認結果。

不要在沒有本站實測記錄時填寫吞吐量、併發數、恢復秒數或成功率。應以真實基準流水線產生證據，再根據佇列壓力與發佈 SLA 決定固定生產節點是否需要搭配可按需增加的遠端 Mac 容量。若要先了解 NUKCLOUD 可提供的遠端 Mac 存取方式，可參考遠端 Mac 使用說明，並把試點節點與正式簽名節點分開採購和管理。

每台節點完成測試後，應只輸出以下三種結論之一，而不是以「Runner 在線」作為模糊通過標記：

• 若服務切換、路由、清理、簽名隔離、重啟恢復和回退演練全部通過，則選擇分批放量。 先移轉低風險流水線，再加入正式發佈任務，持續保存日誌與驗收證據。
• 若功能通過但容量、私有網路或人工恢復仍有限制，則選擇限制放量。 只允許已核准專案使用，並以備用節點承接高優先級發佈。
• 若任何專案能讀取前一任務資料、服務無法在重啟後接單，或回退路徑未演練，則回到備用節點並退回整改。 不應透過臨時修改配置或同時保留兩種啟動方式來掩蓋問題。

這套分支也能協助技術總監判斷是否需要增加隔離 Mac：當唯一節點無法在維護或故障期間維持發佈 SLA，就不應只加快單機遷移，而要先建立第二個信任邊界清楚的節點。

FAQ 的完整回答如下，適合在企業變更單或遷移 Runbook 中直接引用。

舊版 launch agent 的遷移是否只是重新安裝 Runner？

不是。官方遷移流程涉及舊服務的停止與移除、新 Runner 安裝、設定檔核對和服務狀態驗證；企業還必須自行驗證任務路由、執行帳號、工作區清理、簽名憑證及故障回退。設定檔可讀取，不能取代實際流水線驗收。

macOS 重啟後沒有接單，首先應該查什麼？

先查服務是否由預期的啟動方式載入，再核對執行使用者、設定檔權限、工作目錄、網路連線和服務日誌。不要只看 CircleCI 控制台上的 Runner 狀態；若本機服務沒有正常恢復，應先切到備用節點，避免在生產主機上臨時混用舊服務與新服務。

舊有 config.yaml 能否直接沿用？

只能把它當作比對起點，不能當作通過證據。應逐項核對工作目錄、清理設定、Runner mode、命令前綴、任務時限、環境變數、檔案權限和 task-agent 快取，再用不含生產憑證的測試任務確認退出碼及產物回傳。

如何驗證自託管 Mac 不會殘留程式碼和簽名材料？

以兩個隔離專案執行交叉測試，並分別檢查工作目錄、快取、SSH checkout key、臨時 Keychain、Provisioning Profile 和產物。測試不能只涵蓋成功流程；失敗、超時和中斷後也要驗證清理結果，並記錄執行帳號、檔案權限與人工覆核者。

沿用現有 Mac 的優點是既有工具鏈和私有網路通常較容易保留，但舊 launch agent 殘留、單機維護窗口和硬體故障會讓回退變得困難；若再把測試、簽名和正式發佈混在同一節點，清理與權限邊界也更難證明。直接購置新 Mac 則需要承擔採購週期、資產折舊、機房維護和閒置容量，短期試點尤其不划算。

較穩妥的做法，是先申請一台與生產環境隔離的 NUKCLOUD 遠端 Mac，透過 VNC、SSH 或網頁控制台完成 Machine Runner 3 試點，讓團隊在不動唯一生產建置機的情況下測試重啟、憑證清理和任務路由。若試點通過，再依佇列與發佈 SLA 決定長期節點數量；可從NUKCLOUD 遠端 Mac 方案開始評估，而不是把整個遷移風險一次壓在現有主機上。