Xcode Cloudのビルド失敗は、まずレポートで失敗したアクションとログを確認し、その後、同じコミットを再現してワークフロー環境・依存関係・権限を切り分けます。Xcodeを開いて状態を比べる必要がある場合に限り、遠隔Macでの対照を検討してください。環境を変えるだけでは、クラウド側の設定やアクセス権の問題は解決しません。
アプリの運用・製品担当者：失敗がコード、設定、ワークフローのどこにあるか判断したい方。
iOSプロジェクトの協力者：失敗したコミットを再現し、依存関係やスキーム、権限を確認したい方。
macOS環境の責任者：手元のMacと比較する必要があるか判断したい方。
最初にビルドの最終状態と失敗アクションを分けます
「成功ではない」というだけで、コードのコンパイルエラーとは限りません。レポートの最終状態と、どのアクションで処理が止まったかを別々に確認します。Appleのビルド完了状態の定義でも、状態は区別されています。
失敗、処理中のエラー、キャンセル、スキップでは、次に調べる場所が異なります。たとえば、ビルドやテストのアクションで失敗したなら、そのアクションのログを確認します。手動または自動のキャンセル、条件によるスキップなら、コード変更より先に実行の経緯やワークフローの条件を確認してください。
メール通知の要約だけでは、失敗した処理や最初の関連エラーが分からないことがあります。まず何を記録すればよいですか？ 失敗したコミット、ワークフロー名、失敗アクションの3点を控え、レポートと対応づけます。
レポートから失敗したアクションのログを開きます
XcodeのReport navigator、またはApp Store ConnectのXcode Cloud画面から対象のビルドレポートを開きます。アクションを展開してログを確認し、通知文ではなく、失敗箇所に近い最初の関連エラーを手がかりにします。Appleの一般的な設定・ビルド問題の確認項目も、原因を切り分ける際の参照先になります。
ログの前後にある処理も見てください。依存関係の取得が始まる前に止まったのか、コンパイル中なのか、テストや署名など後続のアクションなのかで、調べる対象が変わります。ログを共有する場合は、アカウント情報、トークン、顧客データなどを除いたうえで、失敗箇所の前後が分かる範囲を残します。
Xcode Cloudのビルドログはどこで確認できますか？
対象のビルドレポートをXcodeまたはApp Store Connectで開き、失敗したアクションを展開します。表示される場所や操作の詳細は、利用中の画面とAppleの初回ワークフロー設定ガイドで確認してください。
同じコミットを再現してクラウドとの差を見ます
ローカルで最新のブランチをビルドして成功しても、失敗したビルドの原因が解消した証拠にはなりません。失敗時のコミットをチェックアウトし、問題が起きたアクションと同じ操作を試します。Appleも、失敗したビルドに対応するコミットを使ったローカルでの再現を案内しています。
特定の失敗ビルドをどう再現すればよいですか？
ビルドレポートでコミットを特定し、その状態をチェックアウトしてから、失敗したアクションに相当するビルドまたはテストを実行します。再現できたかどうかだけでなく、実行条件やログもクラウド側と照合してください。
| 確認する場所 | 分かること | 次の判断 |
|---|---|---|
| Xcode Cloudのレポートとログ | 失敗状態、アクション、エラーが発生した位置 | 失敗箇所に対応する設定や処理を調べます |
| 失敗コミットを使ったローカル環境 | 同じコードで問題が再現するか | 再現するならプロジェクト側、しないなら実行環境や条件の差を調べます |
| 遠隔Macなどの別のmacOS環境 | Xcodeを使った対話的な確認や環境差 | 差が分かっても、クラウド側の権限や障害とは分けて対応します |
再現しない場合は、コミットが一致しているか、ワークフローの実行条件や環境が違わないかを見直します。一度ローカルで成功しただけで、クラウド側の問題が解決したと判断しないことが大切です。
ローカルで再現しないことは、クラウド側に問題があるという確定材料ではありません。コミット、ワークフローの条件、ツールや依存関係の違いを順に照合します。
環境と依存関係はワークフロー設定から確認します
macOSやXcodeの環境、必要なツール、依存関係の取得状況を確認します。Xcode Cloudで選択されている環境と、プロジェクトが前提としている設定が合っているかは、ワークフローのリファレンスに照らして確認してください。対応環境は変わる可能性があるため、古い記事のバージョン要件を現行の保証として扱わず、公開中の公式情報を参照します。
Swift PackageやCocoaPodsなどを使う場合は、必要な依存関係のファイルがプロジェクトに含まれているか、クラウド環境から取得可能かを確認します。Appleの依存関係をXcode Cloudで利用可能にする説明も参照してください。取得できない場合は、ネットワークや認証、リポジトリへのアクセスの問題と、ソースコードのコンパイルエラーを分けて調べます。確認できていない汎用コマンドを貼り付けて、設定を変更するのは避けてください。
依存関係を取得できない、またはリポジトリにアクセスできない場合は？
まず、ワークフローが参照するリポジトリと必要なファイルを確認します。依存先へのアクセスや認証に問題があるなら、その経路を修正します。依存関係の取得が成功してからコンパイルが失敗する場合は、ログのエラーに沿ってプロジェクト側を調べます。
権限、スキーム、能力設定は個別に点検します
リポジトリに接続できない場合は、ワークフローから必要なリポジトリへアクセスできる設定かを確認します。Xcode Cloudがスキームを見つけられない場合は、対象スキームが共有され、プロジェクトで利用可能かを調べます。
能力や署名に関するエラーは、アプリのApp IDに必要な能力とプロジェクト側の設定を照合してください。権限や署名の設定は、別のMacを使うだけでは修復されません。画面上の手順や現在の設定方法は変更されることがあるため、Appleの現行ドキュメントで確認し、権限の変更はチームの承認を得て行います。
遠隔Macで対照する範囲を決めてから再実行します
どの段階でローカルMacによる確認が役立ちますか？
同じコミットのプロジェクトをXcodeで開き、状態や設定を対話的に調べたい場合です。クラウドのログだけでは確認しにくいローカルのプロジェクト状態を比べられます。ただし、遠隔MacはXcode Cloudのログ確認、リポジトリ権限の修正、プラットフォーム側の処理に代わるものではありません。
作業は次の順で進めます。
- ビルドレポートで最終状態と失敗アクションを確認します。
- 失敗したコミットとワークフロー名を記録します。
- 失敗アクションを開き、最初の関連エラーと前後のログを確認します。
- 同じコミットをチェックアウトし、失敗した操作をローカルで試します。
- ワークフロー環境、依存関係、リポジトリ権限、スキーム、能力設定をログに沿って点検します。
- 必要な修正後、同じワークフローを再実行し、レポートとログで結果を確かめます。
再実行が成功したか、同じアクションで再び止まったかを確認して、排查を終えるか次の調査に進むかを判断します。ビルド、署名、審査の成功を、Mac環境の変更だけで保証することはできません。
クラウドのログ確認だけでは対話的なXcode操作や同一コミットの比較が難しい一方、別の環境を用意しても、アクセス権やワークフロー設定の不備は残ります。ローカルMacを購入するほどではないものの、一定期間、実際のプロジェクトをmacOS上で確認したい場合は、DebugMacの遠隔Macを選択肢として検討できます。利用前には、失敗コミットへのアクセス、必要なファイルの受け渡し、Xcodeで行う操作を自分たちのプロジェクトで確かめてください。
利用の判断材料を探している場合は、DebugMacのガイド一覧を確認し、必要な作業が遠隔Macに合うかを見極めてください。環境が適していると確認できた場合に限り、DebugMacの案内から利用条件を確認できます。
ビルド失敗の再現検証に、DebugMacの専用Macを
DebugMacでは、Mac mini M4を搭載した専有物理ノードを、ほかの利用者と実行環境を共有せずにご利用いただけます。