個人の Mac では公開できるのに、リモート Mac では秘密鍵が見つからず署名に失敗する状態です。
fastlane match の既存証明書を先に取り込み、旧経路と新しい CI を並行検証してください。CI では臨時キーチェーンと readonly 同期を使い、証明書の作成や更新は管理者だけが実行する構成にします。
このチェックリストの対象
iOS または macOS の自動署名パイプラインを保守し、個人の Mac への依存をなくしたい DevOps エンジニア向けです。
証明書、秘密鍵、プロビジョニングプロファイル、App Store 公開権限を管理する担当者や、長期運用できるリモート Mac を CI ノードとして用意する開発責任者にも適しています。
Apple のコード署名では、証明書だけでなく対応する秘密鍵も必要です。Apple の署名証明書共有に関する説明でも、署名に使う身元情報を証明書単体で扱わないことが確認できます。
まず署名資産を場面別に分けます
新規プロジェクトと既存プロジェクトでは、最初に選ぶ手順が異なります。新規なら match で統一した保管先を初期化できますが、すでに本番公開へ使っている証明書をいきなり作り直すと、公開経路を失う可能性があります。
新規プロジェクトは最小ビルドを基準にする
新規の iOS アプリでは、次の値を占いではなく設定表として確定させます。
- Bundle Identifier：
com.example.app - Apple チーム識別子：
TEAM_ID_PLACEHOLDER - 署名リポジトリ：
git@example.invalid:team/signing.git - 対象ブランチ：
team-placeholder-ios - 暗号化パスワード：CI の秘密情報ストアで管理
- 対象 Target：アプリ本体、Extension、Widget、Watch App など
開発用、Ad Hoc、App Store 用では必要な証明書とプロファイルの用途が異なります。macOS アプリを配布する場合も、iOS 用の設定を流用せず、macOS の配布署名に関する Apple の資料で対象を確認します。
完了条件は証明書ファイルをダウンロードできたことではありません。新しいリモート Mac 上で、クリーンなワークスペースから同じコミットをビルドし、アーカイブの署名を確認できることを基準にします。
既存の本番署名は先に取り込む
個人の Mac で公開できている場合、最初に次を記録します。
- 使用中の証明書名と用途
- 対応する秘密鍵が存在するキーチェーン
- アプリ本体と付属 Target のプロファイル
- App Store Connect や配布先に関わる認証
- 旧 Mac での公開手順と回復担当者
その後、影響範囲を限定した署名リポジトリへ match import を試します。fastlane 公式の match インポート手順に沿って、秘密鍵を含む資産を暗号化して保管し、まず開発用または検証用の対象で取得します。
注意：
match nuke、証明書の失効、キーチェーンの削除は、バックアップと回復入口を確認する前に実行しないでください。失効後に旧 Mac、CI、配布先のどこも署名できなくなると、切り戻し自体が難しくなります。
旧経路を残したまま、同一コミットで新しいリモート Mac のアーカイブ、署名情報、実機または配布先での導入結果を比較します。単に match が終了しただけでは、移行完了とは判定しません。
署名保管と Target の境界を決めます
同じ Apple チームの複数アプリでは、証明書を共有しながら、アプリごとのプロファイルを分ける構成が一般的です。ただし、Extension や Widget が別の Bundle Identifier を持つ場合、メインアプリのプロファイルだけ取得しても実際のアーカイブは完成しません。
| 管理対象 | 共有できる範囲 | 分離する条件 | 確認する証拠 |
|---|---|---|---|
| Apple チーム | 同一チームの証明書 | チーム識別子が異なる | Appfile と開発者アカウント設定 |
| アプリ本体 | 署名証明書 | Bundle Identifier が異なる | 生成されたプロファイル |
| Extension、Widget、Watch App | 署名基盤 | Target ごとの識別子や機能が異なる | 全 Target のアーカイブ |
| CI ジョブ | 検証用の読み取り権限 | 本番公開や更新権限を使う | ジョブ権限とログ |
複数チームを一つの共有設定に押し込むと、暗号化パスワードや Apple チーム設定の取り違えが起きやすくなります。チームごとに保管領域を分け、必要な場合はブランチ、リポジトリ、CI の秘密情報、Appfile を独立させます。fastlane の Appfile 公式資料でチーム設定を確認し、実際のアカウント情報は設定例へ書き込まないでください。
リモート Mac の CI は読み取り専用にします
CI の標準経路は、署名資産の同期、キーチェーン確認、ビルド、アーカイブ、成果物検証の順です。証明書の新規作成やプロファイル更新まで通常ジョブに許可すると、失敗原因の切り分けと権限管理が複雑になります。
次のように、認証情報を用途ごとに分けてください。
| 認証情報 | 用途 | 保管場所の例 | 通常 CI への許可 |
|---|---|---|---|
| 署名リポジトリ認証 | 暗号化済み資産の取得 | CI の秘密情報ストア | 読み取り |
| match の復号パスワード | 証明書と秘密鍵の復号 | CI の秘密情報ストア | 読み取り |
| Apple サービス認証 | プロファイル更新や公開 | 管理ジョブ専用の秘密情報 | 原則として分離 |
| 配布トークン | App Store 公開 | リリースジョブ専用 | 承認後だけ |
| SSH、VNC などの管理権限 | ノード保守 | 管理担当者 | CI に渡さない |
setup_ci は CI 向けのキーチェーン設定を準備するためのアクションです。公式の setup_ci ドキュメントに従い、ジョブごとに臨時キーチェーンを作成し、match に読み取り専用の動作を指定します。同期はビルドやアーカイブより前に実行してください。
非対話で次の状態になるかを確認します。
- キーチェーンの確認ダイアログを待たない
- Apple アカウントの追加認証や画面操作で停止しない
- 秘密鍵が署名処理から利用できる
- 失敗時に復号、署名、プロファイル、公開のどこで止まったかログに残る
- ジョブ終了後に別ジョブが同じ秘密鍵を自動利用できない
共有ノードは分離と再起動を検証します
同じ Mac を開発ビルド、テストアーカイブ、正式公開で共有する場合、macOS のユーザー、作業ディレクトリ、CI の秘密情報、キーチェーンを同一にしない構成が必要です。
特に、ノードの再起動、ログインユーザーの変更、並列ジョブの実行は、臨時キーチェーンとプロファイルの状態を変える要因になります。設定直後だけでなく、再起動後にも署名同期からやり直せるか確認します。
受け入れ試験の手順
- 署名資産の一覧、対応する秘密鍵、Target、旧公開経路を台帳化します。
- 既存資産を隔離した保管先へ取り込み、復号パスワードを CI の秘密情報として登録します。
- リモート Mac で臨時キーチェーンを作成し、match を readonly で実行します。
- メインアプリ、Extension、Widget、Watch App を含む同一コミットをビルドします。
- アーカイブ内の署名とプロファイルを確認し、実機または対象配布先で導入します。
- ノードを再起動し、ユーザーセッションが変わっても同じ処理を再実行します。
- 権限の異なる二つのジョブを連続または並列で動かし、資格情報の混在と残留を確認します。
- 旧 Mac の公開経路を維持したまま、失敗時の切り戻し条件を記録します。
Apple の配布手順では、登録デバイス向け配布とプロファイルの関係を確認できます。登録デバイスへの配布に関する公式資料と、プロファイルの編集・再生成に関する資料を照合し、プロファイルが古いまま残っていないか確認します。
本番移行は三つの判定から選びます
証明書の期限、プロファイルの変更、暗号化パスワードの更新、リモート Mac の交換、署名リポジトリの停止は、個別の復旧手順が必要です。更新権限を通常 CI に渡すのではなく、変更担当者、承認者、切り戻し担当者を先に決めます。
判定は次のように整理できます。
- 直接移行：新ノードで全 Target のアーカイブと配布を確認し、再起動後の復旧と旧経路からの切り戻しも確認できた場合
- 二重運用を継続：ビルドは成功するものの、公開権限、実機導入、再起動復旧、並列ジョブのいずれかが未確認の場合
- 移行を保留：秘密鍵の対応関係、プロファイルの対象、復号手段、旧経路の回復入口が不明な場合
個人の Mac だけで運用する方法は、担当者が不在になると署名秘密鍵へアクセスできず、端末交換や macOS の更新時に復旧作業が集中し、CI の再現性も保ちにくいという弱点があります。共有クラウド環境だけに依存する方法も、Mac 固有の権限、再起動状態、GUI を伴う Xcode 作業を細かく管理しにくい場合があります。
そのため、署名資産を棚卸しした後は、管理権限を分離でき、再起動後の復旧試験も行える実機のリモート Mac を用意するのが現実的です。短期の検証や公開前の移行試験であれば、RUVCLOUD の Mac レンタル案内を確認し、非本番証明書で match、アーカイブ、復旧を先に通してから正式な公開ジョブを移してください。
よくある確認事項
fastlane match の既存証明書は失効させずに取り込めますか？
可能です。既存の証明書、秘密鍵、プロファイルを先に棚卸しし、隔離した保管先で match import を試行します。旧公開経路を残し、同じコミットで新しいリモート Mac のアーカイブと導入結果を比較してから切り替えます。
なぜ臨時キーチェーンが必要ですか？
臨時キーチェーンは、共有ノードの通常ユーザー環境と CI 用秘密鍵を分けるために使います。ジョブ開始時に作成し、署名同期後に鍵が利用できることを確認すれば、画面上の確認や別ジョブの資格情報に依存する範囲を抑えられます。
readonly はどのジョブで有効にしますか？
通常のビルド、テスト、アーカイブ、リリース候補の検証では readonly を有効にします。証明書の作成やプロファイル更新が必要な場合は、変更範囲、承認者、バックアップ、切り戻し方法を確認できる管理ジョブへ分離します。
複数アプリと複数チームの保管先はどう分けますか？
同じチーム内では証明書を共有し、Bundle Identifier ごとにプロファイルを管理できます。Apple チームが異なる場合は、ブランチまたは保管領域、復号パスワード、Appfile、CI 権限を分け、実際のチーム識別子を設定例へ直接書かない構成にします。
fastlane match の移行は、証明書ファイルを取得できたかではなく、秘密鍵を含む署名、全 Target のアーカイブ、配布先での導入、再起動後の復旧まで確認できたかで判断します。個人 Mac だけの運用や、権限を一つの高権限キーへ集約する運用を続けるより、隔離と復旧を検証できるリモート Mac の方が、継続的な CI 署名には適しています。
まずは本番証明書を使わず、管理権限を分離できるリモート Mac で移行手順を再現してください。検証用の Mac 環境を確保する場合は、RUVCLOUD の利用手順から、必要な期間と管理方法を確認できます。