非公開Swiftパッケージの取得で失敗し、Xcode 27のリモートビルドが止まる。 まず失敗箇所をログで特定し、実際のリポジトリURL、macOSの実行ユーザー、認証情報の出どころを確認してから、Package.resolvedがバージョン管理に含まれているか調べてください。Xcode Cloudと自前のMacでは認証手順が異なります。トークンや秘密鍵をリポジトリやURLに埋め込んではいけません。
本記事は、ローカルでは構築できるのに、リモートMacの依存解決で止まる独立開発者や小規模チーム向けです。 xcodebuildを管理する人は、SSH設定と実行ユーザーの違いを切り分けられます。 Xcode Cloudに非公開依存を追加したばかりのチームは、プラットフォームの認可と自前環境の設定を混同せずに確認できます。
失敗段階を特定して、認証問題と決めつけない
最初に見るのは、ビルド全体の成否ではなく、ログ上で最初に失敗した処理です。Swift Package Managerの依存解決時に止まったのか、取得後のSwiftコンパイルで止まったのかを分けてください。コンパイルエラーなら、認証情報を変更しても直りません。
Xcodeのビルドレポート、または実際に使うコマンドラインの出力から、失敗した依存名、リポジトリへの接続結果、エラーが出た処理を確認します。xcodebuildの実行方法は、AppleのXcodeコマンドラインツール資料を参照し、CIのログでも同じ入口を調べてください。
記録するのは、ビルドを開始した仕組み、作業ディレクトリ、macOS上の実行ユーザーです。画面から手動で起動したビルドが成功しても、別ユーザーの自動実行まで認証できているとは限りません。
接続先・認証・再現性を環境別に見比べる
次の比較で該当する環境を選び、確認手順を分けてください。適合度は環境と手順の相性を示す目安で、ビルド成功を保証するものではありません。
| 確認項目 | 自前のリモートMac | Xcode Cloud |
|---|---|---|
| 認証の確認先 | ビルドを起動するmacOSユーザーのSSH・Git設定。自動実行ユーザーでの検証が必須です | SCM連携と、非公開依存関係向けの認可設定。Appleの案内に沿って確認します |
| SSH設定の持ち込み | 対象ユーザーの鍵、ssh-agent、known_hostsを確認します | 自前のMacのSSH設定を流用せず、Xcode Cloudの認可手順を確認します |
| 依存バージョン | Package.resolvedの配置、コミット状態、実際の解決結果を照合します | CIの依存解決でロックファイルが使われる状態か確認します |
| 適合度 | ◎：SSH設定を管理できる場合 | ◎：Xcode Cloudの連携設定を管理できる場合 |
URLと実行ユーザーからアクセス経路を点検する
プロジェクトのPackage.swift、Xcodeのプロジェクト設定、Package.resolvedに記録された依存元を照合します。実際のビルドが参照するのがSSHかHTTPSか、ホスト名とリポジトリのパスが想定どおりかを確認してください。Swift Packageの依存元の定義は、AppleのPackage.Dependency資料で確認できます。
次に、ビルドを実行するユーザーの権限で、対象リポジトリへ接続できるかを検証します。確認の結果は「ホストに到達できるか」「リポジトリの場所が正しいか」「指定したブランチやタグが存在するか」「認証後に読み取れるか」に分けて記録します。
URLの書き換えは、参照先が間違っていると確認できた場合に限って行います。認証エラーに見えるメッセージでも、DNS解決やネットワーク到達性、存在しないリポジトリ名が原因の場合があります。URLを変えて直ったように見えても、意図しないリポジトリを参照していないか確かめてください。
SSH鍵やトークンをURL、スクリプト、ログに含めないでください。秘密情報が一度でも共有ログなどへ出力された疑いがあれば、削除だけで済ませず、漏えいした認証情報の失効・交換を先に計画します。
実行ユーザーの認証情報を環境に合わせて確認する
自前のMacでは、XcodeまたはxcodebuildがどのmacOSユーザーとして動くかを調べます。手動ログインした開発者のホームディレクトリに鍵があっても、CI用アカウントのホームディレクトリから同じ鍵やGit設定が参照できるとは限りません。
SSHを使う場合は、該当ユーザーの秘密鍵、ssh-agentの読み込み状態、known_hostsによる接続先の確認、Gitの設定を点検します。設定変更後は、そのユーザーが実際のビルド入口からリポジトリを読み取れることを検証してください。Appleのソースコード管理の認証設定も確認材料になります。
Xcode Cloudを使う場合は、Mac上のSSH鍵を複製するのではなく、Xcode Cloudのワークフローで対象のソースコード管理先へ認可を設定します。接続手順の詳細はAppleのXcode Cloud接続ガイドを参照し、表示される設定項目は利用中の環境で確認してください。
Package.resolvedで依存関係の再現性を確認する
認証が通っても、依存解決の結果が意図と異なれば、別のビルド失敗が起こり得ます。Package.resolvedがプロジェクト構成に適した位置にあり、CIが使う作業ツリーに含まれているかを確かめ、バージョン管理上の状態とビルドログの解決結果を比較してください。
AppleはCIでPackage.resolvedを使い、Swiftパッケージの依存バージョンを固定する方法を案内しています。設定を確認するときは、SwiftパッケージのCI構築ガイドに照らして、プロジェクトに合ったファイルの配置とコミット状態を検証します。
ロックファイルの不備を、強制的な再解決で覆い隠さないでください。意図しないバージョンへの更新や、認証問題の見落としにつながります。また、macOSのGit設定を利用したい場合は、Xcodeが使うGitの動作を決めつけず、現在のXcode環境とAppleの説明に基づいて適用可否を確認します。
修正前に変更範囲と戻し方を決める
確認作業では、何を変えるとどこへ影響するかを先に整理します。認証鍵の交換は、その鍵に依存する別のビルドにも影響する場合があります。共有Git設定の編集は、同じユーザーが実行する他のリポジトリの動作を変える可能性があります。
キャッシュ削除も最初の修復手段にはしません。原因がURL、権限、鍵、ロックファイルのどれかを確認してから、対象を絞って実施します。変更前の設定を安全に記録し、問題が悪化した場合に戻せる状態を用意してください。
同じ実行条件で修復を受け入れる
次の項目を満たしたら、修正を完了扱いにします。ローカルの開発者アカウントで成功しただけでは、リモートMac iOS構築の受け入れ確認にはなりません。
- [ ] 実際のCIと同じ構築入口、作業ディレクトリ、macOSユーザーでテストしています。
- [ ] 使用した依存URLが意図したリポジトリを指し、指定ブランチまたはタグが確認できています。
- [ ] ビルドを実行するユーザーから認証が機能し、私有リポジトリの取得結果をログで確認できています。
- [ ] Package.resolvedが想定した場所とバージョン管理の状態にあり、解決された依存バージョンが期待と一致しています。
- [ ] 秘密情報がリポジトリ、コマンド出力、共有ログ、URLへ記録されていません。
- [ ] クリーンな作業領域でも依存解決と最終ビルドを実行し、結果を再確認しています。
よくある疑問への確認事項
ローカルで通るのにリモートだけ失敗する場合
ローカルで使っている開発ユーザーと、CIの実行ユーザーの差を最初に調べます。鍵やGit設定がユーザー単位で異なるほか、CIが別の作業ディレクトリやリポジトリURLを参照していることもあります。失敗ログを依存取得時点までさかのぼり、接続先と認証の結果を別々に確認してください。
自前のMacでSSHを使う場合
秘密鍵を、実際にビルドを実行するユーザーから読み取れる状態にします。加えて、ssh-agent、known_hosts、Gitの設定、対象リポジトリへの読み取り権限を確認します。対話セッションでは成功しても自動実行では失敗する場合があるため、本番と同じユーザー・入口で検証してください。
Xcode Cloudでの認可
Xcode Cloudでは、ワークフローのSCM連携と非公開依存関係へのアクセス認可を確認します。自前のMacで使う鍵の配置手順をそのまま適用せず、Appleが案内するXcode Cloudの設定方法を使ってください。認可後は、対象リポジトリを実際に取得できることをビルド結果で確かめます。
Package.resolvedがない場合
ビルドが期待した依存バージョンを再現できているか判断しにくくなり、ローカルとCIで異なる解決結果になる可能性があります。プロジェクトの構成に合ったPackage.resolvedをバージョン管理に含め、CIがその状態を使っているか確認します。認証エラーを解決する代わりに、強制的な再解決を行うのは避けてください。
すでに自前のCI用Macを運用しているなら、手元のMacをそのまま使う方法は追加契約を避けられる一方、実行ユーザーの管理、秘密情報の保護、保守中の停止対応を自分で担います。一般的なクラウド環境だけで済ませる方法も、macOS固有のツールチェーンを動かすには適合しない場合があります。専用のMacが必要でも、購入すると初期費用と保守の負担が残るため、短期の検証やビルド環境の分離が目的なら、MACGPUのリモートMac環境の案内を確認し、必要な期間や接続方法が運用に合うかを判断してください。具体的なMac構成も比較したい場合は、Mac構成の案内も確認できます。安定した常時稼働や物理接続が必要な用途では、自前のMacを含めて比較するのが適切です。