團隊 iOS CI 證書輪換應先盤點證書、私鑰、描述文件和依賴它們的發布任務，再用 Fastlane Match 分階段同步新資產；先在真實 Mac CI 驗證建置、歸檔與簽名，通過後才處置舊資產。這適合需要控制簽名變更風險的企業 IT、平台工程及 iOS 發布團隊。本週先建立資產清單與回退條件，不要把「輪換」直接等同於撤銷舊證書。

企業 IT 負責人：釐清資產所有者、審批人和回退責任。
平台工程師：讓 CI 以受控方式讀取簽名材料。
iOS 發布工程師：確認新資產能完成實際歸檔和發布流程。

里程碑一：先盤點資產，再界定輪換影響面

開始變更前，把簽名材料和使用它們的工作流連起來。只看開發者帳戶裡有沒有證書，或 CI 磁碟上是否存在檔案，都不足以證明建置節點可以簽名。

  • 分開記錄 Apple Development、Apple Distribution 等證書用途，並列出相應私鑰、iOS provisioning profile、應用程式識別碼及使用中的建置與發布任務。Apple 說明不同證書類型適用於不同簽署情境；請以Apple 證書類型與管理說明核對實際資產，不要把開發、商店發行和內部使用簽名視作同一項。
  • 從開發者帳戶、Mac Keychain、CI 變數與流水線設定交叉核對資產狀態、擁有人和用途。記錄證書識別資訊與對應的描述文件，並確認哪個專案、分支或發布流程會取用它。
  • 逐項確認建立或管理證書的帳戶角色是否合適。Apple Developer Program 的角色權限並不相同；依Apple 的角色權限說明確認誰能管理簽名資產，再把日常建置權限與資產管理責任分開。

盤點完成後，為每項資產標示「仍在使用」、「待替換」或「用途未明」。用途未明的項目先查流水線和產物紀錄，不要因為檔名舊或看似閒置就刪除。

里程碑二：先固定可重現基線，再準備替換

輪換前留下可比較的狀態，才能區分簽名變更造成的失敗，和專案、Xcode 或建置設定本身的變化。

  • 記錄目前 Mac CI 使用的 Xcode 版本、簽名身份、描述文件、匯出設定及關鍵建置工作流。把成功流水線紀錄、歸檔產物和簽名檢查結果保存為基線。
  • 確認私鑰可被預定的建置帳戶使用。證書檔案存在，不代表相應私鑰已匯入、可解鎖，或該工作流有權存取；在隔離的測試任務中驗證簽名，而非只檢查檔案清單。
  • 檢查目前誰能讀取 Keychain、Match 加密儲存庫及 CI Secret。若簽名任務使用共享 Mac，還要確認工作區清理、登入工作階段和其他任務的存取邊界，不能把主機層級權限誤當成 Fastlane Match 的隔離保證。

注意：Xcode 可協助團隊同步簽名身份，但這不會替你完成企業審批，也不能取代 CI 主機權限治理。請對照Apple 的 Xcode 團隊簽名身份說明，再依實際工作流確認可用性。

基線應包含「怎樣算通過」和「什麼情況要停止放量」。若關鍵發布任務沒有可重現的成功證據，先補齊對照流程，不要同時更換證書、描述文件與建置設定，否則故障來源難以定位。

里程碑三：先更新新資產，再決定是否撤銷

準備新簽名材料時，按團隊現行管理方式選擇由 Xcode、Apple 開發者帳戶或 Fastlane Match 管理；不要為了輪換而臨時改用另一套資產來源，除非你已安排獨立試點和回退方案。

Apple Distribution 證書到期前，先確認哪些準備？

先核對證書當前狀態及使用範圍，而不是假設它必然即將到期。檢查與其關聯的私鑰、描述文件、應用程式識別碼，以及生產和備援 Mac 節點上的引用位置；再由具備相應權限的人員依團隊流程建立或管理替代資產。

證書變更後，檢查受影響的 provisioning profile 是否仍有效，或是否需要編輯、重新下載或重新產生。Apple 提供描述文件管理步驟，而描述文件與簽名錯誤可再配合Apple 的簽名與描述文件技術說明追查。

不要把撤銷當成一般輪換的第一步。Apple 說明，撤銷證書會令包含該證書的描述文件失效；因此在任何撤銷操作前，先確認受影響的應用程式、建置和發布流程，並留下替代資產已可用的證據。細節以Apple 撤銷證書說明為準。

里程碑四：先在隔離環境試行，再讓正式 CI 只讀同步

Fastlane Match 能協助團隊管理與同步簽名證書及描述文件，但不會自動替你審批變更，也不會證明儲存庫、解密憑證或 Mac 主機已妥善隔離。正式切換前，先把變更控制和存取責任寫清楚。

Fastlane Match 如何讓 CI 只讀取既有資產？

先在隔離的 Mac 建置環境，針對目標應用程式和簽名類型執行同步，確認取回的是預期資產。進入正式流水線後，使用 Fastlane Match 文件所述的唯讀模式，避免建置任務意外建立或改寫簽名材料；實際參數和行為以Fastlane Match 官方文件為準。

  • 將 Match 儲存庫的加密存取權、解密口令及 CI Secret 分別列入權限清單，授權範圍只涵蓋需要執行簽名的工作流與維護者。
  • 把密碼和金鑰放在 CI 平台的 Secret 管理機制中，不要寫入程式碼、建置日誌或可供無關任務讀取的設定檔。若使用 GitHub Actions，請參照其Secret 安全說明，並按實際 CI 平台核對對應設定。
  • 將簽名任務安排在受控的建置環境，限制不可信程式碼接觸憑證。CI runner 一旦遭到入侵，簽名材料可能面臨風險；可參考runner 受損風險說明評估信任邊界。

若正式工作流需要建立或更新簽名資產，應由經審批的維護流程執行；不要讓一般建置任務因缺少資產就自行改寫共用簽名庫。

里程碑五：以真實 Mac CI 驗收，而不是只看流水線綠燈

驗收要證明產物使用了預期簽名身份，並走通團隊真正需要的工作流。只看到流水線成功，可能漏掉歸檔設定、嵌入描述文件或發布路徑仍使用舊資產的問題。

  • 選取能代表生產用途的專案和任務，分別驗證建置、歸檔，以及團隊實際採用的發布或測試分發路徑。
  • 檢查產物的簽名身份與嵌入的描述文件，並把結果和輪換前基線比較。遇到錯誤時，保留流水線日誌、產物檢查結果及使用的簽名材料線索；Apple 的簽名與描述文件技術說明可協助判讀相關問題。
  • 驗證備援 Mac 節點、排程建置及實際發布工作流，不要只在單一測試任務成功後就擴大切換。若任何關鍵任務失敗，暫停推廣，回到已知可用的設定，再依證據查明是哪項資產或權限不符。

怎樣確認 Mac CI 已使用新簽名資產？

比對產物內的簽名身份和描述文件，再核對流水線實際取用的資產來源；不要只根據 Secret 已更新、Match 執行成功或日誌顯示綠燈判定完成。通過條件應包括目標建置與歸檔成功、所需發布路徑可用，以及備援工作流不再依賴未驗證的舊資產。

里程碑六：完成依賴確認後，才處置舊資產

只有當生產工作流、備援節點和相關應用都完成驗收，才依組織審批流程決定舊資產要保留、更新或撤銷。撤銷前再次核對描述文件的依賴關係；未確認影響面時，不要刪除唯一可恢復的私鑰或簽名材料。

何時可以撤銷舊證書？

先確認沒有未切換的發布流程或備援節點仍依賴它，替代證書和描述文件已經過實際驗收，回退所需材料也可取得。再記錄資產所有者、變更審批、驗收證據、回退條件及最終處置結果；撤銷可能令相關描述文件失效，必須把這項影響納入審批和發布安排。

你可以用以下條件作切換決策：

  • 若目標工作流與備援節點都已完成簽名驗收，替代材料可恢復，且沒有待處理的舊資產依賴，則按審批流程退役舊資產。
  • 若只完成部分工作流驗收，則維持舊資產可用，先限制存取並列出未完成的任務，再擴大驗收範圍。
  • 若新資產簽名失敗或回退材料不可用，則停止切換，恢復已知可用配置並保留診斷證據；不要以撤銷舊證書來「清理」狀態。

輪換完成後，把定期核對資產歸屬、CI Secret 權限和產物簽名結果納入維護流程。若團隊還在評估 Mac 節點資源，可先依實際簽名工作量與存取要求核對VMSPIN 的方案與價格資訊，但不要把租用節點視為簽名治理的替代品：證書所有權、私鑰保管、審批和 runner 權限仍由你的團隊負責。

當現有 Mac 設備不足以支援受控驗收，遠端真實 Mac 可作為補充選項；相較自購設備，能避免立即配置實體主機，但仍須評估網路連線、帳戶權限和團隊的安全要求。若要試行，可先了解VMSPIN 的遠端 Mac 方案，並用本文的驗收條件確認節點是否符合你的簽名工作流；若工作負載長期穩定、必須直接連接特定實體設備，則應一併比較自有設備或其他適合的部署方式。