GameCI and GitHub Actions for Unity Automation

The integration of Continuous Integration and Continuous Deployment (CI/CD) into the Unity game development pipeline represents a fundamental shift in how interactive software is engineered, tested, and delivered. By leveraging GitHub Actions, specifically through the ecosystem provided by GameCI, developers can transition from a manual, error-prone build process to an automated framework where every commit is validated, tested, and compiled without human intervention. This automation solves a critical bottleneck in the Unity editor: the "editor lock," where the software becomes unusable during the build process, often for hours. By offloading these tasks to GitHub-hosted or self-hosted runners, the development cycle is streamlined, allowing engineers to focus on feature implementation while the infrastructure handles the heavy lifting of compilation and artifact generation.

The Fundamental Mental Model of Unity Automation

To successfully implement automation for Unity, a developer must first internalize the operational flow of GitHub Actions. The process is not merely about running a script but about orchestrating a series of virtualized environments that mimic a developer's local machine.

The overall architectural flow follows a specific sequence:

• Understanding the mechanics of GitHub Actions: This involves grasping how triggers (events) initiate jobs, which in turn execute a series of steps.
• License Configuration: Because Unity is commercial software, the automation runner must be authenticated via a valid license to operate the editor in headless mode.
• Workflow Definition: This is the creation of a YAML configuration file that defines exactly what happens during the CI/CD process.
• Validation: The end result is the ability to merge pull requests with significantly higher confidence, knowing that the code compiles and passes all automated tests.

Workflow Architecture and Implementation

Setting up a workflow requires the creation of a specific configuration file located at .github/workflows/main.yml within the root of the repository. This file serves as the blueprint for the entire automation process.

The standard operational sequence for a Unity workflow consists of the following critical steps:

• Checkout: The workflow must first use the actions/checkout action to pull the repository's source code onto the runner.
• Caching: To avoid downloading and regenerating the Unity Library folder on every run, the actions/cache action is used. This significantly reduces build times by storing the Library folder across different workflow runs.
• Test Execution: The Test Runner is configured to execute all project tests to ensure no regressions have been introduced.
• Build Execution: The Builder action compiles the project into a playable binary.
• Deployment: The final application is deployed to a target platform or uploaded as a GitHub artifact.

Technical Specifications of the Setup-Unity Action

The setup-unity action is a critical component based on Unity Hub, designed to download and install the specific version of the Unity editor required for the project. It is cross-platform, supporting Ubuntu, macOS, and Windows environments.

The following table details the configuration parameters for the setup-unity action:

Critical operational warnings regarding the setup-unity action include:

• macOS Android Installation: Installing the android module along with its child modules can cause the process to freeze on macOS. It is highly recommended to implement timeout-minutes in the workflow configuration to prevent hung runners.
• Storage Limitations: On GitHub-hosted Ubuntu runners, the workflow may fail with System.IO.IOException: No space left on device due to the massive size of Unity installations and project libraries.

The Unity Builder and the GameCI Ecosystem

The Unity Builder is a specialized GitHub Action developed as part of the GameCI open-source project. It is important to note that this tool is not affiliated with Unity Technologies and is not certified by GitHub; it is governed by separate third-party terms of service.

The Builder allows for the compilation of Unity projects across diverse platforms. Because it is MIT licensed, it encourages community contribution. The primary benefit of using the Builder is the removal of the "twiddling your thumbs" phase of development, as the build process is decoupled from the local editor.

For those seeking higher performance than standard GitHub runners, options such as Buildalon runners can be utilized to accelerate the process, though standard or self-hosted runners remain viable alternatives.

License Management and Secret Configuration

A pivotal requirement for any Unity CI/CD pipeline is the handling of the Unity license. Since the editor requires activation to run in headless mode, the license file (.ulf) must be extracted from a local machine and stored as a GitHub Secret.

The location of the license file varies by operating system:

• Windows: C:\ProgramData\Unity\Unity_lic.ulf
• Mac: /Library/Application Support/Unity/Unity_lic.ulf
• Linux: ~/.local/share/unity3d/Unity/Unity_lic.ulf

Developers must open these files with a text editor and upload the contents to GitHub Secrets. In addition to the license, the following secrets are typically required for authentication:

• UNITY_EMAIL: The email associated with the Unity account.
• UNITY_PASSWORD: The password for the Unity account.
• UNITY_LICENSE: The content of the .ulf license file.

Advanced Implementation: IL2CPP and Matrix Strategies

For complex projects, a simple linear workflow is insufficient. The use of a "matrix" in GitHub Actions allows developers to test and build for multiple Unity versions and target platforms in parallel.

IL2CPP (Intermediate Language To C++) builds have a strict requirement: the base operating system of the runner must match the build target. For example, an iOS build requires a macOS runner.

A sophisticated workflow configuration for IL2CPP and multi-platform support looks like this:

yaml name: Actions 😎 on: [push, pull_request] jobs: buildAndTestForLinuxBasedPlatforms: name: Build for ${{ matrix.targetPlatform }} runs-on: ubuntu-latest strategy: fail-fast: false matrix: projectPath: - test-project unityVersion: - 2019.4.1f1 - 2020.2.1f1 targetPlatform: - StandaloneLinux64 - iOS - Android - WebGL steps: - uses: actions/checkout@v4 with: fetch-depth: 0 lfs: true - uses: actions/cache@v3 with: path: ${{ matrix.projectPath }}/Library key: Library-${{ matrix.projectPath }}-${{ matrix.targetPlatform }}-${{ hashFiles(matrix.projectPath) }} restore-keys: | Library-${{ matrix.projectPath }}-

In this configuration, the fail-fast: false setting ensures that if one platform build fails, the others continue to execute. The lfs: true flag in the checkout step is mandatory for Unity projects to ensure that large assets are correctly pulled from Git LFS.

Integrating Unity Gaming Services (UGS) CLI

Beyond building the binary, developers often need to manage cloud services. The Unity Gaming Services (UGS) CLI can be integrated into GitHub Actions to automate service configurations and deployments.

The following implementation demonstrates the deployment of service configurations using a specialized recipe:

yaml name: UGS CLI GitHub Actions Demo on: push env: UGS_CLI_PROJECT_ID: "your-project-id" UGS_CLI_SERVICE_KEY_ID: "your-service-key-id" UGS_CLI_SERVICE_SECRET_KEY: "your-service-secret-key" jobs: demo-cli: runs-on: ubuntu-latest steps: - name: Download CLI run: curl -OL https://github.com/Unity-Technologies/unity-gaming-services-cli/releases/latest/download/ugs-linux-x64 - name: Test CLI Commands run: | chmod +x ./ugs-linux-x64 ./ugs-linux-x64 --version ./ugs-linux-x64 config get project-id ./ugs-linux-x64 status ./ugs-linux-x64 env list ./ugs-linux-x64 deploy <directory-with-service-configurations> -j

This setup allows for the automation of backend service updates, ensuring that the game client and the cloud services are always in sync.

Operational Best Practices and Troubleshooting

Implementing Unity automation is not without challenges. Many developers find that GitHub Actions is not an intuitive scripting system and requires a significant time investment to master. The "commit-push-wait-fail" cycle can be frustrating for first-time users.

To optimize the pipeline, the following steps are recommended:

• Use of specialized Git clients: Tools like Anchorpoint can be used to manage the repository and ensure that changes are committed before triggering actions.
• Workflow Permissions: It is critical to change the workflow permissions to "read and write" within the GitHub repository settings to allow the action to upload artifacts.
• Build Settings Validation: Before triggering a build, ensure the project has at least one scene added to the build settings. For WebGL targets, specific project tweaks are required to ensure compatibility with the web browser.
• Artifact Management: Use the actions/upload-artifact action to store the resulting build. This allows developers to download the binary directly from the GitHub Actions tab.

Example of a build and upload step:

```yaml
- name: Build project
uses: game-ci/unity-builder@v4
env:
UNITYLICENSE: ${{ secrets.UNITYLICENSE }}
UNITYEMAIL: ${{ secrets.UNITYEMAIL }}
UNITYPASSWORD: ${{ secrets.UNITYPASSWORD }}
with:
targetPlatform: StandaloneWindows64
allowDirtyBuild: true

• uses: actions/upload-artifact@v4
  with:
  name: Build
  path: build
  ```

Conclusion

The transition to an automated Unity pipeline via GitHub Actions and GameCI transforms the development process from a series of manual hurdles into a streamlined, industrial-grade software factory. By abstractly managing the installation of the editor through setup-unity, handling licenses via secure secrets, and leveraging matrix strategies for multi-platform builds, development teams can eliminate the productivity loss associated with editor locking and manual compilation. The integration of UGS CLI further extends this automation to the cloud layer, creating a holistic environment where code, assets, and services are deployed in unison. While the learning curve for YAML-based workflows is steep and the storage limitations of hosted runners can be problematic, the resulting increase in deployment velocity and confidence in build stability makes this architecture indispensable for professional Unity development.

Sources

1. GameCI Getting Started
2. GitHub Marketplace: Setup Unity
3. GitHub Marketplace: Unity Builder
4. Unity Discussions: Automating Unity Builds
5. Unity Docs: UGS CLI CI/CD
6. Anchorpoint: Setting up CI/CD for Unity