fastlane matchの証明書同期に失敗したら？リモートMacでの調査（2026）

まず、ログ上で停止した工程を4つに分けてください。fastlane matchの説明とコード署名の排障資料に沿って、リポジトリ取得、復号、証明書と秘密鍵の利用、ビルド時の署名を順に切り分けます。最初に現れたエラーを直し、証明書を一括で作り直したり失効させたりしないでください。リモートMacでは、実際にビルドを実行するユーザーとKeychain環境で再確認します。(matchの公式説明、コード署名の排障資料)

この手順は、手元にMacがなくリモートMacで初めてfastlane matchを動かすiOS開発者向けです。
ローカル環境からビルドを移し、証明書や秘密鍵が使えなくなった小規模チームにも役立ちます。
常時稼働のビルド環境を保ち、署名材料の重複作成や誤った失効を避けたい場合も対象です。

fastlane matchの証明書同期失敗を停止箇所で分ける

最初に、失敗したコマンドと完全なログを保存します。末尾のエラーだけで判断すると、matchが成功した後に発生したxcodebuildの署名エラーまで、証明書同期の問題と誤認することがあります。

次の順で、ログ中の最後に成功した工程を特定します。

• リポジトリに接続できず、クローンやフェッチの前後で停止したか。
• リポジトリは取得できたが、証明書やプロファイルの復号で停止したか。
• 同期処理は完了したが、証明書アイデンティティや秘密鍵が見つからないか。
• matchの後にビルドが進み、署名対象やプロビジョニングの不一致が出たか。

fastlaneの排障資料では、署名の問題をログや設定に基づいて確認する方法が案内されています。コマンド全体、実行ユーザー、作業ディレクトリ、ログの最初のエラーを一緒に記録し、再実行時に何が変わったか比較してください。(fastlaneのコード署名トラブルシューティング)

ログを共有する場合は、トークン、秘密鍵、証明書リポジトリの認証情報、復号パスワードを伏せてください。原因の特定に必要なのは、秘密値そのものではなく、認証・復号・Keychainのどの段階で失敗したかです。

リポジトリ取得と復号を別々に確認する

Gitの取得に失敗する場合、まずmatchに渡しているリポジトリURLと、リモートMacからそのURLへ接続できる認証方法を確認します。SSHを使う構成なら、ビルドを起動するユーザーが必要なSSH鍵を利用できるか、リポジトリへのアクセス権があるかを確認してください。手元のMacで成功することは、リモートの実行環境でも同じ認証情報が使える証拠にはなりません。

クローンは成功するのに復号で失敗する場合は、Git権限ではなくmatchのストレージ設定と復号パスワードを調べます。ローカルのシェルに登録した環境変数が、SSHの非対話シェルやCIジョブへ引き継がれているかを、秘密値を表示せずに確認してください。fastlaneの資料では、matchの保存先と暗号化パスワードの扱いが説明されています。(matchの保存先とパスワード設定)

切り分けの順序は、次のとおりです。

• クローン前に失敗するなら、URL、SSH認証、リポジトリ権限を確認します。
• クローン後に復号で止まるなら、実行環境でのパスワード設定とmatchの保存設定を確認します。
• どちらも通るなら、証明書のインポートとKeychainの状態へ進みます。

一度にURL、認証方法、パスワードを変更しないでください。変更点が複数あると、どの修正が効いたのかログから追えなくなります。

Keychainと秘密鍵を実行ユーザーで調べる

証明書ファイルがリモートMacにあるだけでは、ビルドで署名できるとは限りません。証明書がKeychainに取り込まれていること、その証明書に対応する秘密鍵が利用可能であること、ビルドを実行するユーザーがその組を参照できることを分けて確認します。Appleの資料でも、署名アイデンティティを使うには証明書に対応する秘密鍵が関係します。(署名証明書と秘密鍵の説明)

特に、リモートデスクトップでの手動実行、SSHからの実行、CIの非対話タスクは、同じMac上でもユーザーやログイン状態が異なることがあります。対話セッションで証明書が見えていても、ジョブ実行時のKeychainで利用できるとは限りません。実際のビルドユーザーに切り替え、同じ起動経路から署名アイデンティティを確認してください。

fastlaneの一般的な署名問題にも、証明書やプロビジョニング設定を照合する確認事項があります。エラーに表示されたユーザーとKeychainを確認し、証明書だけを再作成する前に、実行コンテキストの違いをつぶします。(fastlaneの一般的なコード署名問題)

Provisioning Profileとターゲットの対応を照合する

証明書が使えるのに署名に失敗するなら、対象アプリのBundle ID、ターゲット、署名方式、プロファイルに含まれる証明書を確認します。メインアプリの設定が正しくても、通知拡張など別のターゲットが別のBundle IDやProvisioning Profileを使っていれば、そのターゲットで失敗します。

プロジェクトのビルド設定と、Apple Developerで確認できるプロファイルの実際の内容を突き合わせてください。プロファイルが対象IDや署名証明書と合っていない場合に、編集または再生成が必要かを判断します。Appleはプロビジョニングプロファイルの編集・ダウンロード・削除手順と、App Store用プロファイルの作成手順を公開しています。まずその内容とプロジェクト側の設定を照合し、理由が確認できてから変更してください。(プロファイルの管理方法、App Store用プロファイルの作成方法)

強制的な再同期や再生成は、すべての不一致を直す方法ではありません。誤ったBundle IDやターゲットのマッピングを残したまま更新しても、同じ構成で再び失敗する可能性があります。

Xcode選択と複数ターゲットを確認する

matchの実行時とビルド時で、選択されているXcodeが異なっていないか確認します。コマンドラインツールの選択状態は、実際にタスクを動かすユーザーの環境で調べてください。AppleのXcodeコマンドラインツール資料を参照し、GUIで開いたXcodeだけを根拠にせず、ジョブの実行環境で選択状態を照合します。(Xcodeコマンドラインツールのリファレンス)

複数ターゲットを含むアプリでは、署名設定をターゲットごとに確認します。メインアプリのBundle IDとプロファイルが正しくても、拡張ターゲットに別のID、署名方式、プロファイルが割り当てられていることがあります。ビルドログで失敗したターゲットを特定し、そのターゲットの設定だけを先に照合してください。

実行中のXcodeを確認するには、次のコマンドをビルドと同じユーザーで実行します。

xcode-select -p

出力が想定と異なる場合は、ジョブ設定や実行ユーザーの環境を確認してから切り替えます。変更後はmatchだけを実行して終わりにせず、同じ経路から対象ターゲットのビルドまで再確認してください。

修復後の確認と次の環境選び

復旧時は、修正した箇所を記録し、次の順で結果を確認します。

• matchを再実行し、リポジトリ取得と復号が通ることを確認します。
• ビルド実行ユーザーのKeychainで証明書アイデンティティと秘密鍵を確認します。
• ターゲットごとにBundle ID、署名方式、Provisioning Profileの対応を確認します。
• 同じSSHまたはCIの起動方法で、対象ビルドを実行します。
• 署名済みアーカイブまで生成できたことを確認してから、修正を完了扱いにします。

修復の判断には、次の分岐を使えます。

• リポジトリ取得に失敗する場合：Git URL、SSH認証、権限だけを先に直し、復号や署名設定は変更しません。
• 取得後の復号に失敗する場合：実行環境でのmatch設定とパスワード受け渡しを確認し、証明書を再発行しません。
• 証明書はあるが署名できない場合：同じ実行ユーザーのKeychainと秘密鍵を確認し、対話セッションだけの成功で判断しません。
• プロファイルや特定ターゲットで失敗する場合：ID、ターゲット、証明書との対応を直し、根拠なしに一括更新しません。
• 上記が通り、ビルドだけ失敗する場合：Xcode選択状態とターゲットごとのビルド設定へ戻って確認します。

手元のMacはローカルでの操作性に優れますが、専用機として購入・維持する費用とディスク容量が必要です。既存のWindowsやLinux中心の構成に署名工程だけを外付けすると、認証情報の受け渡し、実行環境の差、Mac側の稼働管理が残ります。反対に、長時間の重いビルドを継続する場合や、特定の物理機器へ直接接続する場合は、自分で管理するMacのほうが合うことがあります。

FAQに入る前に、リモート環境の利用条件はMangoVMのヘルプで確認できます。署名素材を扱う運用では、データ保護に関する案内も確認し、鍵やパスワードをログへ出さない手順を整えてください。

よくある切り分けの質問

新しいMacでmatchの復号に失敗する場合

Gitの取得に成功しているなら、次に確認するのは復号パスワードが実際の実行環境に渡っているかです。手元のシェルとSSH・CIの非対話シェルは環境変数が異なる場合があります。秘密値を出力せず、同じユーザーと起動方法で再実行して、最初に失敗する工程が変化したかを確認します。

リモートMacで証明書の秘密鍵を見つける場合

証明書ファイルの有無だけでなく、ビルド実行ユーザーのKeychainに署名アイデンティティと対応する秘密鍵があるか確認します。リモートデスクトップで確認した結果をSSHやCIへ当てはめず、実際のビルドと同じ起動方法で照合してください。ユーザーやKeychainが異なる場合は、まず実行環境をそろえます。

Provisioning Profileが一致しない場合

更新を急がず、失敗したターゲットのBundle ID、署名方式、証明書、プロファイルを順に照合します。拡張ターゲットがメインアプリと別の設定を使っている可能性も確認してください。Apple Developer上のプロファイル内容とプロジェクト設定に不一致が見つかった場合に、該当プロファイルの編集または再作成を検討します。

SSHやCIからKeychainへアクセスできない場合

ジョブを動かすユーザーとKeychainを、手動実行時の状態と比較します。非対話タスクでのみ失敗するなら、ログイン時に開かれるKeychainや環境変数の受け渡しを確認し、同じ起動方法で署名付きビルドを試してください。秘密鍵をログに出したり、確認のために秘密情報を共有したりする必要はありません。

ビルド頻度に合わせてMac環境を選ぶ

手元のMacで問題なくビルドでき、署名工程の実行頻度も少ないなら、まずローカル環境を維持するのが簡単です。一方、Macを持たない、ローカルの容量を確保できない、または署名ビルドのためだけに専用機を常時維持したくない場合は、遠隔から使えるMacを選択肢にできます。

遠隔環境には通信の遅延があり、物理接続や長期の高負荷運用には向かない場合があります。条件が合い、環境を分けて継続的にビルドしたいなら、MangoVMのMac環境を確認し、利用期間と実際のビルド頻度を照らし合わせてください。まずは同一ユーザー・同一実行経路で署名付きアーカイブまで再現できるかを受け入れ条件にすると、移行後の見落としを減らせます。

よくある質問