pod が見つからない、または依存関係の導入でXcode Cloudのビルドが止まる。
最初の有効なエラーで失敗箇所を特定し、スクリプト、Podfile と Podfile.lock、依存先へのアクセスを順に確認してください。最初から依存関係を書き換える必要はありません。
CocoaPodsを使うアプリをXcode Cloudに接続し、依存関係の準備で失敗している個人開発者向けです。
ローカルでは通るのにクラウドのビルドだけ失敗する小規模チームや、Xcode Cloudを直すか自主管理のmacOS環境へ移すか判断したいリリース担当者にも役立ちます。
Xcode CloudでCocoaPodsのインストールに失敗したときの切り分け
ログに出た最後の行だけで判断せず、最初に現れた有効なエラーと、その直前まで成功していた処理を確認します。原因は「スクリプトが動いていない」「pod コマンドを実行できない」「依存関係を取得できない」「Podの導入後にXcodeのビルドが失敗する」などに分かれます。
Appleは、Xcode Cloudで依存関係を準備する方法と、カスタムビルドスクリプトの配置・実行方法を案内しています。まずは依存関係をXcode Cloudで利用可能にするAppleの説明とビルドスクリプトの仕様を、プロジェクトの設定と照らし合わせてください。
pod コマンドが見つからない場合
pod: command not found などが記録されている場合は、依存解決より前に、実行環境でCocoaPodsを利用可能にできているかを確認します。スクリプト内でインストールしているなら、コマンドが実行された記録だけでなく、インストール処理の終了状態と、その後の pod --version の出力もログで確かめます。
CocoaPodsを導入する処理は、依存関係の取得より前に実行される必要があります。Appleの説明にある ci_scripts 内のスクリプト配置と、実際に呼び出されるタイミングを確認し、意図した処理がビルドログに現れているかを見ます。ファイル名、実行権限、shebangが想定と異なると、スクリプトが存在していても期待した処理にならない場合があります。詳しい配置条件はAppleのカスタムビルドスクリプトの説明で確認できます。
CocoaPodsの導入スクリプトと実行環境
依存関係の取得前に pod install を実行する構成では、Appleが案内するスクリプトのファイル名と配置場所が、リポジトリ内の実物と一致しているかを確認してください。たとえば、チェックアウト後に準備を行う ci_post_clone.sh を使う場合は、そのスクリプトにCocoaPodsの導入と pod install が含まれているか、また処理の失敗が後続工程へ隠れていないかをログで追います。
シェルの種類をファイル名だけから決めつけず、shebangと実際のログを確認します。環境変数に依存する処理がある場合も、手元のターミナルで設定した値がクラウド上で同じように存在するとは限りません。Xcode Cloudの環境変数リファレンスと、ワークフローのソース管理設定を参照し、対象の処理に必要な値がビルド環境へ渡っているか確認します。
- [ ]
ci_scripts内のファイル名と配置が、Appleの説明に沿っている - [ ] 実行権限とshebangが設定され、ログにスクリプトの開始・終了が残っている
- [ ] CocoaPodsの準備が依存関係の取得より前に行われている
- [ ] インストールコマンドの終了状態と、後続の
pod実行結果を確認した - [ ] 認証情報をログへ出力せず、必要な環境変数だけを安全に渡している
Podfile.lock と依存関係の不一致
Podfile と Podfile.lock が同じ変更として管理されているか、ビルド対象のブランチに両方が含まれているかを確認します。ローカルでは更新済みのファイルを使っていても、コミット漏れやブランチの違いがあれば、Xcode Cloudは別の依存関係を解決しようとすることがあります。
すでにレビュー済みの依存関係でビルドしたいなら、まず正しい Podfile.lock をリポジトリに戻し、差分が意図した変更かを確認します。原因の切り分けをせずにロックファイルを削除したり、pod update で全体を再解決したりするのは避けてください。CocoaPodsの説明では、pod install はロックファイルに記録された依存関係を尊重する一方、pod update は対象Podの更新を行います。違いは公式ガイドで確認できます。
プライベート依存関係にアクセスできない場合
プライベートなPodの取得に失敗したら、リポジトリのURL間違い、認証情報の不足、認証情報に付与された権限、ネットワーク経路、依存先の応答異常を分けて調べます。ログにアクセス拒否がある場合は、単に再試行するのではなく、ビルド環境で使える資格情報が対象リポジトリを読み取れるかを管理者に確認します。
トークンや秘密鍵、認証ヘッダーを Podfile や公開サンプルへ直接書かないでください。ログ共有が必要な場合は、アカウント名、リポジトリの実URL、プロジェクト名、認証情報を伏せ、エラーの種類と処理の流れが判断できる範囲だけを共有します。Appleの一般的な設定・ビルドエラーの案内も参照し、認証の失敗と依存先の応答異常を混同しないようにします。
認証情報を消す際は、エラー行だけでなく、その前後に出力されたURLや環境変数も確認してください。値を伏せても、リポジトリ名やアカウント名からアクセス先が推測できる場合があります。
修復後に依存関係とビルドを再確認する手順
修正がキャッシュや手元の環境に偶然支えられていないことを確認するには、依存関係の入力を固定して再実行します。以下の順で記録を残すと、再発時に変更点を比較できます。
- 対象ブランチの
PodfileとPodfile.lockを確認し、意図しない差分があれば戻します。 - スクリプトの配置、権限、shebangを確認し、修正内容をリポジトリへ反映します。
- プライベート依存関係がある場合、ビルド環境で必要な資格情報と最小限のアクセス権を確認します。
- Xcode Cloudで新しいビルドを実行し、依存関係の取得・導入のログを確認します。
- Podの処理が通った後、Xcodeのコンパイルや後続工程も完了するか確認します。
- 使用したブランチ、環境設定、ロックファイルの状態、最初の有効なエラーを記録します。
Appleの依存関係に関する案内に照らし、修正後の処理が構成と矛盾していないかも確認してください。ビルド環境を切り替えた場合は、依存関係の取得から後続のビルドまで改めて検証します。ログで確認できた事実だけを復旧結果として扱い、特定の所要時間や成功率を前提にしないことが重要です。
Xcode Cloudを直すか、管理できるMac環境へ移すか
次の条件に沿って判断してください。
- ログにスクリプトの起動がない場合：まずファイルの配置、名前、実行権限、ワークフロー設定を直し、同じ環境で再確認します。
podが見つからない場合：CocoaPodsの準備処理と実行順を修正します。スクリプトで解決できるなら、環境を移す前にその方法を検証します。- ロックファイルや依存先の問題が原因の場合：正しいロック状態、URL、資格情報を修正し、同じ入力で再ビルドします。
- 必要な権限やmacOS上のツールをXcode Cloudの範囲内で用意できない場合：権限、環境制御、資格情報の管理責任を整理してから、自主管理の遠隔Macへ移す案を比較します。
Xcode Cloudはビルドスクリプトで一部の追加ツールを準備できますが、スクリプトだけですべての環境要件や権限上の制約を解消できるとは限りません。移行先ではツールや認証情報を自分で管理できる反面、macOS環境の保守、アクセス制御、依存関係の再現確認も担当することになります。CocoaPodsの構成を遠隔環境で再現する作業には、遠隔MacでのCocoaPods依存関係の準備に関するガイドも参考になります。
Xcode Cloudで解消できる設定ミスまで環境移行で覆い隠す必要はありません。一方、依存導入に必要なツールや資格情報の扱いを自分で制御する必要があり、クラウド側の制約が原因だとログで確認できたなら、管理できる遠隔Macを比較対象に加えるのは妥当です。共有環境の制約や調整作業が残るクラウド運用に対し、レンタルしたMacでは環境の管理範囲を広げられる可能性がありますが、保守と資格情報管理は利用者側の責任として残ります。
環境を一時的に用意して検証したい場合は、KVMFLUXの利用用途と料金・契約条件を確認し、プロジェクトの要件に合うか判断してください。まずガイドに沿って移行後の検証項目を整理し、Xcode Cloudで修復できる問題か、管理環境が必要な問題かを切り分けてから選ぶと、不要な環境変更を避けられます。