DevOps / CI/CD2026年8月30日

SwiftPMプライベート依存関係：2026年リモートMac設定ガイド

ProxyMac Engineering Team2026年8月30日~5 分
SwiftPMプライベート依存関係：2026年リモートMac設定ガイド

Appleは継続的インテグレーションで利用する Package.resolved をソース管理に含める方法を案内しています。公式ドキュメントに沿えば、勝ち筋は明確です。リモートMacでは、専用のリポジトリ資格情報を、実際にビルドを実行するmacOSユーザーへ割り当て、Package.resolved を固定します。 先に依存関係の取得だけをクリーンなセッションで検証し、その後にコンパイルとアーカイブへ進めます。

対象となる開発者

ローカルMacからリモートビルド環境へ移行し、プライベートなSwiftパッケージを使う独立開発者や小規模チーム向けです。資格情報と依存関係の固定を優先して確認します。

SSHや定時タスクでiOSビルドを実行する開発者は、Xcodeの画面に残ったログイン状態ではなく、非グラフィカルなセッションを検証します。複数の私有リポジトリを管理するチームは、読み取り権限の範囲と鍵のローテーションも対象になります。

移行基準と権限分離

現在成功している状態を保存する

最初に、プロジェクトが直接参照するパッケージだけでなく、依存パッケージがさらに参照する伝播依存も一覧化します。各パッケージについて、リポジトリのURL、利用するブランチまたはタグ、読み取りに必要な権限を記録します。

現在のMacで成功した Package.resolved とコミット状態も保存します。Appleの依存関係仕様では、パッケージはURLやバージョン指定などを基に解決されます。依存関係の公式仕様を基準に、リモート環境で意図しない更新が起きない状態を作ります。

個人開発者が普段使う鍵をそのままコピーする方法は避けます。専用鍵は私有パッケージの読み取りだけに限定し、コード署名や公開作業の資格情報とは分けます。

管理対象 推奨する設定 避ける設定
リポジトリ用SSH鍵 ビルド専用。読み取り権限を限定 開発者個人の全権限鍵
コード署名用資格情報 別の保管場所と運用手順 リポジトリ鍵との共用
Package.resolved リポジトリへ登録し、変更をレビュー ビルド時の自動更新に任せる
秘密情報 鍵管理機構や保護された環境変数で供給 スクリプト、プロジェクト、履歴へ直書き

ビルドユーザーとSSH認証

GUIの成功をバックグラウンドへ持ち込まない

VNCでログインしたユーザーと、SSH、launchd、スケジューラーなどからビルドを起動するユーザーが異なると、SSH設定の参照先も変わります。~/.ssh、SSHエージェント、known_hosts、キーチェーンの状態は、実行ユーザー単位で確認します。

専用のmacOSユーザーを決めたら、そのユーザーでリポジトリへアクセスできるようにします。秘密鍵の作成とエージェントへの登録については、SSH鍵とエージェントの公式手順を参照できます。

ssh-keygen -t ed25519 -C "build-user"
ssh-add --apple-use-keychain ~/.ssh/id_ed25519
ssh -T git@ホスト名

上の例は認証の最小確認だけを示しています。実際の鍵ファイル名とホスト名は環境に合わせます。秘密鍵の内容やパスフレーズを、プロジェクトファイルやシェル履歴へ書き込んではいけません。

リポジトリ側へ登録する公開鍵は、専用ビルドユーザーのものだけにします。接続テストの成功メッセージだけで判断せず、対象リポジトリを読み取れるか確認します。SSH接続テストの公式説明も、接続先と認証結果を切り分ける材料になります。

注意：ホスト鍵の検証エラーを解消するために、ホストチェックを無効化する設定へ変更するのは長期対策になりません。正しいホスト鍵を確認し、対象ユーザーのknown_hostsへ登録してから再試行します。

認証方式 向いている場面 主な落とし穴
SSH鍵 無人の依存取得、定時ビルド 実行ユーザー、agent、known_hostsの不一致
HTTPS資格情報 手動の短時間確認 トークンの保管と期限管理
GUIログイン状態 Xcode画面での手動操作 バックグラウンド処理では再現しない

初回解析とPackage.resolved

依存関係だけを先に解決する

いきなりアーカイブを実行すると、認証失敗、ホスト検証失敗、バージョン解決失敗、コンパイル失敗が一つのログに混ざります。最初はビルドを止め、専用ユーザーの同じ作業ディレクトリから依存関係の解析だけを実行します。

xcodebuild -resolvePackageDependencies \
  -workspace Sample.xcworkspace \
  -scheme Sample

プロジェクト形式が異なる場合は、実際のワークスペースまたはプロジェクトに合わせます。Appleのコマンドラインビルドに関する公式資料では、xcodebuild を使ったビルド操作と引数の考え方が説明されています。

確認する結果は次の通りです。

  • すべてのプライベートパッケージが期待するリポジトリから取得される
  • Package.resolved の配置がプロジェクト構成と一致する
  • 解決されたバージョンやリビジョンが移行前の基準と一致する
  • 認証情報が求められる対話プロンプトに依存していない
  • 失敗時に、認証、ホスト検証、解決条件のどこで止まったか判別できる

Package.resolved は、CIで再現性を持たせるためにコミットする対象です。依存関係の更新が必要な場合は、開発環境で意図的に更新し、差分をレビューしてからリモートMacへ反映します。

xcodebuildが取得できない場合

まず、同じmacOSユーザーでSSHの単独テストを実行します。SSH単体が失敗するなら、xcodebuild の引数を増やしても直りません。

SSH単体が成功しているのに解析が失敗する場合は、次を分離します。

  • Git URLがSSH形式になっているか
  • known_hosts がビルドユーザーの環境にあるか
  • サブ依存のリポジトリにも同じ読み取り権限があるか
  • Package.resolved とプロジェクトファイルの組み合わせが正しいか
  • Xcodeのソース管理設定やSSH関連の引数を追加する必要があるか

GitのURLマッピングやプロキシなど、高度なソース管理設定を使う場合だけ、Xcodeのソース管理と継続的インテグレーションの説明を確認します。原因が不明なままキャッシュ削除を繰り返す方法は、再発条件を隠します。

コンパイルとアーカイブ

同じユーザーと作業条件で実行する

依存解析が成功したら、定時タスクと同じmacOSユーザー、作業ディレクトリ、環境変数で実際のプロジェクトをビルドします。VNC上のXcodeで一度成功しただけでは、無人ビルドの確認になりません。

アーカイブでは、次の順に結果を記録します。

検証段階 合格条件 不合格時の停止点
パッケージ解析 private packageの取得と固定版の確認 SSH、権限、URLを修正
ターゲットコンパイル 対象スキームが依存関係を解決して成功 Swiftバージョンや依存差分を確認
Archive 署名を含むアーカイブが生成される 署名資格情報を別系統で確認
ログ保存 コマンド、ユーザー、失敗箇所を追跡できる 再現条件を記録してから再実行

アーカイブと配布用署名は、依存取得の認証とは別の問題です。Appleのアーカイブとエクスポートに関する資料を参照し、リポジトリ読み取り用の鍵が公開権限を持たない構成を維持します。

無人実行と再起動後の復旧

SSHエージェントとキーチェーンを分けて確認する

SSH接続が手動では成功しても、SSHセッション終了後や再起動後に鍵が利用できるとは限りません。SSHエージェントの登録方法、キーチェーンの許可、定時タスクへ渡る環境変数を別々に確認します。パスフレーズ付き鍵をエージェントで扱う場合は、SSHパスフレーズの公式説明が基準になります。

再起動後にSSH鍵が失効したように見える場合、鍵そのものを作り直す前に、次の順で確認します。

  • ビルドタスクが想定したmacOSユーザーで起動しているか
  • SSH_AUTH_SOCKなどの環境が定時タスクへ渡っているか
  • 鍵がエージェントへ再登録されているか
  • known_hostsがユーザー領域から消えていないか
  • リポジトリ側で公開鍵が無効化または期限切れになっていないか

個人用鍵と署名用資格情報を分離しておけば、プライベートパッケージの読み取り鍵を交換しても、公開作業全体を止めずに済みます。鍵の読み込みに失敗した場合は、ホストチェックを無効化するのではなく、タスクを失敗として停止させます。

状態 確認する場所 復旧方針
手動SSHだけ成功 ログインシェルとagent 無人タスクの環境を再現
再起動後だけ失敗 agent、キーチェーン、known_hosts 起動時の登録処理を確認
一部パッケージだけ失敗 サブ依存のリポジトリ権限 公開鍵の読み取り範囲を追加確認
鍵の期限切れ リポジトリ側の認証設定 専用鍵だけを交換し、旧鍵を撤去

冷起動と依存更新の受け入れ基準

クリーンな作業ディレクトリから、依存解析、コンパイル、アーカイブを連続して実行します。その後、Macを再起動し、VNCへログインしていない状態で同じ処理を再実行します。

合格条件は、キャッシュが残っていたから成功した状態ではありません。依存関係の取得先、固定されたリビジョン、アーカイブ結果、失敗ログが追跡できることです。Xcodeを更新した場合も、SSH認証、Package.resolved の扱い、署名、アーカイブを再確認します。

私有パッケージを更新するときは、先にローカルで差分を確認します。リモートMacのビルド開始時に依存バージョンが自動で変わる構成は避けます。リポジトリの移管、鍵のローテーション、ビルドユーザーの変更、依存パッケージの削除も、同じ受け入れ基準で確認します。

構築環境の選び方

自宅のMac、クラウド型のCI、リモートMacは、依存認証の扱いと保守負担が異なります。価格だけでなく、常時起動の必要性、物理Macへのアクセス、鍵を置く範囲で判断します。

選択肢 私有依存の設定自由度 再起動後の確認 向いているケース
手元のMac 高い 手動確認になりやすい 日中の開発と少量の手動アーカイブ
クラウドCI 制約が環境ごとに異なる 実行環境の仕様確認が必要 標準化された短時間ビルド
リモートMac macOSユーザーとSSHを細かく管理できる 実機に近い復旧確認が可能 常駐ビルド、専用ツール、段階的な移行

構成を固定できない場合は、長期契約の前に短期間のリモートMacで、実際の私有リポジトリを使った冷起動解析とアーカイブを試すのが安全です。ProxyMacのリモートMac利用手順を確認し、必要な操作権限と接続方法を先に照合できます。利用期間や料金条件を比較する場合は、日本向けのMacレンタルプランで運用期間に合う選択肢を確認します。

ローカルMacは、長期間にわたる安定した高負荷処理や物理デバイス接続には適しています。一方、専用機の購入は初期費用、保守、設置場所、故障時の交換を開発者側で抱えます。一般的なCIは手軽ですが、独自のSSH設定、常駐プロセス、Xcode固有の検証を細かく管理しにくい場合があります。

私有パッケージの認証が整った後は、短周期の環境で実プロジェクトを冷起動解析し、アーカイブし、再起動後にも再現するかを確認します。無人状態で安定して読み取れることを確認できた段階で、常時稼働の打ち込み環境へ移行するのが適切です。

既存のWindowsやLinux環境だけでiOSの署名・アーカイブまで完結させる方法は、XcodeとmacOSユーザー固有の認証状態を扱えず、SSH鍵、キャッシュ、実行環境の差分も増えます。自前のMacを常時稼働させる方法も、購入費用と保守負担、再起動後の復旧確認を抱えます。短期の検証や常駐ビルド機が必要な場面では、ProxyMacのリモートMacを使って先に実プロジェクトを検証するほうが、導入判断を小さく始められます。

プライベートパッケージの検証環境をProxyMacで整えませんか

ProxyMacなら、Macをリモートで利用できるため、手元の環境に左右されずビルド検証を進められます。
専用のMac環境で依存関係や資格情報を整理し、再現性の高い開発フローを構築できます。