Xcode Cloudのプライベート依存関係取得失敗への対処：2026年トラブルシューティングガイド

症状：Xcode Cloudでプライベート依存関係を取得できない場合は、まずビルドレポートで失敗段階を特定し、認証・依存解決・スクリプトの該当箇所を直してください。
最短の判断：私有依存があるだけでCIを移行する必要はありません。現在のワークフローで満たせないプライベートネットワーク接続やツール要件が確認できた場合に、自前のMacビルド環境を検討します。

Xcode Cloudのワークフローを管理し、ビルドレポートから依存取得の問題を解決したいエンジニア向けです。
社内Swift Package、Gitサブモジュール、複数のリポジトリを保守するチーム責任者は、認証と依存解決を確認できます。
CIの実行環境を選定するIT担当者は、必要なネットワークやツールが現在の構成で満たせるか判断できます。

ビルドレポートで失敗段階を特定する

同じ「依存関係を取得できない」症状でも、リポジトリの複製、Swift Packageの解決、カスタムスクリプト、Xcodeのビルドでは確認箇所が異なります。エラー文だけで原因を決めつけず、ビルドレポートで最初に失敗した処理と、その直前のログを確かめてください。

Xcode Cloudは、依存先のリポジトリや必要なサードパーティーツールにアクセスできない場合、ビルドに失敗することがあります。ただし、これは調査の手掛かりであって、特定のエラーだけから根本原因が確定するわけではありません。Appleの依存関係準備に関する説明とワークフロー設定の資料を参照し、実際のログと照合します。

プライベートなSwift Packageに接続できない場合、どこを確認しますか。
まず、パッケージが実際に置かれているコード管理サービスと、そのリポジトリへのXcode Cloudの接続状態を確認します。アプリ本体のリポジトリにアクセスできても、依存パッケージが別の場所にあれば、その依存先の認証が別途必要な場合があります。Appleのコード管理接続に関する説明と依存関係の設定を見比べ、失敗した対象をログから特定してください。

注意：接続の状態だけでなく、失敗したビルドが参照している依存先のURLも確認します。開発者のローカル環境で取得できることは、CI環境から同じリポジトリにアクセスできる証明にはなりません。

リポジトリ認証と複数インスタンスの確認

プライベートリポジトリを追加したあとにビルドが失敗した場合は、アプリ本体だけでなく、Swift Package、Gitサブモジュール、スクリプトが参照するリポジトリも確認対象に含めます。Appleの案内に沿って、失敗したビルドのレポートにアクセス許可を求める案内が出ていないか確認し、対象リポジトリへの接続を完了してください。

プライベートなGitサブモジュールも別途認証を確認すべきですか。
はい。サブモジュールが別リポジトリを参照しているなら、そのリポジトリにもビルド環境からアクセスできる必要があります。トップレベルのリポジトリだけ認証済みでも、サブモジュールの取得段階で失敗する可能性があるため、ビルドレポートに記録された取得先を確認します。

同じコード管理サービス内の複数インスタンスと、異なるサービス上のリポジトリは分けて考えます。アプリ本体と依存先が異なるインスタンスにある場合、最初の接続が済んでいても、未接続のインスタンスへのアクセス許可が必要になることがあります。後続のビルドで接続を促す表示が出た場合は、その案内から該当するインスタンスを認可してください。これはすべてのアカウント権限を見直す一般的な手順ではなく、実際に使うリポジトリへの接続確認です。

ここでの評価は原因を断定するスコアではなく、調査順を決めるための目安です。Appleはコード管理の接続設定を案内していますが、個々の企業アカウントでの接続可否は、構成とビルドレポートで確かめる必要があります。

Package.resolvedと依存解決の整合性

Package.resolvedが欠けている、または変更がコミットされていないと、チームのローカル環境とCIの依存解決結果が一致しない可能性があります。まず、Xcodeプロジェクトが使うファイルの配置と、失敗したビルドが参照するブランチ上のコミットを確認してください。

Package.resolvedが未コミットだと、ビルドにどう影響しますか。
ロックされた依存バージョンをビルド環境が参照できず、意図した解決状態と異なる結果になる可能性があります。チームの開発環境で成功していても、その状態がリポジトリに記録されていなければ再現できるとは限りません。Swift PackageをCIで扱うAppleのガイドを確認し、対象プロジェクトのロックファイルをバージョン管理に含めているか照合します。

「自動で依存関係を解決し直す」設定を、最初の修正として使うのは避けてください。ロックファイルの不整合を隠したり、失敗時の条件を変えたりする可能性があるためです。先にファイルの配置、コミット履歴、チームが意図した解決状態を確認し、その後に必要性を判断します。

ツール準備とカスタムスクリプトの失敗

CocoaPodsやCarthageなどを使うプロジェクトでは、依存管理ツールの導入方法とロックファイルの管理状態を確認します。ビルド環境に開発者のMacと同じツールや設定があるとは限らないため、必要なツールをどの手順で用意しているかをワークフロー上で明確にしてください。Appleのカスタムビルドスクリプトの説明では、スクリプトを使ってビルド前後の処理を実行する方法が案内されています。

post-clone、pre-xcodebuild、post-xcodebuildのどこで止まるかによって、見るべき処理は異なります。スクリプト名と配置、参照するファイル、終了状態、出力ログを確かめ、管理者権限やローカル端末にだけ存在する設定を前提にしていないかを点検します。実行に必要な環境変数はAppleの環境変数リファレンスで確認し、ワークフロー固有の条件はワークフローリファレンスと照合してください。

スクリプトに認証情報を直接書いたり、秘密情報をログへ出したりしないでください。プロキシ設定や社内ネットワークへの接続が必要なら、実行環境で利用できることを別途検証し、未確認の権限や端末状態を暗黙の前提にしない設計にします。

• [ ] ビルドレポートで最初に失敗した処理と、直前のログを確認した
• [ ] アプリ本体、Swift Package、Gitサブモジュール、スクリプトが参照する取得先を洗い出した
• [ ] 依存先のコード管理サービスと対象インスタンスの接続状態を確認した
• [ ] Package.resolvedの配置、コミット状況、チームの意図した解決状態を照合した
• [ ] 第三者ツールの導入手順とロックファイルの管理を確認した
• [ ] カスタムスクリプトの実行段階、配置、終了状態、参照ファイルを確認した
• [ ] ネットワーク、プロキシ、環境変数、秘密情報の扱いを検証した
• [ ] 再実行で同じ条件を再現し、修正前後のレポートを比較した

実行環境を変える判断基準

上の確認でリポジトリ認証やロックファイルの問題が解消するなら、Xcode Cloudを継続するのが自然です。一方、ワークフローが必要とするプライベートネットワークや固定ツール環境を現在の実行方法で用意できないと確認できた場合は、自前のMacを含む別環境の検証に進みます。要件を満たせるかは、実際の接続先、認証方式、ツール導入手順を使って確かめてください。

自前のMac環境なら、社内ネットワーク経路や導入ツールをチーム側で調整しやすくなる場合があります。ただし、OSやツールの保守、認証情報の保護、ビルド環境の再現性も運用側の責任になります。Xcode Cloudの接続と自前環境の違いは、Mac環境の選択肢を比べる案内も参考にしながら、要件ごとに整理できます。

現行のワークフローで不足が出やすいのは、社内ネットワークへの経路、チーム固有ツールの導入制御、実行環境の継続的な管理です。これらが実際のログや再現テストで問題になったときは、Mac環境を借りて要件を満たせるか検証する選択肢があります。zshmacの環境でも、利用したいリポジトリへの接続や必要なツールが成立するかを事前に確かめ、要件に合わない場合は移行しない判断をしてください。確認方法や利用条件はzshmacの案内で確認できます。