結論と概要
Github Actions を使用してGithubに git push
が行われたら自動的にUnityビルドを行いその成果物をダウンロードできる仕組みを構築することができたので紹介します。
実際に自動的にUnityビルドを行っているプロジェクトは以下のプロジェクトになります。
こちらのプロジェクトに記載されている内容をコピー、改変して利用してください。
実際に Unityビルドを自動的に行なっている場所(実行している処理のレシピ)は以下のようになります。
name: execute-unity-builds
on:
push:
branches:
- unity-deploy
jobs:
build:
name: ${{ matrix.targetPlatform }}
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
unity-editor-version: [2020.3.26f1]
unity-license-version: [2020.x]
node-version: [14.x]
root-project-path: [Unity]
targetPlatform:
- StandaloneOSX # Build a macOS standalone (Intel 64-bit).
- StandaloneWindows # Build a Windows standalone.
- StandaloneWindows64 # Build a Windows 64-bit standalone.
- StandaloneLinux64 # Build a Linux 64-bit standalone.
- iOS # Build an iOS player.
- Android # Build an Android .apk standalone app.
- WebGL # WebGL.
steps:
- name: Set up Node.js ${{ matrix.node-version }}
uses: actions/setup-node@v3
with:
node-version: ${{ matrix.node-version }}
# Checkout
- name: Checkout
uses: actions/checkout@v2
with:
fetch-depth: 0
# Cache
- uses: actions/cache@v3
id: cache-unity-library
with:
key: ${{ runner.os }}-Unity-Library-${{ matrix.targetPlatform }}
path: |
${{ matrix.root-project-path }}/Library
restore-keys: |
${{ runner.os }}-Unity-Library-
# Cache
- uses: actions/cache@v3
id: cache-unity-license
with:
key: ${{ runner.os }}-Unity-License-${{ matrix.unity-license-version }}
path: |
${{ matrix.root-project-path }}/Unity_v${{ matrix.unity-license-version }}.ulf
${{ matrix.root-project-path }}/Unity_v${{ matrix.unity-editor-version }}.alf
# Request Unity Activation File
- name: Request manual activation file
id: getManualLicenseFile
uses: game-ci/unity-request-activation-file@v2
with:
unityVersion: ${{ matrix.unity-editor-version }}
# Activate from alf File
- name: Install node package, `unity-activate`
run: npm install -g unity-activate
- name: Activate The License
id: activateLicense
run: unity-activate -u "${{ secrets.UNITY_EMAIL }}" -p "${{ secrets.UNITY_PASSWORD }}" -k "${{ secrets.UNITY_AUTHENTICATOR_KEY }}" -o ${{ matrix.root-project-path }}/ "${{ steps.getManualLicenseFile.outputs.filePath }}"
- name: Read ulf
id: ulfRead
uses: juliangruber/read-file-action@v1
with:
path: ${{ matrix.root-project-path }}/Unity_v${{ matrix.unity-license-version }}.ulf
# Build
- name: Build
uses: game-ci/unity-builder@v2
env:
UNITY_LICENSE: ${{ steps.ulfRead.outputs.content }}
with:
targetPlatform: ${{ matrix.targetPlatform }}
projectPath: ${{ matrix.root-project-path }}
allowDirtyBuild: true
# Upload Build
- name: Upload Build
uses: actions/upload-artifact@v3
with:
name: Build-Results
path: build/
なお
on:
push:
branches:
- unity-deploy
とあるように unity-deploy
ブランチにgit push
されたタイミングで自動的にUnityのビルドが実行されるようになっています。
実際にUnityビルドを行っているUnityプロジェクトは Unity/
以下になります。
この Unity/
以下のプロジェクトのパスは共通で使用するので以下のように設定しています
strategy:
matrix:
root-project-path: [Unity]
Unityビルドが完了した成果物は以下にそれぞれ公開されているのでこちらからダウンロードすることができます。
また、github-actions-examples のプロジェクトではUnityビルドの他にもWebサイト
、Android
の自動ビルドについても行なっています。それぞれの自動ビルドの内容についてはこちらにて解説していますので、そちらを参照してください。
Github Actionsとは
通称 CI(継続的インテグレーション: continuous integration) / CD(継続的デリバリー: Continuous Delivery) が実行できるGithubの機能です。
詳しくはこちらを参照してください。
CI/CD実行環境: つまり開発していく中で繰り返し行われる作業を特定のイベントをトリガーにして(今回の場合は git push
つまりソースコードなどがアップロードされたタイミングで)自動的に記述された処理を実行してくれる環境をCI/CD環境と言います。
成果物がダウンロードできるまでの処理の様子
今回、Unityビルドが完了するまでに行われている処理の流れについて、その様子を以下に図示します。
※ 上記の中に登場する各種ファイルについて補足します
- alfファイル: Unityのライセンス要求ファイル。Unityのライセンスファイルの取得を要求するライセンスファイル
- ulfファイル: Unity のライセンスファイル。このファイルによってUnityのライセンスを管理しています。
補足
上記のUnityの ulfファイル(ライセンスファイル)の取得 を毎回行う必要はないのでキャッシュが使えるのなら一度ダウンロードしたulfファイルをキャッシュに保存して使いまわせるようにした方がいいです。(一応キャッシュを行っている箇所を以下に記述しますが、詳細な解説などは省略します)
steps:
# Cache
- uses: actions/cache@v3
id: cache-unity-license
with:
key: ${{ runner.os }}-Unity-License-${{ matrix.unity-license-version }}
path: |
${{ matrix.root-project-path }}/Unity_v${{ matrix.unity-license-version }}.ulf
${{ matrix.root-project-path }}/Unity_v${{ matrix.unity-editor-version }}.alf
参考
使用しているツールについて
ツール一覧
- unity-request-activation-file: unityのalfファイルをダウンロードするために使用
- unity-activate: ダウンロードしたalfファイルを使ってulf(ライセンスファイル)のダウンロードまで一気にやるために使用
- read-file-action: ダウンロードしたulfファイルを読み込むために使用
- unity-builder: Unityビルドを行うために使用
それぞれのツールの使用方法
Unityビルドを自動的に行なっている場所(実行している処理のレシピ)と使用しているツールの解説していきます。
unity-request-activation-file
steps:
- name: Request manual activation file
id: getManualLicenseFile
uses: game-ci/unity-request-activation-file@v2
with:
unityVersion: ${{ matrix.unity-editor-version }}
${{ matrix.unity-editor-version }}
はビルドするために使用しているUnityのバージョンについて記述しています。ここでは後述する共通で使用する変数として事前に設定している値である 2020.3.26f1
をUnityビルドを行うUnityバージョンとして指定しています。
strategy:
matrix:
unity-editor-version: [2020.3.26f1]
↑のように共通で使用する変数として設定しています。この値はビルドしたいUnityのバージョンによってそれぞれ値を変更して利用してください
unity-activate
alfファイルをから ulfファイル(ライセンスファイル)を取得する方法は本来は手動で行います。
本来は手動で行っているものをPuppeteerを使用して自動的に実行されるようにしています。
今回使用しているツールである unity-activate は Unityの.alfファイルから自動で.ulfをダウンロードしたい! の記事にて作られたプロジェクトをインスパイアして作られたものになります。
unity-activate は npm packgae であるので使用するためには事前にNPMを使用できる環境を以下のように整える必要があります。
steps:
- name: Set up Node.js ${{ matrix.node-version }}
uses: actions/setup-node@v3
with:
node-version: ${{ matrix.node-version }}
- name: Install node package, `unity-activate`
run: npm install -g unity-activate
${{ matrix.node-version }}
では Node.js のバージョンを指定しています。ここでは 14.x
(14系)を指定しています。
strategy:
matrix:
node-version: [14.x]
unity-activate を使用する際には基本的には unity-activate [alfファイルのパス]
を指定して実行すればいいいのですが、途中でUnityへのログインが必要になるのでそれぞれ実行に必要な引数を指定して実行する必要があります。
-u "[Unityアカウントにログインするためのメールアドレス]"
-p "[Unityアカウントにログインするためのパスワード]"
-k "[二段階認証鍵]"
-o "[ulfファイルの出力先]"
実行に必要な引数を指定して実行している様子が以下のようになります
steps:
- name: Activate The License
id: activateLicense
run: unity-activate -u "${{ secrets.UNITY_EMAIL }}" -p "${{ secrets.UNITY_PASSWORD }}" -k "${{ secrets.UNITY_AUTHENTICATOR_KEY }}" -o ${{ matrix.root-project-path }}/ "${{ steps.getManualLicenseFile.outputs.filePath }}"
${{ secrets.UNITY_EMAIL }}
のメールアドレス、${{ secrets.UNITY_PASSWORD }}
のパスワード、${{ secrets.UNITY_AUTHENTICATOR_KEY }}
の2段階認証鍵はいずれも秘匿にすべき情報なので機密情報として登録しています。2段階認証鍵については後述します。秘匿情報を設定する方法いついては以下を参照してください。
${{ matrix.root-project-path }}
は上記で設定したUnityプロジェクトのパスの値になります。
${{ steps.getManualLicenseFile.outputs.filePath }}
は unity-request-activation-file にてダウンロードしたalfファイルのファイルパスを指定しています。${{ steps.getManualLicenseFile.outputs.filePath }}
は以下のルールにそった値の変数が代入されるように指定しています。
-
${{ }}
で囲まれたものの中に変数を代入 -
${{ }}
の中の変数はsteps.[id名].outputs.filePath
のような形式 -
steps.
はGitHub Actionsのワークフロー構文の中の jobs..steps に相当するもの -
[id名]
は上記 unity-request-activation-file のid: getManualLicenseFile
の部分の値 -
.output.filePath
を指定することでダウンロードしてきたファイルのパスの結果を参照できます
read-file-action
steps:
- name: Read ulf
id: ulfRead
uses: juliangruber/read-file-action@v1
with:
path: ${{ matrix.root-project-path }}/Unity_v${{ matrix.unity-license-version }}.ulf
ulfファイル(Unity のライセンスファイル)の中身はテキストファイルなので、後述する unity-builder にてUnityビルドを行うためにはulfファイルの中身を読み込む必要があります。ここではそのテキストファイルの中身を読みこんでいます。このようにファイルの値を読み込んで以降の処理に値を参照させるために使用しているものが read-file-action になります。
${{ matrix.root-project-path }}
は上記で設定したUnityプロジェクトのパスの値になります。
Unity_v${{ matrix.unity-license-version }}.ulf
はダウンロードしてきたulfファイルのファイル名になります。ulfファイルはそれぞれUnityのバージョンに対応したライセンスのファイル名となりここではその値を ${{ matrix.unity-license-version }}
に指定しています。ここではUnityの2020系
のUnityバージョンを使ってビルドしていますので、ライセンスファイル名として 2020.x
という名前になります。
strategy:
matrix:
unity-license-version: [2020.x]
unity-builder
steps:
- name: Build
uses: game-ci/unity-builder@v2
env:
UNITY_LICENSE: ${{ steps.ulfRead.outputs.content }}
with:
targetPlatform: ${{ matrix.targetPlatform }}
projectPath: ${{ matrix.root-project-path }}
allowDirtyBuild: true
UNITY_LICENSE: ${{ steps.ulfRead.outputs.content }}
ではulfファイル(ライセンスファイル)の中身の値を代入しています。ulfファイル(ライセンスファイル)の読み込みは read-file-action にて行った処理の結果を取得しています。
これは unity-builder でUnityビルドを行うためには必要な情報となります。
${{ steps.ulfRead.outputs.content }}
は以下のルールにそった値の変数が代入されるように指定しています。
-
${{ }}
で囲まれたものの中に変数を代入 -
${{ }}
の中の変数はsteps.[id名].outputs.content
のような形式 -
steps.
はGitHub Actionsのワークフロー構文の中の jobs..steps に相当するもの -
[id名]
は上記 read-file-action のid: ulfRead
の部分の値 -
.output.content
を指定することでファイルを読み込んだ結果を参照できます
targetPlatform: ${{ matrix.targetPlatform }}
ではビルド対象のプラットフォームを指定しています。ここでは StandaloneOSX
, StandaloneWindows
, StandaloneWindows64
, StandaloneLinux64
, iOS
, Android
, WebGL
の環境をそれぞれビルド対象として指定して行っています。
strategy:
matrix:
targetPlatform:
- StandaloneOSX # Build a macOS standalone (Intel 64-bit).
- StandaloneWindows # Build a Windows standalone.
- StandaloneWindows64 # Build a Windows 64-bit standalone.
- StandaloneLinux64 # Build a Linux 64-bit standalone.
- iOS # Build an iOS player.
- Android # Build an Android .apk standalone app.
- WebGL # WebGL.
その他のビルド可能なプラットフォームの対応状況については以下の通りです。unity-actions#build
Target Platform | Done | Status |
---|---|---|
WebGL | ✔ | |
Windows Mono | ✔ | |
Linux Mono | ✔ | |
macOS Mono | ✔ | |
Windows IL2CPP | ✔ | |
Linux IL2CPP | ✔ | |
macOS IL2CPP | ✔ | |
Android | ✔ | |
iOS | ✔ | |
Universal Windows Platform | ✔ | |
AppleTV | ✔ | |
Windows Dedicated Server | ❌ | In progress |
Linux Dedicated Server | ❌ | In progress |
macOS Dedicated Server | ❌ | In progress |
Lumin | ❌ | In progress |
Xbox | ❌ | Requires license |
Playstation | ❌ | Requires license |
Switch | ❌ | Requires license |
projectPath: ${{ matrix.root-project-path }}
は上記で設定したUnityプロジェクトのパスの値になります。
allowDirtyBuild: true
ではダーティビルドを許可する設定です。(設定の詳細は不明ですがこれを有効にしないとなぜかエラーが出ることがあるので設定しています)
その他導入、実装までの留意事項やTips
Unityアカウントの2段階認証について
ulfファイル(Unityライセンスファイル)のダウンロードを行なっている部分が以下の部分になります)
steps:
- name: Activate The License
id: activateLicense
run: unity-activate -u "${{ secrets.UNITY_EMAIL }}" -p "${{ secrets.UNITY_PASSWORD }}" -k "${{ secrets.UNITY_AUTHENTICATOR_KEY }}" -o ${{ matrix.root-project-path }}/ "${{ steps.getManualLicenseFile.outputs.filePath }}"
ここで secrets.UNITY_EMAIL
と secrets.UNITY_PASSWORD
はUnityのアカウントにログインするためにUnityにて登録したメールアドレスとパスワードを入力してください。(ここではSecret
という形で秘匿しています)
secrets.UNITY_AUTHENTICATOR_KEY
が2段階認証を設定しているときの鍵の情報になります。
以降にてこの値を確認する方法を紹介していきます。
- Unityの設定ページ https://id.unity.com/en/settings/tfa/new にアクセスして
Start setup
を選択します
-
Authenticator App
を選択してNext
を選択します
- QRコード下の
Can't scan the barcode?
を選択すると3.In "Enter your key" type the following key (space not required)
の下の部分に文字列が出現します
- この出てきた文字列を
secrets.UNITY_AUTHENTICATOR_KEY
に設定する
これにより2段階認証が有効になっていてもulfファイルのダウンロードが可能となります。
また2段階認証が有効になっていないままulfファイルのダウンロードを行おうとすると、途中でメール認証のためのメールが送られてしまい、ulfファイルをダウンロードすることができない というようなことが発生する可能性があります。
そのため2段階認証を用いた上記の方法にて実現することをお勧めします。
Unityビルド完了後もう一回ビルドする必要があるものについて
今回のUnityビルドはあくまでUnity側で行われるビルドまでを行います。環境によっては実行ファイルを抽出するためには専用の環境でもう一回ビルドする必要があるものもあります。
以下にビルドした成果物を展開した様子になります
展開したものの様子より、もう一度ビルドする必要がある環境、およびビルドする方法は
- iOS: Xcode を使ってMac OSにて再度ビルド
となります。
Unity Proライセンスを用いてのUnityビルドについて
unity-activate を使用するときに UnityのProライセンスのシリアルコードを --serial シリアル番号
または -s シリアル番号
と指定することでUnityのProライセンスでもUnityの認証を通ってulfファイルをダウンロードすることができます。
例えば以下のようにシリアル番号を設定して unity-activate を実行してください
steps:
- name: Activate The License
id: activateLicense
run: unity-activate -u "${{ secrets.UNITY_EMAIL }}" -p "${{ secrets.UNITY_PASSWORD }}" -k "${{ secrets.UNITY_AUTHENTICATOR_KEY }}" -o ${{ matrix.root-project-path }}/ -s ${{ secrets.UNITY_SERIAL }} "${{ steps.getManualLicenseFile.outputs.filePath }}"
secrets.UNITY_SERIAL
とあるようにUnityのシリアル番号も非公開にすべき情報なので、Github ActionsのSecret
に設定するようにしてください
またUnityのライセンスのシリアル番号を確認する場合は以下の方法で確認することができます
- Unity ID にサインインします。
- マイアカウントをクリックします。
- シートをクリックします。
管理しているUnityのアカウントを選択し、Proライセンスのものにのみシリアル番号を確認します。(画像ではProアカウントがないので一覧には出てきていないのですが)
参考
実装にあたり参考になった記事を以下に紹介します。
まとめ
今回紹介した Github Actions を使用して自動的にUnityビルドを行う方法、また実際に動くレシピ unity-build-personal.yml を紹介しました。
他にもやり方を紹介している記事などを多くみたのですが
git push
〜 Unityビルド完了までを一気に自動的に実現させてくれている記事がなかったため記事を作成しました。
今回紹介したものを活用すると、開発スピードが非常に向上するようになります。
是非活用してみてください。