ローカルでは署名できるのに、GitHub Actionsでは証明書が見つからない、またはアーカイブで失敗する。 まずRunnerが実際に使うmacOSアカウントとmacOS Keychainを確認し、その後で署名IDとプロビジョニングプロファイルの対応を調べます。SSHでの成功だけを根拠にせず、権限を広げたり証明書を繰り返し読み込んだりする前に、Workflowのログで責任範囲を切り分けます。
iOS／macOS開発者：ローカルとCIで署名結果が異なる場合に、プロジェクト設定とホスト環境を分けて調べられます。
DevOps担当者：自ホストMac Runnerの実行アカウント、サービス状態、ログを確認できます。
リリース・資格情報管理者：証明書、秘密鍵、Keychain、プロファイルの担当範囲とアクセス制御を整理できます。
[ SECTION_01 ] GitHub ActionsのXcode署名失敗は、ログと責任範囲から切り分けます
最初に確認するのは、どの工程で失敗したかです。コンパイル、アーカイブ、署名IDの選択、署名処理をひとまとめに「証明書の問題」と扱うと、設定変更の対象を誤ります。ローカルとCIで同じコミット、Scheme、ビルド対象を使い、同じWorkflow実行のログを調査の基準にします。
| ログで見える状況 | 主に確認する担当 | 切り分けの確度 | 次に見る証拠 |
|---|---|---|---|
| ビルド設定や対象が想定と異なる | iOS開発者 | 高 | Scheme、Target、ビルド設定、実行ログ |
| SSHでは使える署名IDがRunnerでは選べない | CI運用担当 | 高 | 実行アカウント、Runnerログ、Keychainの状態 |
| 署名IDは見えるが対象アプリに署名できない | 署名管理者 | 中 | 秘密鍵へのアクセス、Bundle Identifier、プロファイル |
| ビルドは通るが配布用アーカイブを検証できない | リリース担当 | 中 | アーカイブの署名結果、配布目的、実際の成果物 |
Xcodeの設定値とビルド結果は、AppleのBuild Settings Referenceやアプリのビルドと実行に関する説明と照らします。設定画面だけで判断せず、Workflowが出力したビルド設定とログも残してください。
ローカルでは署名できるのに、GitHub Actionsで証明書が見つからない場合は、何を先に比べますか。
同一コミット、同じSchemeとTargetを使っているかを先に確認します。次に、ローカルで選ばれた署名IDとCIのログに記録された選択結果を比べます。差があればプロジェクト設定か実行環境かを絞り、証明書を入れ直す前に担当者へ証拠を引き継げます。
iOS開発者はプロジェクトの署名先を特定します
自動署名と手動署名では、確認する設定と期待する動作が異なります。Scheme、Target、署名方式、ビルド引数を確認し、CIが意図した構成を選んでいるかをログとプロジェクト設定で照合します。特にBundle Identifier、Team ID、プロビジョニングプロファイルの対象が同じアプリを指しているかを確認します。
Appleのコード署名IDの説明では、署名IDは証明書だけでなく秘密鍵と結び付いたものとして扱われます。証明書名が設定に書かれていることだけでは、その実行環境から署名に使えるとは判断できません。
引き継ぎメモ： 開発担当者はコミット、Scheme、Target、署名方式、Bundle Identifier、Team IDを記録します。値が期待どおりで、失敗が署名処理に限定される場合は、Runnerの実行環境を管理する担当へ引き継ぎます。
[ SECTION_02 ] Runner運用担当は実行アカウントとKeychainを確認します
SSHログインに使うアカウントと、Runnerサービスやプロセスが使うアカウントは、同じとは限りません。デスクトップのターミナルで署名確認に成功しても、Workflowの実行主体が同じKeychainへアクセスできる証拠にはなりません。GitHubの自ホストRunnerの監視とトラブルシューティングを参照し、Runnerのログとサービス状態を確認します。
SSHでは署名できるのに、Runnerの実行時に失敗する場合は、どのアカウントとKeychainを確認しますか。
Workflow内で実際に動いているプロセスの実行アカウントを確認します。SSHセッションの結果とWorkflow内の確認結果は別々に記録し、Keychainがその実行環境で利用可能かを調べます。Runnerがlaunchdで管理されている場合は、サービスの状態とRunnerログを合わせて見ます。
| 確認場所 | 観察できる情報 | 誤判定を避けるポイント |
|---|---|---|
| SSH接続後のターミナル | 対話セッションのユーザーとKeychain | Runnerと同じ実行主体とは限りません |
| Workflowのログ | Jobの実行中に取得した環境情報 | 実際のCI実行結果を基準にします |
| Runnerサービスの記録 | サービス状態とRunner側のログ | launchd管理時は対話セッションと分けて調べます |
GitHubのRunnerアプリケーション設定に関する説明も確認し、サービス管理やログ調査の手順を環境に合わせます。対話型セッションだけで確認を終えず、必要な観察情報をWorkflow側でも取得してください。
[ SECTION_03 ] 署名管理者は証明書、秘密鍵、プロファイルを照合します
署名IDが一覧にあることと、そのIDで現在のWorkflowが署名できることは別の確認事項です。Appleのコード署名証明書に関するテクニカルノートを手がかりに、対象の証明書と秘密鍵が対応しているか、実行環境から利用できるかを調べます。秘密鍵の有無やアクセス権を確認せず、証明書だけを再インポートしても原因が残ることがあります。
続いて、プロファイルのアプリ識別子、Team ID、用途をビルド対象と照合します。AppleのApp Store配布用プロビジョニングプロファイル作成手順を参照し、プロファイルが意図したアプリと配布先に対応しているかを確認します。
署名IDが存在するのにXcodeが署名できない場合、次に何を確認しますか。
まず、そのIDに対応する秘密鍵をRunnerの実行環境が利用できるか確認します。利用できる場合は、Bundle Identifier、Team ID、プロファイルのアプリ識別子と用途を照合します。どの項目が一致しないかを特定してから、証明書またはプロファイルの変更を申請します。
変更前の注意： 既存の署名素材を削除・更新する前に、変更対象、承認者、復旧方法を記録します。認証情報を含むJobへアクセスできるリポジトリ、Workflow、担当者を確認し、不可信のタスクから本番署名素材を参照できない構成にします。GitHubのActions利用時のセキュリティに関する説明に沿って、アクセス範囲を必要最小限に抑えます。
[ SECTION_04 ] リリース担当は実アーカイブで修正を判定します
Runnerがオンラインになったことや、コンパイルが成功したことだけでは、リリース署名の復旧確認になりません。配布先に合った実際のWorkflowを動かし、署名の選択結果、アーカイブの検証、成果物を確認します。修正が別の実行でも再現するかも記録し、再現しない場合は本番リリースへ戻さず実行環境を調べ直します。
修正後に実行する確認項目
- [ ] ローカルとCIで同じコミット、Scheme、Target、署名方式を使っている
- [ ] WorkflowのログからRunnerの実行アカウントを確認できる
- [ ] 対話型ターミナルの結果とWorkflow内の結果を分けて記録している
- [ ] 署名IDと秘密鍵を、Runnerの実行環境から利用できる
- [ ] Bundle Identifier、Team ID、プロファイルの識別子と用途が一致している
- [ ] 本番署名素材にアクセスできるWorkflowとリポジトリを確認している
- [ ] 実際の配布対象でアーカイブと署名を検証し、成果物を確認している
- [ ] 変更の承認者、対象範囲、復旧手順を記録している
実行主体や権限の範囲が安定せず、修正の再現性を確認できない場合は、署名Jobをいったん分離し、専用Runnerを再構築する判断も必要です。アクセス制御を無効にしてエラーを消すのではなく、実行環境と署名素材の境界を整えてから公開作業へ戻します。
手元のMacや共有Runnerだけで運用すると、対話セッションとCIの差を見落としやすく、署名素材へのアクセス範囲も整理しにくくなります。一方、長期にわたって安定した高負荷運用を続け、物理的な接続や社内管理が必要なら、自社でMacを保有する方が適する場合があります。短期の検証や専用のCI実行環境が必要な場合は、NOVAKVMのリモートMac環境も比較対象にできます。NOVAKVMのMac環境を確認し、Mac miniを調達して自社運用する条件と比べる際は、Mac miniの注文案内も参照してください。