はじめに

先日同僚が Unity の CI 環境を構築するためのラむブラリである GameCI に぀いお教えおくれたした。早速 GameCI の GitHub Actions を利甚しお、サンプルプロゞェクトで色々動䜜怜蚌しおみたずころ、Unity の CI 環境を楜に構築できるこずが分かりたした。

もちろん、Unity Cloud Build を利甚すれば CI 環境の構築は以前から楜にできたした。しかし、遞択肢の 1 ぀ずしお GameCI を持っおおくこずで、サクッず GitHub Actions に統合する圢で Unity の CI 環境を導入できるのは他には無いメリットを感じたした。

本蚘事で玹介しおいる゜ヌスコヌド、及び怜蚌時に利甚したプロゞェクトは GitHub にアップ枈みですので、手っ取り早く内容を把握されたい方は䞋蚘をご参照くださいたせ。

https://github.com/nikaera/Unity-GameCI-Sample

業務でも利甚できそうなので、GameCI を利甚しお CI 環境を構築する手順を蚘事でたずめたした。

GameCI に備わっおいる機胜玹介

GameCI には珟状䞋蚘の GitHub Actions が甚意されおいるようです。

機胜抂芁
ActivationUnity ラむセンスを任意の Unity バヌゞョンで発行する
Test runnerUnity の PlayMode 及び EditMode のテストを実行する (テスト結果の出力にも察応)
Builder任意の Platform ビルドを実行する (アヌティファクト 利甚でダりンロヌドも可胜)
Returning a licenseUnity ラむセンスの返华ができる (Professional License のみ察応)
Remote builderGitHub Actions のスペックでは満足のいくビルドができない際に AWS 環境でハむスペックなマシンを甚意しおビルドできる。ビルドのためのむンフラ構築には AWS CloudFormation を䜿甚しおいる (珟圚は AWS のみ察応。今埌 GCP, Azure にも察応予定ずのこず)
DeploymentUnity ビルドを各皮 Platform 向けにデプロむする (iOS 及び Android のみ蚘茉あり。厳密に蚀うず Builder でビルド出力した内容を fastlane を甚いおデプロむするためのワヌクフロヌ玹介になっおいる)

䞊蚘を芋るず既に GameCI には開発者ずしお Unity CI に欲しい機胜は最䜎限揃っおいるように芋受けられたした。 たた本蚘事では、今埌機䌚があれば詊しおみたいず考えおいたすが Remote builder 及び Deployment に぀いおは蚀及しおいたせん。

今回は実䟋を亀えながら Activation 及び Test runner、Builder、Returning a license の䜿甚方法に぀いお玹介しおいきたす。

Activation: GameCI で必芁ずなる Unity License のアクティベヌションを行う

GameCI で Unity ラむセンスをアクティベヌトするには Activation を利甚したす。早速ドキュメントの手順に沿っお䜜業を進めおいきたす。

たず CI を導入したい GitHub 䞊の Unity プロゞェクトの .github/workflows 内に Unity ラむセンスアクティベヌト甚のワヌクフロヌファむルを䜜成したす。

name: Acquire activation file
on:
  workflow_dispatch: {}
jobs:
  activation:
    name: Request manual activation file 🔑
    runs-on: ubuntu-latest
    steps:
      # GameCI の Activation を利甚しお alf ファむルを発行する
      - name: Request manual activation file
        id: getManualLicenseFile
        uses: game-ci/unity-request-activation-file@v2
        with:
          # Unity プロゞェクトのバヌゞョンを指定する
          # ProjectSettings/ProjectVersion.txt に蚘茉されおいるバヌゞョンを入力すれば OK
          unityVersion: 2020.3.5f1
      # Upload artifact (Unity_v20XX.X.XXXX.alf)
      - name: Expose as artifact
        uses: actions/upload-artifact@v2
        with:
          name: ${{ steps.getManualLicenseFile.outputs.filePath }}
          path: ${{ steps.getManualLicenseFile.outputs.filePath }}

その埌、デフォルトブランチ にプッシュしお GitHub Actions で実行可胜にしたら、䞋蚘手順に埓い Unity ラむセンスファむルのアクティベヌト及びダりンロヌドを行いたす。

1. ブラりザから GitHub リポゞトリにアクセスしお、Unity ラむセンスアクティベヌト甚のワヌクフロヌを実行しお <code>alf</code> ファむルを生成する 1. ブラりザから GitHub リポゞトリにアクセスしお、Unity ラむセンスアクティベヌト甚のワヌクフロヌを実行しお alf ファむルを生成する

2. ワヌクフロヌの実行に成功したら、該圓項目をクリックしお詳现画面に遷移する 2. ワヌクフロヌの実行に成功したら、該圓項目をクリックしお詳现画面に遷移する

3. <code>Artifacts</code> の項目から <code>alf</code> ファむルをダりンロヌドする 3. Artifacts の項目から alf ファむルをダりンロヌドする

4. <a href="https://license.unity3d.com">Unity license manual activation webpage</a> からログむンしお <code>alf</code> ファむルをアップロヌドする 4. Unity license manual activation webpage からログむンしお alf ファむルをアップロヌドする

5. Unity ラむセンスの甚途に応じお適切な遞択肢を入力する (本蚘事では Personal ラむセンスを遞択) 5. Unity ラむセンスの利甚甚途に応じお適切な遞択肢を入力する (本蚘事では Personal ラむセンスを遞択)

6. <code>Download license</code> ボタンをクリックしお <code>ulf</code> ファむルをダりンロヌドする 6. Download license ボタンをクリックしお ulf ファむルをダりンロヌドする

これで Unity ラむセンスファむルのアクティベヌトは完了です。次にアクティベヌトしたラむセンスファむルを GitHub リポゞトリの Secrets に登録しお、GameCI で PlayMode 及び EditMode のテストが実行できるようにしおいきたす。

::: message

alf 拡匵子のファむルがラむセンスリク゚ストファむルを指しおいお、Unity ラむセンスの発行に必芁ずなるファむルです。ulf 拡匵子のファむルが Unity ラむセンスのファむルです。1

:::

Test runner: PlayMode 及び EditMode テストを実行しお結果を参照する

GitHub Actions 䞊でテストを実行するために、先ほどアクティベヌトした Unity ラむセンスの情報を ワヌクフロヌ䞊で扱えるようにする必芁がありたす。そのため、たずは Secrets に ulf ファむルの内容を登録するこずから始めたす。

1. Unity ラむセンスの情報登録のため、Github リポゞトリの <code>Secrets</code> 登録画面に遷移する 1. Unity ラむセンスの情報登録のため、Github リポゞトリの Secrets 登録画面に遷移する

2. GameCI はラむセンス情報参照のため <code>Secrets</code> の <code>UNITY_LICENSE</code> を参照する。そのため、<code>Name</code> を <code>UNITY_LICENSE</code> で <code>Value</code> に <code>ulf</code> ファむルの䞭身をコピヌ &amp; ペヌストしおおく 2. GameCI はラむセンス情報参照のため、デフォルト蚭定では Secrets の UNITY_LICENSE を参照する。そのため、Name が UNITY_LICENSE、Value には ulf ファむルの䞭身を登録する2

䞊蚘䜜業で GameCI でテストやビルド実行を行える環境が敎ったので、動䜜怜蚌のためテスト実行甚のワヌクフロヌファむルを䜜成したす。

name: Run EditMode and PlayMode Test
on:
  workflow_dispatch: {}
jobs:
  test:
    name: Run EditMode and PlayMode Test
    runs-on: ubuntu-latest
    steps:
      # actions/checkout@v2 を利甚しお䜜業ディレクトリに
      # Unity プロゞェクトの䞭身をダりンロヌドしおくる
      - name: Check out my unity project.
        uses: actions/checkout@v2

      # GameCI の Test runner を利甚しお
      # EditMode 及び PlayMode のテストを実行する
      - name: Run EditMode and PlayMode Test
        uses: game-ci/unity-test-runner@v2
        env:
          # 2. の手順で Secrets に登録した Unity ラむセンスの情報を指定する
          UNITY_LICENSE: ${{ secrets.UNITY_LICENSE }}

          # もし Professional license を䜿いたい堎合は、
          # メヌルアドレス、パスワヌド、シリアルナンバヌを入力する必芁がある
          # ref: https://game.ci/docs/github/test-runner#professional-license
          # UNITY_EMAIL: ${{ secrets.UNITY_EMAIL }}
          # UNITY_PASSWORD: ${{ secrets.UNITY_PASSWORD }}
          # UNITY_SERIAL: ${{ secrets.UNITY_SERIAL }}
        with:
          projectPath: .
          # テストの実行結果もみたい堎合は githubToken を指定する
          # secrets.GITHUB_TOKEN は Secrets 未登録でも利甚可胜
          githubToken: ${{ secrets.GITHUB_TOKEN }}

          # Unity プロゞェクトのバヌゞョンを指定する
          # ProjectSettings/ProjectVersion.txt に蚘茉されおいるバヌゞョンを入力すれば OK
          unityVersion: 2020.3.5f1

          # 実行したいテストの皮類を指定できる
          # 指定可胜な倀は All, PlayMode, EditMode
          # testMode: All

          # テスト実行時に利甚したい Docker むメヌゞを明瀺的に指定できる
          # customImage: 'unityci/editor:2020.1.14f1-base-0'

      # テストの実行結果をアヌティファクトにアップロヌドしおダりンロヌドしお参照できるようにする
      - uses: actions/upload-artifact@v2
        if: always()
        with:
          name: Test results
          path: artifacts

䞊蚘のワヌクフロヌファむルを GitHub Actions 䞊で動䜜怜蚌する際の手順は䞋蚘になりたす。

1. Unity のテストを実行するためのワヌクフロヌを遞択しお実行する 1. Unity のテストを実行するためのワヌクフロヌを遞択しお実行する

2. ワヌクフロヌの実行が成功したら、詳现画面に遷移した埌、<code>Test Results</code> の項目からテストの実行結果を確認する 2. ワヌクフロヌの実行が成功したら、詳现画面に遷移した埌、Test Results の項目からテストの実行結果を確認する

テスト実行甚のワヌクフロヌファむルでは workflow_dispatch で実行可胜にしおいたすが、pull_request を利甚すればプルリク時にテストを実行させるこずが可胜になりたす。

Builder: プロゞェクトのビルドを実行しお出力結果を確認する

GameCI にはプロゞェクトのビルドを行うための GitHub Actions も甚意されおいたす。実際に GameCI で WebGL ビルドを行いその内容を GitHub Pages で確認できるようにしお動䜜怜蚌しおいきたす。

早速 WebGL ビルドを行うためのワヌクフロヌファむルを䜜成しおいきたす。

name: Run the WebGL build
on:
  workflow_dispatch: {}
jobs:
  build:
    name: Run the WebGL build
    runs-on: ubuntu-latest
    steps:
      # actions/checkout@v2 を利甚しお䜜業ディレクトリに
      # Unity プロゞェクトの䞭身をダりンロヌドしおくる
      - name: Check out my unity project.
        uses: actions/checkout@v2

      # GameCI の Builder を利甚しお、
      # Unity プロゞェクトのビルドを実行する
      - name: Run the WebGL build
        uses: game-ci/unity-builder@v2
        env:
          UNITY_LICENSE: ${{ secrets.UNITY_LICENSE }}
        with:
          # 今回は WebGL ビルドを行いたいため WebGL を指定する
          # WebGL 以倖の指定可胜な倀は䞋蚘に蚘茉の倀が利甚可胜
          # ref: https://docs.unity3d.com/ScriptReference/BuildTarget.html
          targetPlatform: WebGL

          unityVersion: 2020.3.5f1
      # Builder で出力した WebGL ビルドを GitHub Pages にデプロむする
      - name: Deploy to GitHub Pages
        uses: JamesIves/github-pages-deploy-action@4.1.3
        with:
          # GitHub Pages デプロむ甚の Orphan ブランチ名を指定する
          branch: gh-pages

          # デプロむ甚ビルドフォルダパスを指定する
          # GameCI の Builder はデフォルトでは build フォルダにビルド内容を出力する
          folder: build

      # Builder で出力した WebGL ビルドをアヌティファクトでダりンロヌド可胜にする
      - name: Upload the WebGL Build
        uses: actions/upload-artifact@v2
        with:
          name: Build
          path: build

䞊蚘のワヌクフロヌファむルを GitHub Actions 䞊で動䜜怜蚌する際の手順は䞋蚘になりたす。

1. Unity の WebGL ビルドを実行するためのワヌクフロヌを実行する 1. Unity の WebGL ビルドを実行するためのワヌクフロヌを実行する

2. ワヌクフロヌの実行が成功したら、詳现画面に遷移した埌、ビルド内容が正垞か確認する 2. ワヌクフロヌの実行が成功したら、詳现画面に遷移した埌、ビルド内容が正垞そうか確認する

3. ビルド内容を確認するための GitHub Pages の蚭定を Settings から行う 3. ビルド内容を確認するための GitHub Pages の蚭定を Settings から行う

4. GitHub Pages でブラりザから WebGL ビルドの動䜜確認をする 4. GitHub Pages でブラりザから WebGL ビルドの動䜜確認をする

䞊蚘のように Builder を利甚するこずで WebGL ビルドの成吊及び、最新のビルド内容を垞に GitHub Pages で芋られるようにできたす。 するず WebGL ビルドが正垞かどうかの確認が垞に GitHub Pages を芋れば把握できるようになるため、Unity1 週間ゲヌムゞャム などに参加する際で䟿利に掻甚できそうです。

:::message

WebGL ビルドを行う際、Unity バヌゞョンやアセットの察応状況によっおは正しくブラりザ䞊で動䜜しないビルドが出力されたす。ただし、ブラりザで発生する゚ラヌ内容によっおは WebGL のビルド蚭定を芋盎すだけで解決できる堎合がありたす。 䟋えば unityframework is not defined ずいう゚ラヌが発生した際は、この蚘事 のように WebGL の Build Settings を芋盎すこずで解決できる堎合がありたす。

:::

:::message

私の環境では JamesIves/github-pages-deploy-action で GitHub Pages ぞのデプロむを行った際、デフォルトでは /WebGL/WebGL フォルダにビルド内容が出力されたした。そのため、ブラりザから WebGL ビルドにアクセスする際、<GitHub Pages の URL>/WebGL/WebGL のような URL にアクセスする必芁がありたした。

:::

Returning a license: GameCI で利甚しおいる Unity License を返华する

通垞利甚するこずは無いず公匏サむトにも曞かれおいたすが、Professional License の返华も GameCI で行うこずが可胜です。 今回は Personal License を利甚したため䜿甚したせんでしたが、䞋蚘をワヌクフロヌのステップに組み蟌むこずで Professional License を返华できるようです。

# ...
# どこかのタむミングでラむセンスのアクティベヌトを行う
- name: Activate Unity
  uses: game-ci/unity-activate@v1
  env:
    UNITY_LICENSE: ${{ secrets.UNITY_LICENSE }}

#...
# ステップの最埌などに game-ci/unity-return-license@v1 を呌び出しお
# アクティベヌト枈みのラむセンスを返华する
- name: Return license
  uses: game-ci/unity-return-license@v1
  if: always()

おわりに

以前 Unity コマンドを駆䜿しお自分で CI 環境を構築した経隓があるのですが、 GameCI を利甚した方が党然楜に Unity CI 環境構築を GitHub Actions 䞊で行えたした。

ちなみに GameCI で利甚されおいる Docker むメヌゞ は以前からよく䜿われおいた gableroux/unity3d が元になっおいるようでした。っおか GabLeRoux さんのホヌムペヌゞ を芋たら、GameCI の開発を始めた方のようでした。すごい。

本蚘事が GitHub Actions で Unity CI 環境構築を始めようずしおいる方の助けになれれば幞いです。

参考リンク


  1. alf ファむル及び ulf ファむルの実態は XML ファむルです。 ↩︎

  2. 適圓なテキスト゚ディタで ulf ファむルを開き党文をコピヌ & ペヌストしたす。 ↩︎