官方 FAQ 已明確列出 macOS Runner 不支援 Agent Workflows：原因是 Agent Workflow Firewall 所需的容器作業無法在 macOS Runner 上執行。結論：不要讓 GitHub Agentic Workflows 直接呼叫 Xcode；讓 Agent 在受支援的 Linux Runner 處理倉庫工作，再交給獨立的一般 GitHub Actions macOS 工作流建置與測試。（官方支援限制與替代做法）
適合維護 gh-aw 倉庫自動化的工程師：確認 Agent 能否承擔 Xcode 任務，以及該把哪些工作交給 macOS。
適合負責 Apple 平台 CI 的開發者與平台負責人：設計建置測試流程，並核對 Agent 與 Mac Runner 間的提交、產物和權限邊界。
截至 2026 年 10 月 25 日，官方文件所述的限制仍是這套拆分架構的起點；發布前請再核對官方 FAQ與Runner 設定文件是否已有更新。
SECTION 01部署前：劃清執行環境邊界
GitHub Agentic Workflows、一般 GitHub Actions 工作流和 Xcode 工具鏈不是同一種執行環境。把它們混為一談，常會造成工作流寫好了，實際執行卻卡在 Runner 支援或憑據權限上。
gh-aw CLI 可以安裝在 macOS，不代表 Agent 工作流就能在 macOS Runner 執行。CLI 的安裝平台，與 Agent 工作流執行時所需的容器環境，是兩個不同問題；官方指出，Agent Workflow Firewall 需要容器作業，而這項要求無法在 macOS Runner 上滿足。因而，Xcode 專屬步驟應由獨立的一般 GitHub Actions macOS 作業執行，而不是把 Agent 作業改寫成「Mac 上的 gh-aw」。
GitHub Agentic Workflows 為何不能直接用 macOS Runner？限制在 Agent 工作流的執行與防火牆環境，不是因為 Xcode 無法安裝，也不是因為 gh-aw CLI 無法在 Mac 上使用。請把 Agent 負責的倉庫分析、自動化修改，和需要 Apple SDK、Simulator 或簽署環境的建置測試分開；官方工作流機制說明有助於你確認 Agent 工作流實際如何執行。
在部署前先列清楚輸入與輸出，避免 Agent 和建置工作各自猜測要處理哪一版程式碼：
- Agent 可處理：分析 issue 或變更、提出程式碼修改、產生摘要，並輸出供後續工作流消費的分支或提交識別資料。
- macOS 工作流負責：取得指定提交，執行 Xcode 建置與測試，保存建置結果或可交付產物。
- 雙方事先約定：觸發來源、分支、提交 SHA、產物名稱、建置結論與回報位置；每一項都要標明由哪個工作流產生、由哪個工作流核驗。
SECTION 02首次試跑：先驗證 Linux Agent 工作流
先用不需要 Xcode 的小任務，驗證觸發、權限、Agent 輸出和執行記錄。這能把「Agent 沒有照預期產生交接資料」與「Mac 建置失敗」分開診斷，避免尚未確認上游輸出，就開始排查工具鏈。
依官方流程檢查工作流定義、編譯結果與鎖定檔，再確認所選 Agent 引擎及其認證設定。Runner 相關設定應按frontmatter 參考文件核對；不要假設本機安裝的 CLI 會改變雲端工作流的 Runner 支援範圍。
試跑時，為交接資料定義明確欄位，例如上游工作流識別、head SHA、分支、輸出檔名和執行結論。名稱可使用不含秘密的占位值，像是 BUILD_SHA、ARTIFACT_NAME；不要把 Token、簽署憑據或其他秘密寫進 Agent 輸出，也不要讓後續工作流把文字摘要當成已驗證的程式碼版本。
SECTION 03接入建置：讓一般 macOS 工作流執行 Xcode
Xcode CI 應放在一般 GitHub Actions 工作流，並讓它清楚取得要建置的提交。若 Agent 與 Mac 建置作業在同一個工作流中，可用明確的作業相依關係安排先後，再把上游作業輸出交給建置作業；若分開成不同工作流，則需設定觸發條件，並在下游重新核驗上游執行與提交資料。
GitHub Agentic Workflows 要怎麼把工作交給 Xcode 建置？Agent 工作流先產出已約定的分支或提交資訊；一般 macOS 工作流再取得該提交、執行 Xcode 任務，並將結果回傳到可追蹤的位置。這是工作流間的交接，不是 Agent 作業切換到 macOS Runner。
設計觸發時，逐項確認上游工作流名稱、事件類型、分支條件和下游工作流實際取得的 SHA。特別是 workflow_run：它在上游工作流完成後觸發，但下游工作流檔案必須存在於預設分支，而且下游執行環境與上游提交的關聯不能只靠「剛好是最新一次」推定。請對照工作流事件文件，確認觸發條件及事件資料欄位。
SECTION 04交接驗收：核對產物來源與權限
在同一工作流內，作業可透過 Actions artifacts 傳遞檔案；跨工作流時，下游需要明確指定要下載的上游執行產物，而不是取用名稱相同、來源不明的檔案。GitHub 說明了產物儲存與分享機制，而download-artifact 文件則可用來核對跨執行下載所需的參數。
每次交接至少逐項檢查：
- 上游工作流名稱與執行識別，是否符合預期。
- 上游 head SHA、分支，以及下游實際 checkout 的 SHA 是否一致。
- 上游工作流結論是否允許進入建置；失敗或取消時，下游是否會停止或明確標示狀態。
- 下載的 artifact 是否來自指定執行，而非其他分支或先前執行。
- 下游工作流是否只取得必要權限，且沒有把秘密交給未經信任的程式碼。
workflow_run 特別需要檢查權限提升風險：下游工作流可能取得較高權限或 Secrets，因此不能只因上游已完成，就信任其產物或直接執行其中內容。對從不可信來源取得的程式碼，應先隔離檢查，限制憑據與寫入權限；安全設定可參閱GitHub Actions 安全使用指南。
gh-aw 與 macOS 工作流如何傳遞建置產物？同一工作流可用 artifacts 傳遞檔案；跨工作流則指定上游執行並下載其產物，之後比對 SHA、分支與執行結論。若建置工作會執行產物中的程式碼，還要先確認該內容可信，不能把「成功下載」當作安全驗收。
SECTION 05上線判斷：以完整執行結果決定架構
用真實專案走完 Agent 修改、Mac 建置、測試結果回傳，再檢查失敗是否能正確傳遞、產物能否追溯到來源提交、權限是否符合最小需求。只要 SHA 對不上、失敗被吞掉，或下游拿到不明來源的產物，就先隔離試跑，不要直接接入發布流程。
| 方案 | 適用工作 | 優點 | 主要限制與驗收條件 |
|---|---|---|---|
| Linux Agent + 一般 macOS CI | Agent 做倉庫自動化，Mac 執行 Xcode 建置與測試 | 符合官方建議的職責拆分；可分別追蹤 Agent 與建置結果 | 必須明確核對 SHA、產物來源、觸發條件與下游權限 |
| 只保留一般 macOS CI | Agent 並非必要，或自動化修改暫不可靠 | 執行路徑較直接，減少跨工作流交接點 | 不會自動處理 Agent 的倉庫任務；仍要驗證建置環境與憑據 |
| 隔離試跑 | 工作流權限、產物來源或失敗傳播尚未驗證 | 可在不影響發布流程下收集執行證據 | 不應讓試跑產物直接進入正式發布或取得不必要 Secrets |
workflow_run 觸發 Mac 建置時，怎麼核對上游提交？以事件中的上游執行資訊為線索，明確確認 head SHA 和分支，再要求下游 checkout 同一個 SHA；同時核對工作流名稱、完成結論與 artifact 所屬執行。若任何欄位缺失或不相符，就停止建置並保留記錄，不能以分支名稱或最新提交替代精確核對。
第二張表可直接用作上線前的交接驗收紀錄：
| 驗收項目 | Linux Agent 交付 | macOS 工作流核對 | 不符合時的處理 |
|---|---|---|---|
| 提交 SHA | 輸出預期 SHA | checkout 後再次比對 | 停止建置並查明來源 |
| 分支與觸發 | 提供分支及觸發原因 | 核對事件篩選條件 | 不接受未列入條件的來源 |
| 產物 | 標示產物名稱與來源執行 | 只下載指定執行的檔案 | 隔離來源不明的產物 |
| 執行結論 | 記錄成功、失敗或取消 | 依上游結論決定是否建置 | 不得把失敗當作成功放行 |
| 權限與憑據 | 不輸出秘密 | 限制寫入權限與 Secrets | 暫停工作流並縮小權限 |
完成完整驗收後，再按證據選擇 Linux Agent 加 Mac CI、只保留一般 Mac CI，或繼續隔離試跑；若工作流已穩定，但團隊仍缺少可用的 macOS 執行環境，先確認需要的是自有 Runner、託管節點，還是遠端操作環境。Linux 伺服器無法取代 Xcode 所需的 macOS 工具鏈；臨時借用開發者的本機 Mac 則容易遇到排程衝突、環境漂移和憑據管理問題。遠端 Mac 租用可以納入評估，但不要預設任何服務都能安裝或常駐 GitHub Runner；先核實實際接入方式、交付方式與工具鏈，再決定是否合適。你可先查看 MACNOX 的服務資訊，並在確認用途後參考方案資訊，以專案實際驗收結果作最後判斷。