Github Actionsにて自動的にビルドする環境作成(Unity編) #Unity

結論と概要

Github Actions を使用してGithubに git push が行われたら自動的にUnityビルドを行いその成果物をダウンロードできる仕組みを構築することができたので紹介します。
実際に自動的にUnityビルドを行っているプロジェクトは以下のプロジェクトになります。

github-actions-examples

こちらのプロジェクトに記載されている内容をコピー、改変して利用してください。
実際に Unityビルドを自動的に行なっている場所(実行している処理のレシピ)は以下のようになります。

unity-build-personal.yml

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

この Unity/ 以下のプロジェクトのパスは共通で使用するので以下のように設定しています

strategy:
  matrix:
    root-project-path: [Unity]

Unityビルドが完了した成果物は以下にそれぞれ公開されているのでこちらからダウンロードすることができます。

Actions/execute-unity-builds

また、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の.alfファイルから自動で.ulfをダウンロードしたい！

今回使用しているツールである 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ビルド完了までを一気に自動的に実現させてくれている記事がなかったため記事を作成しました。
今回紹介したものを活用すると、開発スピードが非常に向上するようになります。
是非活用してみてください。