XcodeGenで生成したのに、リモートMacのCIではビルドが通らない。
最短の解決策は、設定ファイルと依存関係の入力を固定し、CIで工程を生成してからXcodeのツールでビルド・テストすることです。生成コマンドの成功ではなく、実際のプロジェクトの再現性を合格条件にします。
複数のAppleプラットフォーム向けtargetを保守し、Xcode設定をレビュー可能にしたい開発者向けです。
個人のMac操作に依存しないビルドとテストを整えたいCI担当者、小規模チームにも役立ちます。
開始前に決める責任範囲と合格条件
XcodeGenはYAMLまたはJSON形式のプロジェクト設定からXcodeプロジェクトを生成し、リモートMacはXcodeのツールチェーンでビルドとテストを実行します。生成とAppleのビルド環境は別の工程です。XcodeGenの用途とコマンドは公式リポジトリの説明、Xcodeに含まれるコマンドラインツールはAppleのリファレンスで確認できます。
導入前に、リポジトリ内のproject.ymlなどの設定ファイル、ソースの配置、依存関係の管理方式、targetとschemeを洗い出します。設定ファイルの名前や構成はプロジェクトごとに異なるため、既存の構成を前提にしてください。
合格条件は「工程ファイルが生成された」だけでは不十分です。クリーンなチェックアウトから同じ手順で生成でき、予定したschemeのビルドと代表的なテストが完了することまでを受け入れ条件にします。
工程ごとの役割
- XcodeGen：リポジトリの設定を読み、Xcodeプロジェクトを生成します。
- 依存関係の導入：プロジェクトで採用している仕組みとロックファイルに従います。
- xcodebuild：生成後のプロジェクトまたはworkspaceを指定し、ビルドやテストを行います。
- CI：これらの順序、入力、実行ログを管理します。
準備段階で入力をリポジトリに固定する
最初に、CIが再現すべき条件をコードレビュー可能な形にします。Xcodeのバージョンはプロジェクト要件とAppleの提供内容を照合して決め、使用するXcodeGenの導入方法とバージョンもチーム内で統一します。ここで特定のバージョンを一律に指定することはできません。
依存関係の取得手順も明記します。CocoaPodsを使うプロジェクトでは、既存のロックファイルを尊重する通常の導入と、依存関係を更新する操作を混同しないでください。CocoaPodsのコマンド説明を確認し、CIで意図しない更新が起こらない手順にします。XcodeGenが扱う依存関係の設定は公式の使用方法も参照してください。
環境変数や署名情報は、設定ファイルやログへ秘密情報を直接書かない設計にします。self-hosted runnerを使う場合、ジョブを実行するホストへコードがアクセスし得る点も運用上のリスクです。GitHubのself-hosted runnerに関するセキュリティ説明を踏まえ、アクセス権と実行対象を確認してください。
生成段階で工程とschemeを検査する
リモートMac上では、リポジトリのルートなど、CIで固定した作業ディレクトリへ移動してからXcodeGenを実行します。たとえば設定ファイルがproject.ymlなら、公式ドキュメントのオプションに従ってそのファイルを指定して生成します。
xcodegen generate --spec project.yml
別ディレクトリに設定ファイルがある場合は、そのパスと出力先を実際のリポジトリ構成に合わせます。まず公式のコマンドと仕様で使っているXcodeGenのオプションを確認してください。
生成後は、終了コードだけでなく、出力された.xcodeprojやworkspace、target、schemeを確認します。想定した構成になっていない場合、設定ファイルのパスやtarget定義、ファイルの配置を調べます。schemeの共有や構成は、Appleのscheme設定資料を参照してください。
設定ファイルの記述ミスがなく生成に成功しても、実際のビルドやテストが成功するとは限りません。生成結果の検査と、Xcodeによるプロジェクトの検証を別々の関門として扱います。
構築段階でxcodebuildを接続する
CIの順序は「チェックアウト、依存関係の導入、XcodeGenで生成、xcodebuildでビルドまたはテスト」とします。CocoaPodsを含む場合は、プロジェクトの実際の依存管理方式に合った導入処理を、生成やビルドの前後どちらに置くべきか確認します。
workspaceを使う構成ならworkspaceを、そうでなければ生成したprojectを指定します。schemeとビルド先も、リポジトリで共有されているものと、CIのMacで利用可能な環境に合わせます。
xcodebuild -project App.xcodeproj -scheme App -showBuildSettings
xcodebuild -project App.xcodeproj -scheme App -destination "$DESTINATION" test
この例のApp.xcodeproj、App、$DESTINATIONは置き換え用です。プロジェクトの実名、共有scheme、利用可能なSimulatorなどに合わせて指定してください。workspaceを使う場合は、Appleのxcodebuildコマンド資料を確認し、-projectではなく該当する指定を使います。自動テストの実行方法はAppleのテスト自動化資料も参照できます。
現場で起きやすい切り分け
設定を変更したあと、生成だけ成功してビルドに失敗するケースでは、失敗段階をログで区別します。XcodeGenのログ、依存関係の導入ログ、xcodebuildのログを分けて保存し、schemeやbuild settingsが意図したものか確認します。ビルド時間だけで失敗原因を判断せず、Appleが案内するビルド時間の確認方法も必要に応じて利用します。
受け入れ段階で再現性とGit方針を確認する
生成されたXcodeプロジェクトをGitに登録するかは、チームの運用で決めます。生成物を登録しない方式は、CIで毎回生成する手順を一貫して適用する必要があります。登録する方式は、設定ファイルと生成物の差分が意図どおりかレビューできる状態が必要です。どちらの方針でも、生成物の差分がいつ、誰の操作で更新されるのかを明文化します。
以下を満たせない場合は、継続運用に進む前に手順を修正してください。
- [ ] クリーンなチェックアウトから設定ファイルを使って工程を生成できる
- [ ] XcodeGenとXcodeのバージョン、依存関係の導入方法をCIログで追跡できる
- [ ] 生成されたprojectまたはworkspace、target、schemeが想定と一致する
- [ ] 実際にCIで使うschemeとビルド先でビルドできる
- [ ] 代表的なテストが完了し、失敗段階をログから判別できる
- [ ] 生成物をGitに登録するかどうかと、差分の扱いがチーム内で決まっている
クリーンな作業環境で再実行したときに生成結果やビルドが変わるなら、まず設定ファイル、依存関係、ツールの差を特定します。XcodeGenの生成成功だけを根拠に、CIへの採用を決めないでください。
よくある判断のFAQ
XcodeGenをリモートMacのCIに組み込む位置
チェックアウトと依存関係の導入を済ませた後、xcodebuildより前にXcodeGenを実行します。生成とビルドを別のログ段階に分けると、失敗した処理を特定しやすくなります。CI担当者は、設定ファイルの場所と生成先をジョブの作業ディレクトリに合わせて固定してください。
project.ymlからの生成確認
設定ファイルのパスを指定して生成し、出力先に想定した工程ができているかを確認します。さらにtargetとschemeも検査します。ファイルが出力されたことだけで合格にせず、後続のビルドとテストまで実行してください。
生成後のiOSビルドとテスト
利用するprojectまたはworkspace、scheme、ビルド先を指定してxcodebuildを実行します。SimulatorやSDKがリモートMacにない場合、指定したビルド先が使えず失敗することがあります。クリーンなチェックアウトで、CIの実際の環境に合わせたテストを行います。
生成物をGitに登録する判断
登録の要否はプロジェクトの運用方針で決めます。登録しない場合はCIで毎回確実に生成し、登録する場合は設定ファイルとの不整合をレビューできるようにします。どちらでも、チームが同じ手順を再実行できることが判断基準です。
リモートMacを使う前に運用上の負担を比較する
手元のMacだけでCIを回す方式は、担当者の端末や利用可能時間に依存し、保守や更新の管理も必要です。LinuxのクラウドサーバーはAppleのXcodeツールチェーンを実行する用途には置き換えられず、Macを購入して専用ノードにする方式は初期投資と継続的な管理が伴います。
一方、リモートMacのレンタルなら、実機購入を保留したままApple向けのビルド環境を用意できます。短期の移行検証や一時的なCI負荷には候補になりますが、長期にわたる常時高負荷運用や物理機器への接続が必須なら、自社所有のMacを含めて比較してください。osxmeshの利用条件を確認する場合は、プランの内容を参照できます。リモート開発環境の利用条件はサポート情報でも確認し、必要な期間と運用要件に合う場合に検討してください。
よくある質問
XcodeGenはリモートMacのCIにどう組み込みますか？
プロジェクト設定ファイルと依存関係の導入手順をリポジトリで管理し、CIの各実行でXcodeGenによる生成を先に行います。その後、対象のプロジェクトまたはワークスペース、scheme、ビルド先を指定してxcodebuildを実行します。生成とビルドを別のログ段階に分けると、失敗箇所を追いやすくなります。
CIでproject.ymlからXcodeプロジェクトを生成するには？
リポジトリのルートや所定の作業ディレクトリで、XcodeGenに設定ファイルの場所を指定して生成します。実行前に作業ディレクトリと出力先を確認し、生成後は想定したプロジェクト、target、schemeが作られたかを調べます。コマンドのオプションは利用するXcodeGenの公式ドキュメントに合わせてください。
XcodeGenの生成後、iOSアプリのビルドとテストはどう確かめますか？
生成コマンドの終了だけで合格とはせず、実際のCIで使うschemeとビルド先を指定してxcodebuildを実行します。依存関係を導入したクリーンなチェックアウトでも同じ手順を試し、代表的なテストまで完了することを確認します。利用可能なSimulatorやSDKに合うビルド先を選んでください。
XcodeGenが作ったXcodeプロジェクトはGitに登録すべきですか？
一律の正解はありません。設定ファイルから工程を再生成する運用なら、生成物を登録せず、CIで毎回生成する方針が候補になります。一方、利用者の手順やリポジトリの運用が生成物を前提にする場合は、差分の確認方法や更新責任を決めてから登録します。チームで同じ判断基準を文書化してください。