ToolNote
💡 Tips

Fastlane match 証明書期限切れ：突然のビルド障害を確実に復旧する手順

結論：fastlane match nuke で古い証明書を消して再生成するだけ

Fastlane match が管理する証明書の有効期限が切れると、CI/CD パイプラインが突然落ちて焦ることがある。結論から言えば、期限切れ証明書を match nuke で削除し、fastlane match を再実行すれば新しい証明書が自動発行されて Git リポジトリへの保存まで一気に完了する。

ただし手順を間違えると Git リポジトリが汚れたり、チームメンバーの環境が壊れたりする。以下の手順を正確に踏んでほしい。

症状を確認する：どんなエラーが出るか

証明書が切れると、ビルド時に次のようなエラーが出る。

error: No signing certificate "iOS Distribution" found:
No "iOS Distribution" signing certificate matching team ID "XXXXXXXXXX"
with a private key was found.

match 実行中には：

[!] Your certificate 'XXXXXXXXXXX.cer' is not valid,
please check end date and renew it if necessary

Xcode の Signing 設定に「Certificate Expired」と赤く表示される場合も同様。まず闇雲に操作せず、本当に証明書が原因か確認する。

事前確認：期限切れ証明書かどうかを診断する

① Keychain で有効期限を確認

security find-certificate -a -p \
  | openssl x509 -noout -dates 2>/dev/null \
  | grep -E "notAfter"

② match のドライランで確認

fastlane match appstore --readonly --verbose

--readonly を付けると証明書の取得だけを行い、作成・上書きはしない。ログに期限切れの情報が表示される。

③ App Store Connect で目視確認

[Certificates, Identifiers & Profiles] を開き、期限切れマークが付いた証明書を探す。match の Git リポジトリと Apple Developer Portal の状態が食い違っていると、再発行後もエラーが出続けることがあるため、必ず両方を確認する。

復旧手順：step by step

Step 1. match リポジトリをバックアップ（任意だが推奨）

git clone <match-repo-url> match-backup-$(date +%Y%m%d)

Step 2. match nuke で期限切れ証明書を削除

match nuke は Apple Developer Portal と match の Git リポジトリから証明書を同時に削除するコマンド。チーム全員のビルドに影響するため、実行前に必ず告知すること。

# Distribution 証明書のみ削除
fastlane match nuke distribution

# Development 証明書も削除する場合
fastlane match nuke development

注意: nuke はプロビジョニングプロファイルも一緒に削除する。App Store Connect で手動作成したプロファイルも巻き込まれるため、確認してから実行する。

Step 3. 新しい証明書を再発行

fastlane match appstore
# または
fastlane match development

新しい証明書が Apple Developer Portal で発行され、暗号化されて match の Git リポジトリに push される。

--force オプションについて：nuke せず既存証明書を残したまま強制再生成したい場合は --force を使える。ただし期限切れ証明書が残存するため、nuke → 再生成 のほうが確実。

Step 4. CI/CD 環境を確認する

GitHub Actions などの CI 環境では、match が Git リポジトリへアクセスするための認証情報（SSH キーや MATCH_PASSWORD）が環境変数に設定されているはず。証明書の再発行後に環境変数の変更は不要だが、setup_ci の呼び出しを Fastfile に入れているか確認する。

lane :build do
  setup_ci if ENV["CI"]          # CI 専用の一時 Keychain を作成
  match(type: "appstore", readonly: true)
  gym(scheme: "MyApp")
end

setup_ci を省略すると、ローカルでは通るのに CI だけ失敗する症状が出やすい。

Step 5. チームメンバーが再同期する

fastlane match appstore --readonly

全メンバーがこれを実行して新しい証明書を Keychain に取得するまで、各自のローカルビルドは壊れたままになる。周知を忘れずに。

対処方法の比較

方法手軽さリスク推奨場面
match nuke → 再生成やや手間低（手順通りなら安全）基本の対処法
--force で強制再生成手軽中（古い証明書が残る）急ぎの場合のみ
App Store Connect で手動発行手間大高（match との整合性が崩れる）非推奨

App Store Connect を手動操作すると match との整合性が崩れて二次被害が出やすい。操作は必ず match 経由で統一するのが鉄則。

再発防止：証明書の有効期限を仕組みで監視する

Apple の証明書は 1年で期限切れになる。突然のビルド障害を防ぐには定期的な更新を CI のスケジュールジョブに組み込んでおくのが一番楽だ。

# GitHub Actions で月次実行する例
on:
  schedule:
    - cron: '0 9 1 * *'  # 毎月1日 9:00 UTC
jobs:
  renew-certs:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v4
      - run: bundle exec fastlane match appstore
        env:
          MATCH_PASSWORD: ${{ secrets.MATCH_PASSWORD }}
          MATCH_GIT_BASIC_AUTHORIZATION: ${{ secrets.MATCH_GIT_AUTH }}

--readonly を外して実行すると、期限が近い証明書を自動更新してくれる。Slack 通知と組み合わせると気づきやすい。

よくあるハマりポイント

Q. nuke したのに App Store Connect に古い証明書が残っている
→ Developer Portal の API 反映に数分かかることがある。しばらく待ってリロードすること。

Q. MATCH_PASSWORD を紛失した
→ ローカルの環境変数や CI の Secrets を確認する。完全に紛失した場合は nuke でリポジトリをリセットし、match init で新しいパスワードを設定するしかない。MATCH_PASSWORD は 1Password などのパスワードマネージャーで必ず管理すること。

Q. ローカルは通るが CI だけ失敗する
→ setup_ci の呼び忘れか、Keychain のロック解除パスワードが違う可能性が高い。Fastfile の setup_ci 呼び出し位置と CI の環境変数を確認する。

まとめ

Fastlane match の証明書期限切れは nuke → 再生成 の手順を踏めば確実に復旧できる。焦って App Store Connect を手動操作するのが最大の落とし穴で、match との整合性が崩れて二次被害に発展しやすい。

定期的な証明書更新を CI のスケジュールジョブに組み込んでおけば、ほぼ再発しない。Fastlane の活用法を体系的に学びたいなら {{AMAZON:iOSアプリ開発 自動化レシピ|Fastlane・CI/CD・署名まわりを体系的に解説}} も参考になる。証明書の有効期限ポリシーや料金は変更される可能性があるため、最新情報は必ず Apple Developer の公式ドキュメント で確認してほしい。

#Fastlane #iOS #証明書 #CI-CD #コード署名 #match