Apple Silicon 雲 Mac iOS/macOS CI：codesign、Notarization、stapler 與鑰匙串邊界

本文要點

CI 上為簽章單獨準備鑰匙串＋最小權限憑證，避免與登入使用者鑰匙串混用導致 errSecInternalComponent。
codesign 與 Hardened Runtime、entitlements 要依產物類型（app、helper、XPC、外掛）分層驗證，再送公證。
以 xcrun notarytool 提交與輪詢；通過後對發佈包執行 stapler staple，區分公證失敗與裝訂失敗。
排障先對齊 submission id 與憑證指紋；同機若疊加 VPN，請把路由與 MTU 一併納入檢核（見 WireGuard 跨境遠控排障文）。

顯示器上的程式碼與終端機介面，象徵雲端 CI 與簽章流水線 — 封面為氛圍示意；正式排障請以 Apple 官方文件、實際 `codesign`／`notarytool` 日誌與鑰匙串存取控制為準。

1. 可複現流水線：金鑰、鑰匙串與 Runner 邊界

雲 Mac 強調無人值守與映像重設：凡依賴「手動點鑰匙串允許」都會在下次實例復發。把發佈憑證與私密金鑰放進專用鑰匙串檔，Job 開頭以 security 設定搜尋順序、預設鑰匙串與解鎖；密語只走 CI 祕密變數。公證輪詢受出口網路影響，若同機還跑 VPN，預設路由可能與 WireGuard 跨境遠控排障文所述非對稱路由疊加，需一併排查。

2. codesign：分層驗證與 Hardened Runtime

對 app 與巢狀目標執行 codesign --verify --deep --strict，必要時以 spctl --assess 預檢 Gatekeeper。隱性失敗多來自子二進位漏簽、entitlements 與 capability 漂移，或腳本改寫已簽 bundle。簽章順序建議寫死：先子後主、再驗簽；第三方二進位須落在你的憑證鏈下或改為 xcframework。若同機使用 Apple Silicon 雲 Mac 上跑生產級 Docker：arm64/amd64 鏡像、bind mount 與構建快取的排障手冊（附套餐資源邊界），勿把宿主鑰匙串 bind 到與使用者脈絡不一致的容器，以免「看得到憑證卻解不了私密金鑰」。

3. Notarization 與 stapler：提交、通過、裝訂

以 xcrun notarytool store-credentials 建立 profile，再 submit 加 wait 取得結構化日誌。通過後對最終發佈的那一份包執行 stapler staple；裝訂失敗常見是包體在公證後又被改動。把 submission id 與狀態寫進建置日誌，便於與 Connect 工單對齊。

# 示意：提交並等待（profile 名稱與路徑請依專案替換）
xcrun notarytool submit ./MyApp.zip --keychain-profile "AC_NOTARY" --wait
xcrun stapler staple ./MyApp.zip
xcrun stapler validate ./MyApp.zip

4. 常見拒絕碼與症狀—動作（速查）

下表用於先分類：左欄貼日誌關鍵字，右欄為首選動作（細節以 Apple 文件為準）。建議在流水線內把每次綠燈建置的 notarytool log 摘要與 codesign -dv 憑證列印存成可下載的建置附檔，與 Git SHA、Xcode 版號、SDK 寫在同一列，之後若 Connect 退回 ITMS 類訊息，才能快速比對是否為「同包不同簽」或「中繼資料漂移」而非產品邏輯回歸。

症狀／日誌線索	高機率根因	首選動作
`errSecInternalComponent`／不允許使用者互動	鑰匙串 ACL、未解鎖或搜尋順序不正確	專用鑰匙串；`security set-key-partition-list`；確認無 GUI 彈窗依賴
`code object is not signed at all`／nested code	巢狀二進位漏簽或簽章被破壞	`codesign --verify --deep`；依相依樹補簽；檢查複製腳本是否改寫 bundle
notarytool `Invalid`	Runtime／entitlements 與公證政策不符	依日誌條目逐項收斂；刪除不必要的寬鬆 entitlement
`stapler staple` 失敗／validate 失敗	公證對象與本機檔案不一致或未通過	對同一未改動包重試；確認先 `wait` 成功再裝訂；檢查是否二次壓縮改變 checksum
上傳 App Store／TestFlight 被拒（ITMS-xxxx）	中繼資料、隱私清單、架構切片與簽章策略	以 Transporter／Xcode Organizer 細節為準；同步更新隱私用途字串與 `PrivacyInfo.xcprivacy`

5. 結語

雲 Mac 上的 CI，要把鑰匙串、憑證、profile、notarytool 與 stapler 順序寫成可宣告的 Runbook，映像升級後做一次冷啟動簽章驗證，讓紅色建置盡量只反映產品變更。