GitHub Copilot cloud agent 預設使用標準託管 Runner。組織管理員也能為 cloud agent 指定 Runner 組或標籤；儲存庫是否可以覆寫組織預設值，則受組織設定控制。這代表「可以使用自架 Mac Runner」不等於每個 Agent 工作都必須改用 Mac。規則與設定入口請以官方 Runner 配置說明為準。

先把工作拆成三種，避免把 Runner 接入誤認為整條發布流程已完成：

• Agent 工作環境：Agent 開始處理工作時所使用的 Runner。若任務需要 macOS 專屬工具、Xcode，或只能從內部網路存取的依賴，才評估指定 Mac Runner。
• 專案準備步驟：環境自訂設定可在 Agent 工作開始前安裝或設定依賴；它不會自動取代組織 Runner 政策，也不代表建置已通過。
• 一般 GitHub Actions 工作流程與最終 Xcode CI 驗收：常規工作流程可有自己的 Runner 設定。Agent 修改程式碼、工作流程執行成功和發布流程驗收，是不同的結果。

決策條件：

• 若任務需要 Xcode、macOS 專屬指令或受控的內部資源，且組織允許安全地限制 Runner 存取，選用對應的 Mac Runner 組或標籤。
• 若工作只需一般程式碼編輯、標準命令列環境，或目前無法確保自架主機隔離，保留標準託管 Runner；不要為了「可能用到 Xcode」而開放 Mac 主機。
• 若只需要 Agent 預先安裝一般依賴，先評估環境自訂步驟，不要把它和指定 macOS Runner 混為一談。

開始設定前，確認組織管理員是否有權管理 Copilot 的 Runner 設定，以及目標 Runner 組允許哪些儲存庫使用。GitHub 的 Runner 組可以透過存取政策限制可用範圍；因此要先核對組織預設值、目標儲存庫和可能的覆寫權限，而不是只確認主機已上線。設定依據可參考Runner 組存取政策文件。

接著依專案列出需求，並逐項確認主機是否符合。不要只寫「需要 Xcode」：列明所需的 Xcode 版本、命令列工具、套件管理方式、私有套件來源，以及是否要連到內部服務。版本與支援範圍會變動，應以自架 Runner 支援文件及專案自身的工具需求核對，不要先假設某台 Mac 已備妥指定環境。

需要一併確認的實際限制包括：

• 網路可達性：Runner 必須能連到 GitHub 和任務所需的套件來源、內部服務；受限網路可能令 Agent 無法取得依賴，或使外部連線超出預期。
• 權限範圍：組織、Runner 組、儲存庫和工作流程的權限彼此相關。只要 Runner 組可被不適當的儲存庫使用，主機便可能暴露給不可信程式碼。
• 主機殘留：自架主機上的工作目錄、快取、登入狀態和暫存憑證，都要列入任務結束後的清理計畫。不能只以 Runner 顯示在線，推論執行環境已隔離。
• 工具與發布權限：安裝 Xcode 不等於已有簽署憑證、發布權限或可直接送審的產物。對憑證的管理和發布驗收要另行設計。

在組織層級選擇標準託管 Runner，或指定自架 Runner 組／標籤。接著確認目標儲存庫是否受到該組 Runner 的存取政策允許。這裡的關鍵不是儲存庫工作流程裡寫了什麼，而是組織是否允許該儲存庫使用指定 Runner、是否允許它覆寫預設值。

示意設定只能使用你自己的群組與標籤名稱，不要複製其他團隊的標籤：

Runner 組：<RUNNER_GROUP>
Runner 標籤：<MAC_RUNNER_LABEL>
目標儲存庫：<OWNER>/<REPOSITORY>

這是欄位示意，不是可直接套用的設定檔。實際值須與管理介面和主機註冊時使用的組別、標籤一致。若組織政策不允許儲存庫覆寫，工作流程自行指定不同 Runner 並不會自動取得該權限。反過來說，允許覆寫也應只授予確有需要的儲存庫，避免把選擇權無限制地交給工作流程。

GitHub 提供 Agent 開始工作前設定環境的方式，可用來準備專案相依項目；但不要以 setup workflow 代替 Runner 類型、權限或安全政策的確認。環境準備方式和適用限制請對照cloud agent 環境自訂文件。

GitHub Actions 自架 Mac Runner 的接入，應按官方流程註冊到正確的範圍，再確認所屬 Runner 組及標籤。依照新增自架 Runner 的官方步驟取得當前註冊指示；不要把主機名稱、群組名稱或憑證寫進公開文件或範例。

實際操作時，依序處理以下事項：

• 由有權限的管理者決定註冊範圍與 Runner 組，確認目標儲存庫能存取該組。
• 在 Mac 主機上依 GitHub 顯示的指示完成 Runner 註冊，核對主機在線狀態與套用的標籤。
• 從主機測試必要的 GitHub、套件來源和內部資源連線。無須存取的網路服務，應維持不可達。
• 以專案準備檔案設定 Agent 開始工作前所需的工具與依賴。避免將長效密鑰直接寫入檔案，並確認依賴下載來源可追溯。
• 分開記錄三種驗收結果：Runner 已註冊且在線、環境準備步驟完成、Xcode 或專案命令實際通過。任一項失敗都要保留日誌，不要以其他項目成功代替。

先選擇非生產或受控儲存庫，用最小任務確認 Agent 是否分配到預期的 Mac Runner。接著驗證儲存庫可讀取、專案準備步驟可執行，以及所需命令能找到正確工具。若專案需要 Xcode，再執行對應的建置或測試命令，保存完整輸出和失敗訊息。

場景案例：你的團隊在 Linux 上處理一般程式碼工作，但 iOS 專案的準備與建置依賴 Xcode。這時可把是否使用 Mac Runner 限定於需要 macOS 的 cloud agent 工作，再透過受控試跑檢查專案依賴和存取路徑。Agent 能修改程式碼，不代表建置成功；建置成功，也不代表簽署與發布已經驗收。

提醒：不要只看單次工作流程的綠色狀態。要確認執行紀錄顯示的是預期的 Runner、預期的工作區，以及預期的工具版本；若工作使用了不該存取的憑證或內部服務，應先停止擴大，而不是把它當成環境設定完成。

對 Xcode CI，驗收內容至少要涵蓋專案所需的命令、相依項目取得、建置或測試結果，以及失敗時可供排查的日誌。簽署、上傳和發布若不在本次試跑範圍內，明確列為未驗收項目。

在擴大使用前，把 Runner 組的儲存庫範圍、工作流程覆寫權限、憑證範圍、內部網路存取和工作後清理列入准入檢查。GitHub 的安全指引提醒，自架 Runner 會帶來主機與工作流程層面的風險，特別是執行不可信程式碼時；應以Actions 安全使用建議核對政策，並用實際試跑檢驗清理和存取控制。

• 啟用：只有在儲存庫存取受控、所需工具已驗收、憑證採最小權限且任務後清理經過檢查時，才讓指定儲存庫使用 Mac Runner。
• 限用：若自架主機可供 Agent 使用，但尚未證明適合不可信程式碼，將 Runner 組限制在信任明確的儲存庫，並保留標準託管 Runner 作為一般工作環境。
• 暫停：若無法隔離任務、清除工作殘留，或無法限制內部網路與憑證存取，先停止接入；不要用「Runner 在線」作為降低安全要求的理由。

相較於標準託管環境，自架 Mac Runner 的好處是能貼近 Apple 平台工具鏈及內部資源；代價是主機維運、存取控制和清理責任都落在團隊。對不需要 macOS 的工作，標準託管 Runner 往往更簡單；對需要 Xcode 的工作，只有在隔離與工具鏈驗收都過關後，自架 Mac 才是合適的選項。

如果團隊沒有可用的 Mac 試跑，或只需在導入期間取得遠端 macOS 環境，可先比較自行維護主機與短期使用遠端 Mac 的差異。自行購置或沿用設備需要處理硬體維護、長期閒置和遠端存取管理；Mac 虛擬環境則可能不符合 Apple 工具鏈或組織政策需求。你可以先閱讀 KVMNODE 遠端 Mac 方案，再依所在地參考香港方案資訊。若要租用，應先確認實際交付的 macOS 工具鏈、遠端存取方式和套餐週期是否適合你的試跑；本文不預設任何未核實的主機規格或 Xcode 配置。