症状：fastlane matchがリモートMacで署名資産を取得できず、ビルドが止まる。
最短の対処：私有リポジトリへのアクセス、matchの暗号化パスワード、Appleアカウントの認証、署名IDを分けて調べます。CIや無人ビルドでは、まず読み取り専用のreadonlyを使い、原因不明のまま証明書を作り直したり失効させたりしないでください。
初めてリモートMacにfastlane matchを設定し、署名資産を取得できない独立開発者。
複数の開発者で署名リポジトリを共有し、書き込み権限を管理したい小規模チーム。
新しいMacやCIへの移行後、署名関連の読み込みでつまずいたリリース担当者。
fastlane matchの取得失敗を層ごとに切り分ける
エラーに「clone」や認証拒否が出るなら、まずGitの接続を確認します。リポジトリを読めても復号に失敗するなら、次にMATCH_PASSWORDを確認してください。資産の取得と復号が通った後に署名で止まる場合は、証明書、秘密鍵、Provisioning Profile、Keychainの問題として調べます。
この切り分けが必要なのは、Gitの認証情報、matchの暗号化パスワード、Apple Developerアカウントの認証が別々に働くためです。どれか一つが成功しても、残りが正しいとは限りません。
初めてのリモートMacでは、まずリポジトリに到達できるか確認
エラー全文を読む前に、リモートMac上で実行ユーザーを確認し、そのユーザーの認証情報でGit接続を試します。git ls-remote <リポジトリURL>は、リモートリポジトリから見える参照を表示するコマンドです。接続できるのに参照が取得できない場合は、URL、アクセス権、SSH鍵やHTTPS資格情報を見直します。git ls-remoteの役割
SSH接続を使う場合は、ローカル端末の接続結果ではなく、実際にビルドを実行するMac上で認証を試してください。手元のMacでは成功しても、リモートMacには別のユーザーや鍵が設定されていることがあります。SSH接続をテストする手順
エラー出力を共有するときは、リポジトリURL、ホスト名、ユーザー名、鍵の内容、トークン、証明書IDを伏せてください。秘密情報を含むログを、そのまま公開チケットやビルドログに貼らないでください。
開発者のMacでは動き、新しいMacだけ失敗する場合
新しいMacがどのユーザーとしてジョブを実行し、どの認証方式を使っているかを照合します。SSHなら、対象リポジトリへの読み取り権限を持つDeploy keyが登録されているか確認します。Deploy keyの権限と使い方は、公式の管理手順で確認できます。
HTTPSを使う構成では、古いMacの資格情報を新しいMacが引き継いでいるとは限りません。トークンを使う場合も、保管場所と対象リポジトリへの権限を確認し、個人用の認証情報をチームで使い回さないでください。認証問題を回避するために署名リポジトリを公開したり、共有の個人パスワードを設定したりするのは避けます。
リポジトリを読めるのに復号できない場合
Gitの読み取りに成功した後で復号エラーが出るなら、リポジトリのアクセス権ではなく、matchが使う暗号化パスワードを調べます。CIやリモートMacの環境変数にMATCH_PASSWORDが設定されているか、ジョブがその秘密情報を参照できるかを確認してください。変数名の誤記や、対象環境に秘密情報が渡されていないことも原因になります。
GitHub Actionsを使う場合は、秘密情報がワークフローや実行対象から利用できる範囲を公式のSecrets仕様で確認します。秘密情報をリポジトリに書き込んだり、コマンド履歴や公開可能なログに出したりしてはいけません。
リモートMacで、matchのパスワード誤りとGit認証失敗をどう見分けますか？
Gitの接続確認が失敗するなら、まずリポジトリURLとGit認証を調べます。接続できて資産を読み込んだ後に復号エラーが出るなら、MATCH_PASSWORDと秘密情報の受け渡しを確認します。パスワードを変えてもGitの認証拒否は解消しません。
取得後に署名できない場合は、署名IDとProfileを確認
matchが資産を取得できたことと、Xcodeが有効な署名IDを使えることは別の状態です。Appleの説明では、コード署名の証明書に対応する秘密鍵が署名IDを構成します。証明書だけがKeychainにあり、対応する秘密鍵がない場合は、その証明書で署名できません。コード署名証明書と秘密鍵の関係
次に、対象アプリのBundle IDや必要な機能にProvisioning Profileが合っているかを確認します。Profileに含まれる条件は、AppleのProvisioning Profile解説で照合できます。期限切れや設定変更が疑われる場合も、対象を特定してからProfileの編集・ダウンロード手順を確認してください。
matchの取得成功後もXcodeが証明書を見つけないときは？
Keychainを確認し、証明書と対応する秘密鍵がそろっているかを調べます。そのうえで、ビルド対象に合うProfileが選ばれているかを確認してください。Appleアカウントの認証失敗と、ローカルの署名資産不足は別の障害です。後者を直すために、すぐ証明書を再生成する必要はありません。
チーム共有とCIでは、必要な書き込み権限を分ける
開発者が通常のビルドで署名資産を読むだけなら、リポジトリへの読み取り権限で足りる構成を検討します。CIではfastlaneの案内に従い、readonly: trueを指定して、意図しない証明書やProfileの作成・変更を防ぎます。matchの保存方式とreadonly設定
- 開発者：担当するビルドに必要な読み取り権限を持つ。
- リポジトリ管理者：アクセス権と秘密情報の保管場所を管理する。
- CI保守担当者：CIに必要な秘密情報だけを登録し、読み取り専用でビルドを検証する。
- 署名資産を変更する担当者：チームの承認手順に沿って、必要な変更を実施する。
CIでmatchを使う場合、readonlyを有効にしますか？
通常のCIビルドではreadonly: trueを基本にします。署名資産の新規作成や更新が必要なときは、権限を持つ担当者がチームの手順で別途実施します。CIの失敗を直すために、常時の書き込み権限を広げるのは避けてください。
Keychainの削除や証明書の失効・置き換えをする前に、そのMacを使う他のビルドへの影響、バックアップ、復旧方法を確認してください。影響範囲が分からないまま削除すると、別のアプリの署名まで止まるおそれがあります。
修復後は取得結果ではなくArchiveまで確認
秘密情報を直した後は、取得、復号、署名、ビルドの順に結果を記録します。matchの成功ログだけで完了と判断せず、対象プロジェクトで実際にArchiveできることまで確かめてください。
- Git認証：ビルド実行ユーザーでリポジトリを読み取れる。
- 復号：保管された秘密情報で署名資産を復号できる。
- 署名ID：証明書と対応する秘密鍵をKeychainで利用できる。
- Profile：対象アプリのBundle IDと必要な機能に適合する。
- ビルド：対象の構成でビルドし、Archiveを確認できる。
| 確認結果 | 主に調べる箇所 | 次の対応 |
|---|---|---|
| リポジトリを読めない | URL、Git認証、読み取り権限 | 実行ユーザーの資格情報を修正 |
| 読み取り後に復号できない | MATCH_PASSWORD、秘密情報の受け渡し |
安全な保管元と環境変数を照合 |
| 資産取得後に署名できない | 証明書、秘密鍵、Profile、Keychain | 不足箇所を特定してから修復 |
| CIだけ書き込みを求められる | 実行設定と権限設計 | readonlyを基本に運用を見直す |
現在の環境とリモートMacを使い分ける
共有の開発者Macを打ち合わせや手動公開に使い続けると、担当者の資格情報に依存しやすく、端末の空き状況も調整が必要です。CIだけで署名を完結させる構成は自動化に向く一方、秘密情報の範囲や失敗時の調査をチームで管理する必要があります。自前のMacは物理的なKeychainや接続機器を扱いやすい反面、保守と常時稼働の負担が残ります。
一時的なビルドや移行時の検証なら、手元のMacや既存CIを先に整えるほうが適することもあります。常時利用する署名ビルド環境がなく、XcodeでのArchiveを継続する必要があるなら、MACCOMEのリモートMac案内を確認し、利用頻度に合うか判断してください。実機への物理接続が必要な作業や、長期の高負荷運用では、自前のMacを含めて比較するのが妥当です。
問題の根因が署名に使えるmacOS環境の不足なら、環境を増やす前に、誰が資格情報を管理し、どのビルドでArchiveを確認するかを決めておきましょう。必要な期間だけ遠隔環境を試す場合は、MACCOMEのMac利用案内を参照し、手元の運用やCIと役割を分けられるか検討できます。