GitHub ActionsでUnityを高速化する
最終更新
GitHub Actions で Unity を高速化するには、Library フォルダを actions/cache でキャッシュし、ビルドターゲットごとに 1 つのキャッシュを保持し、Git LFS ファイルは必要な場合のみ取得し、GameCI の unity-builder で各プラットフォームを個別のジョブとして実行します。Library フォルダにはインポート済みのアセットが格納されており、これを最初から再構築することが Unity CI で最も時間のかかる工程になることがよくあります。
このガイドでは、オープンソースの Unity CI ツールキットである GameCI を使用します。全般的なアプローチについては、GitHub Actions を高速化する方法をご覧ください。
Unity CI が遅くなる理由
クリーンな Unity ビルドでは、負荷の大きい処理が 4 つ行われます。エディタの Docker イメージ(数 GB)を取得し、ライセンスを有効化し、すべてのアセットを Library にインポートし、スクリプトをコンパイルしてプレイヤーをビルドします。テクスチャ、モデル、オーディンファイルが多いプロジェクトでは、インポートが最も大きな要因です。次に大きいのがエディタイメージの取得です。どちらもコンパイラを速くしても解決せず、キャッシュの活用とジョブあたりの処理量の削減によって改善されます。
Library キャッシュ
GameCIのビルダーのドキュメントには、Libraryをactions/cacheでキャッシュするワークフローが示されています。キーにはターゲットプラットフォームとプロジェクト内容のハッシュが含まれ、プラットフォーム用のrestore-keysプレフィックスも指定されています。
- uses: actions/cache@v6
with:
path: Library
key: Library-${{ matrix.targetPlatform }}-${{ hashFiles('Assets/**', 'Packages/**', 'ProjectSettings/**') }}
restore-keys: |
Library-${{ matrix.targetPlatform }}-
この設計の要点は次の 3 つです。
- キーにプラットフォームを含める。各ビルドターゲット(Android、iOS、WebGL、StandaloneLinux64)はアセットのインポート方法が異なります。共有キャッシュでは、ターゲットを切り替えるたびにキャッシュが上書きされてしまいます。
- リストアキーが実質的な役割を担う。キャッシュエントリは変更不可のため、アセットが 1 つでも変わると完全一致はほとんど起きません。プレフィックス一致によって直近の過去の
Libraryが復元され、Unity は変更された部分だけを再インポートします。 - ハッシュのコスト。
hashFilesはAssets/**内のすべてのファイルを読み込みます。アセットが数ギガバイトに及ぶ大規模なプロジェクトでは、ハッシュの計算だけでも時間がかかります。より軽量なキーでは、保存時にはProjectSettings/ProjectVersion.txtとPackages/packages-lock.jsonに加えてgithub.shaを使用し、リストアキーにはプレフィックスを使用します。
Library のキャッシュは大きく、プラットフォームごとに 1 GB 以上になることも多いものです。GitHub はリポジトリごとのキャッシュ総容量に上限を設けているため、GitHub Actions のキャッシュ制限を確認してください。3 つのプラットフォームと PR の多い運用では、有用なエントリがすぐに削除されてしまいます。キャッシュの保存は main に限定して actions/cache/save で行い、どこでも actions/cache/restore で復元するようにしてください。
ライセンスの有効化
GameCI では、リポジトリのシークレットを使う 2 つの方法が案内されています。
- 個人ライセンス。GameCI のアクティベーションワークフローまたはローカルで一度有効化し、
UNITY_LICENSE(.ulfファイルの内容)、UNITY_EMAIL、UNITY_PASSWORDを保存します。 - Professional(Plus または Pro)。
UNITY_SERIAL、UNITY_EMAIL、UNITY_PASSWORDを保存します。ジョブの実行中は Pro のシートが 1 つ使われます。GameCI のビルダーとテストランナーにはライセンス返却のステップが含まれています。 - ライセンスサーバー。フローティングライセンスサーバーを運用している場合は、
unityLicensingServer入力でビルドの接続先を指定します。
GameCI は、お客様の認証情報を取得も保存もしないと説明しています。Unity のライセンス規約は変更されることがあるため、チームで個人ライセンスに頼る前に、CI での利用に関する Unity の最新の規約を確認してください。Pro のシリアルで並列ジョブを実行する場合は、それぞれにシートが必要になる可能性があります。
Git LFS とチェックアウト
Unity プロジェクトでは、テクスチャ、モデル、オーディオを Git LFS で管理することがよくあります。GameCI のサンプルでは lfs: true を指定してチェックアウトしています。指定しないとファイルはポインタのままになり、ビルドが失敗します。取得は慎重に行ってください。
- uses: actions/checkout@v7
with:
lfs: true
actions/checkout では、lfs の既定値は false、fetch-depth の既定値は 1 で、チェックアウトは浅いクローンになります。GameCI のサンプルでは、完全な履歴のために fetch-depth: 0 を指定していますが、これは Git 履歴を読み取るバージョン管理(タグからバージョンを算出するなど)を行う場合にのみ必要です。それ以外は既定値のままにしてください。浅いチェックアウトの方が高速です。LFS のダウンロードは Actions とは別の枠である LFS の帯域幅クォータを消費します。帯域幅や時間が問題になる場合は、.lfs-assets-id のハッシュをキーにして .git/lfs をキャッシュするか、ローカルの Git キャッシュを備えたサービスを利用してください。
プラットフォームごとに 1 ジョブ
マトリックスを使うと、ターゲットごとに個別のジョブ、キャッシュ、マシンが割り当てられます。
name: build
on:
push:
branches: [main]
pull_request:
jobs:
build:
name: Build ${{ matrix.targetPlatform }}
runs-on: ubuntu-latest
timeout-minutes: 60
strategy:
fail-fast: false
matrix:
targetPlatform:
- StandaloneLinux64
- WebGL
- Android
steps:
- uses: actions/checkout@v7
with:
lfs: true
- uses: actions/cache@v6
with:
path: Library
key: Library-${{ matrix.targetPlatform }}-${{ hashFiles('Assets/**', 'Packages/**', 'ProjectSettings/**') }}
restore-keys: |
Library-${{ matrix.targetPlatform }}-
- uses: game-ci/unity-builder@v4
env:
UNITY_LICENSE: ${{ secrets.UNITY_LICENSE }}
UNITY_EMAIL: ${{ secrets.UNITY_EMAIL }}
UNITY_PASSWORD: ${{ secrets.UNITY_PASSWORD }}
with:
targetPlatform: ${{ matrix.targetPlatform }}
- uses: actions/upload-artifact@v7
with:
name: Build-${{ matrix.targetPlatform }}
path: build/${{ matrix.targetPlatform }}
ビルダーの unityVersion 入力の既定値は auto で、ProjectSettings/ProjectVersion.txt を読み取ります。GameCI のドキュメントではこの例で game-ci/unity-builder@v4 を使用し、他の箇所では v6 に言及しています。コピーする前に、アクションのリリースページで最新のタグを確認してください。timeout-minutes は重要です。ライセンスのステップが停止すると、1 時間分の実行時間を無駄にしかねません。
プラットフォームに関する注意点として、Linux ランナーでは Standalone Linux、WebGL、Android をビルドできます。Windows および macOS のターゲットには、それぞれ専用のランナーが必要です。iOS には macOS が必要で、分単位の料金が高くなります。詳しくはiOS CI 向けの macOS ランナーをご覧ください。
テスト
GameCI のテストランナーを使い、すべての PR で EditMode テスト(高速でプレイヤーは不要)を実行し、PlayMode テストは頻度を下げて実行します。テストランナーも Library キャッシュを利用するため、同じキャッシュステップを設定して、テストで毎回新たなインポートが発生しないようにしてください。
CPU コア数を増やす効果
アセットのインポートとスクリプトのコンパイルは複数のコアを使用し、Unity の IL2CPP ビルドは負荷が高いため、マシンが大きいほど効果があります。Library は大きいため、ディスクの速度と RAM も重要です。当社のベンチマークには Unity の項目がないため、高速化の度合いについては示しません。検証される場合は、エディタイメージが大きいことに留意してください。マシンが Docker キャッシュを保持していない限り、新しい VM は毎回イメージを取得します。compiler.dev のランナーには Docker レイヤーキャッシュが用意されており、変更は 1 行で済みます。runs-on: [self-hosted, Linux, compiler-ci]。料金と比較をご覧のうえ、イメージ取得の仕組みについてはCI における Docker レイヤーキャッシュをお読みください。また、ゲームの QA テストに関するページもご覧ください。
よくある質問
GitHub Actions で Unity に対して何をキャッシュすればよいですか?
Library フォルダです。キーにはターゲットプラットフォームを含め、リストアキーにはプラットフォームのプレフィックスを指定します。プラットフォーム間で 1 つのキャッシュを共有しないでください。
Unity CI に Git LFS は必要ですか?
リポジトリでアセットをLFSに保存している場合は、はい。チェックアウト時にlfs: trueを設定してください。設定しないと、ビルドがアセットの代わりにポインタファイルを参照してしまいます。
CIで無料のUnityライセンスを使用できますか?
GameCIは、UNITY_LICENSE、UNITY_EMAIL、UNITY_PASSWORDのシークレットを通じて個人ライセンスをサポートしています。ご利用の用途については、Unityの利用規約をご確認ください。
Unityのキャッシュがヒットしないのはなぜですか?
エントリが不変であり、すべてのアセットをハッシュ化するキーを使用している場合、完全一致のヒットはまれです。restore-keysのプレフィックスを利用し、そのプレフィックスがプラットフォームと一致していることを確認してください。
関連記事
- GitHub ActionsでTypeScriptモノレポを高速化するGitHub Actionsで TypeScriptモノレポの型チェックとリンターを高速化する: インクリメンタルtsc、プロジェクト参照、Lintキャッシュ、並列ジョブ
- GitHub ActionsでモノレポのPlaywrightを高速化するGitHub Actions で Node モノレポの Playwright E2E テストを高速化: アプリを一度だけビルドし、Web アプリに変更がないときは E2E をスキップし、シャーディングとレポートのマージを行います。
- READMEにCIの速度バッジを追加するREADME のバッジで CI の速さを表示しましょう。リポジトリの GitHub Actions 実行時間の中央値が自動で更新されます。公開リポジトリは無料です。
- GitHub Actionsで.NETを高速化するGitHub Actions で .NET のビルドを高速化する: setup-dotnet による NuGet キャッシュ、--no-restore、--no-build、並列の dotnet test、SQL Server サービス。