CICD Made Easier with Unity CLI

CI/CDパイプラインは、自然発生的に成長していく傾向がある。Unity エディターを開いてビルドを開始するスクリプトとして始まったものが、徐々に多くの責任を担うようになります。例えば、適切なエディター実行ファイルの検索、プラットフォームモジュールのインストール、ライセンスの管理、テスト結果の収集、署名資格情報の処理、そしてジョブ完了後のクリーンアップなどです。

その結果はうまくいくかもしれないが、理解するのは難しく、再現するのはさらに難しい。パイプラインは、設定ファイル内のコードだけでなく、ランナーにインストールおよび設定されているすべてのものにも依存します。

新しいUnity CLIは、 Unityと連携した自動化をより簡単に実現する方法を提供します。これにより、ビルドシステムは、エディタのインストール、テストの実行、ビルドの生成、ライセンスの管理を行うための、一貫した統一コマンドを利用できるようになります。これは、非対話型インストール、構造化出力、消去終了コードなど、端末および自動化ワークフロー向けに設計されています。（ unity.com ）

これは、CIプロバイダーやプロジェクトのビルドコードを置き換えるものではありません。その代わりに、両者を接続するために必要な特注機器を削減できる。

簡素化：パイプラインが何をする必要があるかを表現する

Unity CLIが登場する以前は、ほとんどのCIパイプラインはUnity エディターの実行ファイルを直接起動していました。簡略化されたテストコマンドは次のように外観ます。

UNITY_PATH="/opt/unity/editors/6000.2.10f1/Editor/Unity"

"$UNITY_PATH" \
  -batchmode \
  -nographics \
  -quit \
  -projectPath "$PWD" \
  -runTests \
  -testPlatform EditMode \
  -testResults ./results/editmode.xml \
  -logFile -

このやり方自体に本質的な問題はない。課題は、その周囲で起こるあらゆる出来事にある。

パイプラインは、エディタがどこにインストールされているかを知っている必要があります。別のスクリプトまたはマシン画像で、要求されたバージョンが存在することを確認する必要があります。ランナーには、適切なプラットフォームモジュール、ライセンス設定、および環境変数も必要です。Windows、macOS、 Linuxの各ランナーは、それぞれ若干異なるパスとセットアップロジックを必要とする場合があります。

このコマンドはテストを実行しますが、その周辺のパイプラインにはUnity固有の実装の詳細が数多く含まれています。

Unity CLI では、同じステップを意図という観点から表現できます。

unity test . \
  --mode EditMode \
  --output ./results/editmode.xml \
  --allow-install

これは、パイプラインに対してプロジェクトの編集モードテストを実行し、結果をNUnit XMLファイルに書き込むように指示します。--allow-install オプションを使用すると、CLI はプロジェクトに必要なUnity のバージョンを読み取り、必要に応じてインストールできます。ビルドマシンではなく、プロジェクト自体が、どのエディタバージョンを使用するかを決定する真の情報ソースとなる。

ビルドは同じパターンに従います。以前は、ビルドにエディタが直接呼び出されることがありました。

"$UNITY_PATH" \
  -batchmode \
  -nographics \
  -quit \
  -projectPath "$PWD" \
  -buildTarget Android \
  -executeMethod Builder.PerformBuild \
  -logFile -

Unity CLI を使用すると、ビルドがより読みやすくなります。

unity build . \
  --target Android \
  --execute-method Builder.PerformBuild \
  --output-path ./out/app.aab \
  --allow-install

既存のBuilder.PerformBuildメソッドは、シーンの選択、ビルド設定の適用、スクリプトシンボルの設定、バージョン情報の割り当て、スタジオ固有の検証の実行など、プロジェクト固有のビルド処理を引き続き担当できます。

CLI は、そのメソッドに関する自動化を簡素化します。CI設定では、エディタの場所や起動方法についてそれほど多くの情報を知る必要がなくなりました。

まとめると、CIジョブは、短いコマンドシーケンスで、新規ランナーからテスト済みのビルドへと移行できます。

# Install Unity CLI on macOS and Linux
brew install --cask unity-cli

# Install Unity CLI on Windows
winget install Unity.CLI

# Install a specific Editor and its Android module
unity install 6000.2.10f1 \
  -m android \
  --accept-eula \
  --yes

# Run EditMode tests
unity test . \
  --mode EditMode \
  --output ./results/editmode.xml

# Build an Android App Bundle
unity build . \
  --target Android \
  --execute-method Builder.PerformBuild \
  --output-path ./out/app.aab

あるいは、テストコマンドとビルドコマンドで--allow-install を使用することで、プロジェクトがバージョンを判別する必要がある場合に、別途エディターのインストールステップを省略できます。

重要な変更点は、単にコマンドが短くなったということだけではない。それは、その仕事が何を達成しようとしているのかを伝えるということだ。パイプラインを読み解くことで、エディターパスやバッチモードフラグの羅列をデコードことなく、 Unityがどこにインストールされているか、テストがどこで実行されるか、ビルドがどこで生成されるかを把握できます。

生産パイプラインには、他にも様々な要素が存在するだろう。CIプロバイダーは引き続きリポジトリをチェックアウトし、シークレットを挿入し、キャッシュを復元し、テストレポートを公開し、成果物をアップロードします。Unity CLIは、これらのシステムに対し、Unity固有の手順をよりシンプルかつ一貫性のある方法で処理することを可能にします。

改善：パイプラインからリスクを取り除く

パイプラインがシンプルになれば、読みやすく保守しやすくなるが、簡素化はメリットのほんの一部に過ぎない。Unityのセットアップと実行を一貫したCLIの背後に移行することで、チームはCI/CDにおけるいくつかの一般的なリスク要因にも対処できます。

ランナーのエディターバージョンが間違っています

事前設定済みのマシンに依存するパイプラインは、そのマシンが正しく設定された状態を維持することにも依存する。ユーザーはエディタを更新、モジュールを削除したり、インストールパスを変更したりできます。交換用ランナーは、CIダッシュボード上では外観が同じでも、内部構造が微妙に異なる場合がある。

そうした違いを見抜くのは難しい場合がある。パイプライン設定もプロジェクトも変更されていないのに、マシンが変更されたためにビルドが突然異なっています。

Unity CLIを使用すると、ジョブが必要とするエディターとモジュールを宣言できます。

unity install 6000.2.10f1 \
  -m android \
  --accept-eula \
  --yes

または、ジョブで--allow-install オプションを使用し、プロジェクトのProjectVersion.txtファイルに必要なエディタを判断させることもできます。

これにより、ビルド環境はランナーの非公式なプロパティではなく、パイプラインの一部となる。Unityをアップグレードするブランチは、ビルドエンジニアがすべてのランナー画像を更新のを待つのではなく、その要件をCIに取り込むことができます。

また、これにより、一時的なランナーもより実用的になる。新しいランナーは、綿密に準備されたUnityビルドマシンとして最初から稼働する必要はありません。ジョブの一環として、CLIをインストールし、必要な環境をプロビジョニングすることができます。

CIは開発者のマシンとは異なる動作をする。

プロバイダー固有のスクリプトは、ローカル開発とCI（継続的インテグレーション）の間にギャップを生じさせる可能性があります。ジョブが失敗した場合、開発者はビルドランナー上でしか意味をなさないパスやオプションを含む、大きなエディターコマンドを受け取る可能性があります。

その不具合をローカル環境で再現するには、CIスクリプトを開発者のマシンで動作する形式に変換する必要があります。

Unity CLIでは、同じコマンドを両方の場所で使用できるため、そのギャップが縮まります。

unity test . \
  --mode EditMode \
  --output ./results/editmode.xml \
  --allow-install

CI環境には、シークレット、ライセンス、アーティファクトの公開など、依然として違いがありますが、Unity向けのエントリーは変わりません。

そうすることで、失敗した仕事の調査が容易になる。開発者は、テストコマンドまたはビルドコマンドをコピーし、プロジェクトディレクトリから実行することで、ランナーのエディター呼び出しを最初に再構築することなく、問題の再現を開始できます。

カスタムラッパースクリプトはそれ自体がインフラストラクチャとなる

多くのスタジオでは、 Unityのインストール場所を特定し、ビルドターゲットをエディター引数に変換し、ログをストリーム、終了コードを解釈し、テスト結果を適切なディレクトリに移動するためのスクリプトを使用しています。

これらのスクリプトは通常、正当な理由に基づいて作成されます。しかし、時が経つにつれて、それらはテストとメンテナンスが必要なインフラストラクチャの新たなレイヤーとなる。また、プロジェクト間で重複したり、CIプロバイダーごとに書き換えられたりすることもあります。

Unity CLIは、一般的な操作のための単一のエントリーポイントを提供します。

unity install
unity test
unity build

これは、すべてのプロジェクトが全く同じになるという意味ではありません。スタジオは、プロジェクト固有のロジックを本来あるべき場所に留めておくことができるし、そうすべきである。AC#のビルドメソッドは、ゲームの構築方法を引き続き定義できる一方、CLIは自動化のためにそれを呼び出す標準的な方法を提供する。

境界がより明確になる。プロジェクトはビルドを所有し、CIジョブはそのビルドがいつ、どこで実行されるかを所有する。

故障の診断は困難である

Unityジョブが失敗すると、大量の出力が生成される可能性があります。テスト結果がエディタのログにのみ存在する場合、開発者は実際の障害箇所を特定するために、そのログをダウンロードして検索必要があるかもしれません。一時的な実行ファイルの場合、有用な診断ファイルもジョブが終了すると同時に消えてしまう可能性があります。

Unity TestはNUnit XMLレポートを直接書き出すことができます。

unity test . \
  --mode EditMode \
  --output ./results/editmode.xml

CI プロバイダーは、そのレポートを取り込んでディスプレイできます。また、定義済みの終了コードを使用し、CLI 固有のログを保持することで、自動化がテストの失敗を他の問題と区別するのに役立ちます。( docs.unity.com )

その結果は、単にログ記録が増えるというだけではない。開発者が既に外観場所、つまりジョブログ、テストレポート、ビルド成果物に、より有用な出力が表示される。

パイプラインは、各実行からのキー出力を保持することができます。

results/editmode.xml
results/playmode.xml
out/app.aab
Editor.log
cli-log.json

これにより、パイプラインをスケールに運用することが容易になります。開発者は日常的なテストの失敗を自ら調査できる一方、ビルドエンジニアはインフラストラクチャの問題を診断するために必要な詳細なログを保持できる。

資格や免許は仕事が終わるよりも長く有効である

ビルドランナーは、サービスアカウントの認証情報、 Androidキーストア、署名パスワード、オフラインライセンスファイルなど、機密性の高いマテリアルへのアクセスを必要とすることがよくあります。長期間稼働するマシンでは、パイプラインが慎重なクリーンアップを実行しない限り、ビルド間でこれらのファイルや環境変更が保持される可能性があります。

CLIを優先するワークフローは、シークレットストアや一時的なランナーと自然に相性が良い。認証情報は環境変数として注入され、ジョブで使用され、ランナーが削除されると破棄されます。

ファイルの署名も同様の手順で行うことができます。例えば、 Androidのキーストアはbase64エンコードされたCIシークレットとして保存され、ビルドのみデコードされ、ティアダウン時に削除される。

echo "$ANDROID_KEYSTORE_BASE64" \
  | base64 --decode > ./android.keystore

unity build . \
  --target Android \
  --execute-method Builder.PerformBuild \
  --output-path ./out/app.aab

rm -f ./android.keystore

ライセンス取得は、職務ライフサイクルの明確な一部となる場合もある。ランナーはUnityの処理を実行する前にライセンスを有効化し、処理が終了するとライセンスを返却します。

unity license activate --floating

# Run tests and produce builds

unity license return

Unity CLIは、フローティングライセンスやオフラインライセンスなどのオプションを含む、アクティベーションおよび返却ワークフローをサポートしています。（ docs.unity.com ）

一時的なランナーの場合、returnコマンドは無条件のティアダウンステップに配置することで、テストやビルドが失敗した場合でも実行されるようにする必要があります。これにより、失敗したジョブによって座席がチェックアウトされたままになり、後続のビルドに影響を与えることを防ぎます。

このパイプラインは1つのCIプロバイダーに紐づいている。

どのCIプラットフォームにも独自の設定言語がありますが、プロバイダーが変更されたとしても、ジョブ内のUnityの処理内容を変更する必要はありません。

パイプラインでは、 GitHub Actions、GitLab CI、Jenkins、Buildkite、TeamCity、または社内オーケストレーションシステムなどが使用される場合があります。これらのシステムは、スケジューリング、シークレット、キャッシュ、およびアーティファクトの管理を継続します。Unityプロジェクトのテストとビルドコマンドは、一貫性を保つことができます。

unity test . --mode EditMode --output ./results/editmode.xml
unity build . --target Android --output-path ./out/app.aab

これによりCI移行が容易になるわけではありませんが、Unity固有の自動化コードを書き直す必要のある量を減らすことができます。プロバイダーがコマンドを実行し、 Unity CLI がUnityとのインタラクションを処理します。

その一貫性は、プロジェクト全体を通して役立つ。ビルドチームは、すべてのプロジェクトが同じ内部ビルド実装を共有ことを要求することなく、共通のパイプラインパターンを確立できる。

結局のところ、 Unity CLIは優れたCI/CDパイプラインが達成すべきことを変えるものではありません。パイプラインは、環境のプロビジョニング、テストの実行、ビルドの生成、認証情報の保護、有用な出力の公開、およびクリーンアップ必要があります。

変わるのは、それらの手順をUnityで機能させるためにどれだけのカスタム機器が必要になるかという点です。

ハードコードされたエディターパス、事前設定されたランナー、そしてますます複雑化するラッパースクリプトに頼る代わりに、チームは少数のコマンドを使用して意図を記述できます。その結果、読みやすく、再現しやすく、特定のビルドマシンのステートに依存しないパイプラインが実現する。

Unity CLI を使用すると、クリーンなランナーからテスト済みのビルドまでのプロセスを簡素化し、その過程におけるすべての信頼性を向上させることができます。