GitHub Actions Xcode 簽名失敗：2026 排查指南

Xcode 本機簽名正常，但 GitHub Actions 歸檔時簽名失敗，或 SSH 測試成功而 Runner 仍找不到身份。

最快的排查順序：先查 Runner 工作程序實際使用的 macOS 帳戶與 Keychain，再核對簽名身份、私鑰和描述檔；不要先擴大權限或反覆匯入憑證。

適合本機可簽名、CI 卻無法完成歸檔的 iOS/macOS 開發者。
適合需要查明自託管 Mac Runner 執行環境的 DevOps 工程師。
也適合負責憑證、發布與存取權限的管理員。

[ SECTION_01 ] GitHub Actions Xcode 簽名失敗，先分清故障責任

「簽名錯誤」可能發生在不同環節：專案建置設定不符、Runner 工作程序無法使用 Keychain、簽名身份缺少可用私鑰，或描述檔與目標 App 不相符。若只看最後一行錯誤，容易把所有問題都當成憑證損壞。

先以同一個提交版本、同一個 Scheme 與同一個發布目標作比較。從 Workflow 記錄找出失敗發生在一般建置、封存，還是簽名階段；再把本機建置結果與 CI 使用的建置設定並列。Apple 的 Xcode 建置設定參考說明相關設定項目；實際採用的值仍應以該次建置記錄為準。

GitHub 的自託管 Runner 排查文件提供檢視 Runner 記錄與排查服務的方向。CI 維護者應保存失敗 Job 的記錄及 Runner 識別資訊，讓開發者與憑證管理員基於同一份證據接手。

[ SECTION_02 ] 開發者先核對 Scheme、Target 與簽名目標

開發者的責任，是證明專案要求 Runner 簽甚麼，而不是先假定主機上的憑證有問題。核對 Workflow 執行的 Scheme、Target、建置設定及歸檔目的，並確認它們與預期的 iOS 或 macOS 發布流程一致。

自動簽名與手動簽名的排查方向不同。自動簽名要確認 Xcode 使用的 Team 與目標是否符合專案預期；手動簽名則要確認選定身份及描述檔，確實對應正在封存的 Target。Apple 的建置及執行 App 說明可協助核對 Xcode 的建置與執行流程。

接著確認 Bundle Identifier、Team ID、描述檔與發布用途彼此一致。這些欄位應使用實際專案值在內部比對；分享記錄或請求協助時，請以 <BUNDLE_ID>、<TEAM_ID> 等佔位符取代敏感資料。若本機與 CI 使用的設定不同，先修正專案或 Workflow，再交由 Runner 維護者檢查主機環境。

[ SECTION_03 ] Runner 維護者確認工作程序的執行上下文

SSH 登入成功，只能說明該次互動式工作階段可執行相關操作，不能證明自託管 Mac Runner 服務使用相同帳戶、相同 Keychain 或相同環境。CI 維護者應從 Workflow 工作程序取得實際執行帳戶的證據，並與 Runner 服務狀態、Runner 日誌交叉核對。

若 Runner 以服務方式執行，確認服務管理方式及其工作程序上下文。當服務由 launchd 管理時，不能用桌面已登入帳戶的狀態直接推論服務權限。GitHub 的設定自託管 Runner 文件說明 Runner 應用程式的設定與服務管理；排查時應把服務資訊與實際 Workflow 檢查結果一起留存。

再確認工作程序是否能使用所需的 macOS Keychain，以及該 Keychain 目前是否處於預期狀態。把互動式終端測試和 Workflow 內的結果分開記錄。若前者通過、後者失敗，交接重點應是兩種執行上下文的差異，而不是要求開發者重新安裝 Xcode。

[ SECTION_04 ] 簽名管理員核實身份、私鑰與描述檔配對

憑證出現在清單中，不等於當前工作程序能用它簽名。簽名管理員需確認目標身份及其私鑰能否由 Runner 執行環境使用。Apple 對程式碼簽名身份的說明，以及簽名憑證的技術說明，可作為核對身份與簽名材料的官方依據。

描述檔也須獨立核對。確認它對應的應用識別碼、Team ID 與用途符合目前發布目標；Apple 的建立 App Store 發布描述檔說明列出建立該類描述檔時應核實的資訊。若身份與私鑰可用但描述檔不匹配，問題不應歸因於 Keychain。

匯入或更新簽名材料前，記錄變更內容、負責人及復原方式。需要比較本機和 CI 狀態時，只傳遞必要的身份名稱、檢查結果與遮蔽後的識別資料；不要把私鑰、密碼或完整憑證內容貼進一般工作記錄。

[ SECTION_05 ] 安全負責人限制簽名工作可被誰觸發

簽名 Job 能接觸發布憑據，就要檢查哪些倉庫、工作流程與人員可以觸發它。尤其是共享 Runner，不應讓不可信工作流程因路由或權限設定不當而接觸生產簽名材料。

GitHub 的安全使用 GitHub Actions 指引涵蓋工作流程與憑據使用的安全考量。依據團隊政策限制工作流程可見的秘密資料，並縮小可執行簽名任務的 Runner 範圍。排查失敗時，不要為了讓 Job 通過而關閉安全控制或把憑據放進不受信任的工作環境。

提醒：權限變更要記錄核准人、適用的倉庫與工作流程，以及回復原設定的方法。若無法界定簽名材料的存取範圍，先隔離發布工作，再處理復原與重新驗收。

[ SECTION_06 ] 常見疑問：本機、SSH 與 Runner 的結果為何不同

本機 Xcode 可以簽名，GitHub Actions 卻找不到憑證，應由誰先查？
先由 Runner 維護者確認工作程序帳戶與 Keychain，再由簽名管理員核實該環境可用的身份及私鑰。開發者同步提供 Scheme、Target 和建置設定。這樣可把主機上下文與專案設定分開，不必一開始就重建憑證。

SSH 登入 Mac 後可以簽名，為甚麼 Runner 工作仍然報錯？
SSH 是互動式登入，不是 Runner 工作程序本身。請把 SSH 結果只當作一組對照，再從 Workflow 記錄核對工作帳戶與 Keychain 存取情況。若兩者不同，交由服務維護者處理 Runner 的執行上下文，避免以桌面登入狀態推斷服務權限。

怎樣查明 GitHub Actions 使用的 macOS 帳戶與 Keychain？
在 Workflow 中記錄工作程序可取得的帳戶與簽名檢查結果，再與 Runner 服務狀態及日誌比對。不要只看 SSH 登入名稱。若 Runner 由 launchd 管理，也要確認服務所屬上下文；交接時應遮蔽帳戶與路徑等敏感資料。

簽名身份已存在，Xcode 仍無法完成簽名，下一步是甚麼？
先確認身份包含可供當前工作程序使用的私鑰，再檢查描述檔是否與應用識別碼、Team ID 和發布用途相符。接著回查 Scheme、Target 與建置設定。身份列在清單中，只能證明它存在，不能單獨證明 Runner 可以用它簽名。

[ SECTION_07 ] 發布負責人以真實歸檔結果驗收修復

Runner 顯示在線或一般編譯成功，都不足以證明發布簽名已修復。發布負責人應使用實際發布目標，在乾淨的 Workflow 執行中確認建置、簽名與歸檔產物。驗收依據應包含該次建置記錄、身份檢查結果及歸檔產物，而不是單一成功狀態。

修復完成後，確認相同專案設定與執行環境能再次完成簽名流程。若結果不穩定，或簽名權限無法限制在預期工作流程內，先隔離簽名任務或重建專用節點，再決定是否恢復正式發布。GitHub 與 Apple 的官方說明提供排查邊界；具體是否修復，仍須由實際 Workflow 證據確認。

[ SECTION_08 ] 用可追溯檢查清單判斷下一個交接對象

• [ ] 保存失敗 Job 記錄，標出問題發生於建置、封存、身份選擇或簽名階段。
• [ ] 確認本機與 CI 使用相同提交、Scheme、Target 及發布目標。
• [ ] 從 Workflow 證據確認 Runner 工作程序的 macOS 帳戶，不以 SSH 登入帳戶代替。
• [ ] 比對 Workflow 與互動式終端的 Keychain 存取結果。
• [ ] 確認目標簽名身份及私鑰可由 Runner 工作程序使用。
• [ ] 核對描述檔的應用識別碼、Team ID 與發布用途。
• [ ] 檢查哪些倉庫、工作流程及人員能觸發含簽名材料的 Job。
• [ ] 以實際發布目標重新執行 Workflow，檢查簽名與歸檔產物。

[ SECTION_09 ] 按責任角色比較證據，避免錯誤修復

下表的「證據評分」是團隊內部的排查工具，不是 Apple 或 GitHub 的官方評級。每個責任範圍可按證據完整度評為 0 至 2 分：0 代表沒有直接證據；1 代表只有本機或間接結果；2 代表有該次 Workflow 的直接記錄。低分項目應先補證據，再判斷是否修改憑證或權限。

若目前以共享 Mac 或臨時主機執行簽名，常見代價是執行帳戶不一致、Keychain 狀態難以追查，以及不同工作流程共用憑據時難以界定影響範圍。若團隊需要穩定的 macOS 執行環境，可先了解 NOVAKVM 的遠端 Mac 方案，再按工作流程、存取權限與驗收方式評估是否適合接入；也可從 NOVAKVM 服務資訊了解可用方案。若長期固定高負載或必須連接實體裝置，應同時評估自購 Mac 或現有專用節點；若只是需要臨時測試或可隔離的發布環境，遠端 Mac 可作為避免共用個人工作站的選項。