Xcode 27のプライベートSwift Package取得失敗？2026年修正ガイド

AppleのCI向け資料では、SSHで私有Swift Packageに接続する際、CI実行ユーザーの認証情報とknown_hostsの両方を整える必要があります。まず実行アカウントを特定し、そのユーザーのSSH設定を確認してから、Package.resolvedと依存URLを照合してください。主機検証を無効にしたり、最初にキャッシュを消したりするのは避けます。 (AppleのSwift Package CIガイド)

このガイドの対象 Xcode 27のプロジェクトをリモートMacでビルドし、私有Swift Packageを使う開発者向けです。認証エラー、ホスト検証エラー、依存バージョンのずれを切り分けます。
Mac CIの運用担当者は、実行ユーザーへの最小権限の付与方法を確認できます。ローカルビルドから移行中のチームは、問題がノードのアカウント設定かロックファイルかを判別できます。

ローカルのターミナルで取得できても、CIが同じログインユーザーで動いているとは限りません。RunnerやCIサービスが別のmacOSアカウントで起動していれば、管理者のホームディレクトリにある秘密鍵や~/.ssh/configはビルドから見えない可能性があります。

次のコマンドをCIのジョブ内で実行し、ログイン中のユーザーとホームディレクトリを確認します。出力にトークンや秘密情報を混ぜないよう、ログの保存先と閲覧権限もあわせて確認してください。

id -un
printf '%s\n' "$HOME"
printf '%s\n' "$SSH_AUTH_SOCK"

表示されたユーザーのホームディレクトリに、対象ホスト向けのSSH設定と必要な鍵が存在するかを確認します。鍵を登録しただけで済ませず、CIの実行プロセスからその鍵が利用できる状態かを検証するのが要点です。AppleのCIにおけるSSHエージェントの説明も確認し、対話ログイン時だけ有効なエージェントに依存していないか見直します。

鍵の権限はリポジトリを読むために必要な範囲に絞ります。GitHubを利用する場合、読み取り専用のDeploy keyの設定を使えるか検討し、書き込み権限を初期設定にしないでください。アクセスできないときは、鍵を広く配布する前に、実行ユーザーと対象リポジトリの組み合わせを確認します。

SSH鍵が正しくても、接続先のホスト鍵を確認できなければ接続は止まります。認証は「接続する資格があるか」、ホスト検証は「接続先が想定した相手か」を確認する仕組みで、片方の修正をもう片方の解決策として扱わないようにします。

CI実行ユーザーで次の点を確認してください。

• [ ] 依存パッケージのURLがSSH形式か、CIで使うホスト名と一致している
• [ ] 対象ユーザーの~/.ssh/known_hostsに該当ホストの登録がある
• [ ] フィンガープリントを公式の情報と照合したうえで登録している
• [ ] SSH設定のHost、IdentityFile、Userが依存URLに適用される

フィンガープリントは、GitHubが公開するSSH鍵情報など、利用先の公式情報と照合します。known_hostsの不一致は、古い登録の残存だけでなく接続先の誤りでも発生します。ホスト鍵検証エラーの案内に沿って原因を確認し、出所を確かめずに既存登録を置き換えないでください。

StrictHostKeyCheckingを無効にすると、接続先を検証できない状態を見過ごすおそれがあります。例外的に切り分けへ使う場合も、隔離された検証環境に限定し、原因確認後に設定を戻して再検証します。

SSHの設定が想定どおり適用されるかは、OpenSSHの設定項目と照らして確認します。管理者のアカウントで成功した事実だけでは、CIユーザーのknown_hostsや鍵が適切だとは判断できません。

私有Swift PackageのSSH鍵とknown_hostsはどのアカウントに置きますか

原則として、CIジョブを実際に実行するmacOSユーザーの設定領域に用意します。管理者セッションで設定した鍵をRunnerが自動的に引き継ぐとは限らないため、ジョブ内のid -unと$HOMEを基準に、鍵、SSH設定、known_hostsの配置先を確認してください。

認証に成功しているのに依存バージョンが異なる場合は、取得失敗とバージョン解決のずれを分けて調べます。プロジェクトに適用されるPackage.resolvedがコミットされているか、CIの作業ディレクトリから参照されているかを確認します。

続いて、ロックファイル内の私有パッケージのURLと、CIユーザーのSSH設定を照合します。URLに含まれるホスト名やアカウントが~/.ssh/configのルールに一致しなければ、意図した鍵が選ばれないことがあります。URLを直す場合は、ロックファイルだけを書き換えるのではなく、プロジェクト設定、リポジトリ側の依存定義、CIで実際に使う接続先を合わせて確認します。

AppleはCIで依存バージョンを固定するため、Package.resolvedのコミットを案内しています。また、直接xcodebuildを使う場合は、自動解決を無効にしてロックされたバージョンに従わせる方法が示されています。設定の意味を確認し、適用可能なビルドでは次のように実行します。 (AppleのCI向け依存関係設定)

xcodebuild \
  -resolvePackageDependencies \
  -disableAutomaticPackageResolution

この指定で解決が失敗する場合、最初にロックファイルを更新して失敗を隠すのではなく、依存URLへのアクセスとコミット内容を記録します。バージョンが違うのか、取得権限がないのかを、ログ上のエラー段階で判定してください。

Package.resolvedをコミットしたのに依存バージョンが変わる場合

まず、CIがそのファイルを含むブランチと作業ディレクトリをビルドしているかを確認します。次に、ビルドコマンドが自動解決を行っていないか、依存URLがロックファイルの記録と一致するかを調べます。原因が分かる前に依存を更新すると、元の認証エラーや参照先の誤りが見えにくくなります。

本機とCIでGitの動作が異なると、URL書き換え、プロキシ、SSHの特殊設定が依存取得に影響することがあります。システムGitとXcodeが利用するGitのどちらが実際に呼ばれているかを確認し、git config --show-origin --get-regexpなどで設定元を特定してから比較します。

git config --show-origin --get-regexp 'url\..*\.insteadof|core\.sshCommand'

表示された設定に、依存URLを書き換える規則や個別のSSHコマンドがある場合は、その設定がCI実行ユーザーに適用されているかを調べます。システムGitを使う方法を試すのは、ログや設定からGitの差が原因と判断できる場合に限ります。認証情報、Git設定、依存解決の手順を同時に変更すると、どの修正が効いたか特定しにくくなります。

Xcode 27のリリース状態や対応macOSは環境によって決めつけず、Appleのシステム要件と Xcode 27リリースノートで使用時点の情報を確認します。異なるXcodeやmacOSを使うノードを比較する場合は、各環境のバージョンを記録し、条件差を原因として混同しないようにします。

修正後は、元と同じコミット、同じ依存ロックファイル、同じビルドコマンドを使い、CI実行アカウントで再実行します。作業ディレクトリをクリーンにしたうえで、依存取得の成否、選択された依存バージョン、失敗した段階を記録します。ログには秘密鍵、トークン、機密性のある接続情報を残さないようにします。

次の条件分岐で、アカウント修正かノード分離かを判断します。

• 実行アカウントの鍵またはknown_hosts不足が原因で、権限を限定した設定を適用できる場合：共有ノードの権限を広げず、そのアカウントに必要な読み取り権限だけを設定して再試験します。
• 複数のジョブ間で認証情報を安全に分けられない場合：共有ノード上で鍵を共用せず、独立した実行アカウントまたは隔離したビルドノードへ切り替えます。
• 認証とホスト検証が成功し、依存バージョンだけが異なる場合：Package.resolved、作業ブランチ、解決オプションを確認し、認証設定をむやみに変更しません。
• ローカルとCIでXcodeやmacOSが異なる場合：各環境の組み合わせを固定して再現し、Appleの要件とリリース情報に基づいて比較します。

遠隔環境の運用を見直す際は、JEXCLOUDのリモートMac環境も、実行ユーザーや認証情報をどのように管理できるかという観点で確認できます。依存取得の安定性を評価する段階では、ノードの分離、復旧方法、秘密情報の保管範囲を先に要件化してください。

ローカルMacでの開発は手元での確認が容易ですが、常時稼働するCIノードとして使うと、個人アカウントへの依存、端末停止時のビルド中断、チーム間での認証設定のばらつきが問題になり得ます。共有クラウド環境はノード管理を減らせる一方、実行ユーザーと鍵の分離が十分でなければ、私有依存の権限管理が難しくなります。

長期にわたり重いビルドを安定して行う場合や、物理接続が欠かせない場合は、自社でMacを保有する案も比較対象です。一時的な移行検証や、CI用の隔離されたmacOS実行環境が必要で、ハードウェア購入や管理負担を避けたい場合は、JEXCLOUDのMacレンタルを候補として条件を確認できます。既存ノードのアカウント問題を直さずに環境を移しても同じ失敗を再現する可能性があるため、まず本稿の手順で原因を分離し、必要な分離レベルを決めてから利用可能なMac環境を検討してください。