Building a Unity CI Environment with GameCI and GitHub Actions

Introduction

Recently, a colleague introduced me to GameCI, a set of libraries for building Unity CI environments. I immediately tried out GameCI's GitHub Actions with a sample project and found that it makes setting up a Unity CI environment incredibly easy.

Of course, Unity Cloud Build has long made it easy to set up CI. However, having GameCI as an option felt like a unique advantage, as it allows you to quickly integrate a Unity CI environment directly into GitHub Actions.

The source code introduced in this article and the project used for verification have been uploaded to GitHub. If you want to grasp the content quickly, please refer to the link below.

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

Since this seems applicable to professional work as well, I've summarized the steps to build a CI environment using GameCI in this article.

Introduction to GameCI Features

Currently, GameCI seems to provide the following GitHub Actions:

Feature	Overview
Activation	Issues a Unity license for a specific Unity version.
Test runner	Runs Unity PlayMode and EditMode tests (supports test result output).
Builder	Executes builds for any platform (can be downloaded using artifacts).
Returning a license	Allows returning a Unity license (supports Professional License only).
Remote builder	If GitHub Actions specs are insufficient, this allows building on high-spec machines in an AWS environment. It uses AWS CloudFormation for infrastructure. (Currently AWS only; GCP and Azure support planned).
Deployment	Deploys Unity builds to various platforms (iOS and Android mentioned). Strictly speaking, it introduces a workflow to deploy the output from Builder using fastlane.

Looking at the above, it appears that GameCI already covers the minimum features a developer would want for Unity CI. Note that I won't be covering Remote builder and Deployment in this article, though I hope to try them in the future.

In this post, I will introduce how to use Activation, Test runner, Builder, and Returning a license with practical examples.

Activation: Activating the Unity License required by GameCI

To activate a Unity license in GameCI, use Activation. I will proceed according to the steps in the documentation.

First, create a workflow file for Unity license activation in the .github/workflows directory of the Unity project on GitHub where you want to introduce CI.

.github/workflows/activation.yml

name: Acquire activation file
on:
  workflow_dispatch: {}
jobs:
  activation:
    name: Request manual activation file 🔑
    runs-on: ubuntu-latest
    steps:
      # Use GameCI's Activation to issue an .alf file
      - name: Request manual activation file
        id: getManualLicenseFile
        uses: game-ci/unity-request-activation-file@v2
        with:
          # Specify the Unity project version
          # You can enter the version listed in ProjectSettings/ProjectVersion.txt
          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 }}

After that, push to the default branch to make it executable in GitHub Actions. Then, follow the steps below to activate and download the Unity license file.

1. Access the GitHub repository from a browser, run the Unity license activation workflow, and generate an alf file

2. Once the workflow run is successful, click the corresponding item to go to the details screen

3. Download the alf file from the Artifacts section

4. Log in to the Unity license manual activation webpage and upload the alf file

5. Enter the appropriate options depending on the intended use of the Unity license (Personal license is selected in this article)

6. Click the Download license button to download the ulf file

This completes the activation of the Unity license file. Next, we will register the activated license file in the GitHub repository's Secrets so that PlayMode and EditMode tests can be executed in GameCI.

The file with the .alf extension refers to the license request file, which is necessary for issuing a Unity license. The file with the .ulf extension is the actual Unity license file.^[1]

Test runner: Running PlayMode and EditMode tests and viewing results

To run tests on GitHub Actions, you need to make the previously activated Unity license information available within the workflow. Therefore, we will start by registering the contents of the ulf file in Secrets.

1. To register Unity license information, go to the Secrets registration screen of the GitHub repository

2. GameCI references UNITY_LICENSE in Secrets by default to access license information. Therefore, register the name as UNITY_LICENSE and paste the contents of the ulf file into the Value field^[2]

With the above steps completed, the environment for running tests and builds in GameCI is ready. We will now create a workflow file for test execution to verify the operation.

.github/workflows/test.yml

name: Run EditMode and PlayMode Test
on:
  workflow_dispatch: {}
jobs:
  test:
    name: Run EditMode and PlayMode Test
    runs-on: ubuntu-latest
    steps:
      # Use actions/checkout@v2 to download the
      # Unity project contents into the working directory
      - name: Check out my unity project.
        uses: actions/checkout@v2

      # Use GameCI's Test runner to run
      # EditMode and PlayMode tests
      - name: Run EditMode and PlayMode Test
        uses: game-ci/unity-test-runner@v2
        env:
          # Specify the Unity license information registered in Secrets in step 2
          UNITY_LICENSE: ${{ secrets.UNITY_LICENSE }}

          # If you want to use a Professional license, you need to enter
          # the email address, password, and serial number
          # 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: .
          # Specify githubToken if you want to see test execution results
          # secrets.GITHUB_TOKEN is available even if not registered in Secrets
          githubToken: ${{ secrets.GITHUB_TOKEN }}

          # Specify the Unity project version
          # You can enter the version listed in ProjectSettings/ProjectVersion.txt
          unityVersion: 2020.3.5f1

          # You can specify the type of tests you want to run
          # Possible values are All, PlayMode, EditMode
          # testMode: All

          # You can explicitly specify the Docker image to use during test execution
          # customImage: 'unityci/editor:2020.1.14f1-base-0'

      # Upload test execution results to artifacts so they can be downloaded and referenced
      - uses: actions/upload-artifact@v2
        if: always()
        with:
          name: Test results
          path: artifacts

The steps to verify the operation of the above workflow file on GitHub Actions are as follows.

1. Select and run the workflow for executing Unity tests

2. Once the workflow run is successful, go to the details screen and check the test execution results from the Test Results item

Although the test execution workflow file is enabled for manual execution using workflow_dispatch, you can also run tests during pull requests by using pull_request.

Builder: Running project builds and checking output results

GameCI also provides GitHub Actions for building your projects. I will verify this by performing a WebGL build with GameCI and making it viewable on GitHub Pages.

I will now create a workflow file for performing the WebGL build.

.github/workflows/webgl_build.yml

name: Run the WebGL build
on:
  workflow_dispatch: {}
jobs:
  build:
    name: Run the WebGL build
    runs-on: ubuntu-latest
    steps:
      # Use actions/checkout@v2 to download the
      # Unity project contents into the working directory
      - name: Check out my unity project.
        uses: actions/checkout@v2

      # Use GameCI's Builder to execute the
      # Unity project build
      - name: Run the WebGL build
        uses: game-ci/unity-builder@v2
        env:
          UNITY_LICENSE: ${{ secrets.UNITY_LICENSE }}
        with:
          # Specify WebGL since we want to perform a WebGL build
          # Other possible values for targetPlatform are listed in the link below
          # ref: https://docs.unity3d.com/ScriptReference/BuildTarget.html
          targetPlatform: WebGL

          unityVersion: 2020.3.5f1
      # Deploy the WebGL build output from Builder to GitHub Pages
      - name: Deploy to GitHub Pages
        uses: JamesIves/github-pages-deploy-action@4.1.3
        with:
          # Specify the orphan branch name for GitHub Pages deployment
          branch: gh-pages

          # Specify the build folder path for deployment
          # GameCI's Builder outputs build contents to the 'build' folder by default
          folder: build

      # Make the WebGL build output from Builder downloadable as an artifact
      - name: Upload the WebGL Build
        uses: actions/upload-artifact@v2
        with:
          name: Build
          path: build

The steps to verify the operation of the above workflow file on GitHub Actions are as follows.

1. Run the workflow for executing the Unity WebGL build

2. Once the workflow run is successful, go to the details screen and confirm the build content looks correct

3. Configure GitHub Pages in Settings to verify the build content

4. Verify the WebGL build operation in a browser via GitHub Pages

By using Builder as shown above, you can verify the success or failure of the WebGL build and ensure the latest build content is always viewable on GitHub Pages. This makes it very useful for events like Unity 1-Week Game Jam, as you can constantly monitor whether the WebGL build is working correctly by simply checking GitHub Pages.

When performing a WebGL build, depending on the Unity version or asset compatibility, builds may be output that do not work correctly in the browser. However, some browser errors can be resolved simply by reviewing the WebGL build settings. For example, if you encounter a unityframework is not defined error, it may be resolved by reviewing the WebGL Build Settings as described in this article.

In my environment, when deploying to GitHub Pages using JamesIves/github-pages-deploy-action, the build content was output to the /WebGL/WebGL folder by default. Therefore, when accessing the WebGL build from a browser, I had to access a URL like <GitHub Pages URL>/WebGL/WebGL.

Returning a license: Returning the Unity License used in GameCI

Although the official website states that this is not usually necessary, it is possible to return a Professional License with GameCI. Since I used a Personal License this time, I didn't use it, but it seems you can return a Professional License by incorporating the following into your workflow steps:

# ...
# Activate the license at some point
- name: Activate Unity
  uses: game-ci/unity-activate@v1
  env:
    UNITY_LICENSE: ${{ secrets.UNITY_LICENSE }}

#...
# Call game-ci/unity-return-license@v1 at the end of the steps
# to return the activated license
- name: Return license
  uses: game-ci/unity-return-license@v1
  if: always()

Conclusion

I have experience building my own CI environment by manually using Unity commands in the past, but using GameCI made it far easier to set up a Unity CI environment on GitHub Actions.

By the way, the Docker images used by GameCI seem to be based on gableroux/unity3d, which has been widely used for a long time. Looking at GabLeRoux's homepage, it turns out they are the one who started developing GameCI. Amazing.

I hope this article helps anyone looking to start building a Unity CI environment with GitHub Actions.

Reference Links

• GameCI - The fastest and easiest way to automatically test and build your game projects
• Services - Cloud Build - Unity
• AWS CloudFormation (Model and manage resources using templates) | AWS
• fastlane - App automation done right
• Managing the default branch name for your repositories - GitHub Docs
• Issuing a serial number for a Personal License in Unity | Yucchiy's Note
• Unity license manual activation webpage
• Encrypted secrets - GitHub Docs
• Unity - Scripting API: BuildTarget
• Unity 1-Week Game Jam | Free game posting site unityroom
• Solution for bug where Unity2020 WebGL loads 90% but the app doesn't start - Qiita
• Deploy to GitHub Pages · Actions · GitHub Marketplace

脚注

1. The .alf and .ulf files are actually XML files.

2. Open the .ulf file with any text editor and copy and paste the entire content.