How to Use the Unity Builder GitHub Action

name: 'Usage of unity-builder GitHub Action'
on:
    push:
        branches:
            - main
jobs:
    deploy:
        runs-on: ubuntu-latest
        steps:
        - uses: actions/checkout@v4
        - uses: game-ci/unity-builder@v4
          env:
            UNITY_LICENSE: ${{ secrets.UNITY_LICENSE }}
            UNITY_EMAIL: ${{ secrets.UNITY_EMAIL }}
            UNITY_PASSWORD: ${{ secrets.UNITY_PASSWORD }}
          with:
            targetPlatform: WebGL

Unity Builder

Build Unity projects for different platforms

What is Unity Builder?​

The Unity Builder GitHub Action is designed to build Unity projects for different platforms. This action is part of the GameCI open-source project and is not affiliated with Unity Technologies.

How to Use the Unity Builder GitHub Action with a Professional License​

When using a professional license, additional setup is required.

- uses: game-ci/unity-builder@v4
  env:
    UNITY_EMAIL: ${{ secrets.UNITY_EMAIL }}
    UNITY_PASSWORD: ${{ secrets.UNITY_PASSWORD }}
    UNITY_SERIAL: ${{ secrets.UNITY_SERIAL }}
  with:
    targetPlatform: WebGL

How to Use the Unity Builder GitHub Action with a License Server​

If you host your own Unity license server, you can provide its URL to use a floating license.

- uses: game-ci/unity-builder@v4
  with:
    targetPlatform: WebGL
    unityLicensingServer: [url to your license server]

How to Store the Build with Unity Builder GitHub Action​

To be able to access your built files, they need to be uploaded as artifacts. To do this, it is recommended to use GitHub Actions' official upload artifact action after any build action.

- uses: actions/upload-artifact@v3
  with:
    name: Build
    path: build

How to Cache Library Files with Unity Builder GitHub Action​

To make builds run faster, you can cache Library files from previous builds. Add GitHub Actions' official cache action before any Unity steps.

- uses: actions/cache@v3
  with:
    path: path/to/your/project/Library
    key: Library-MyProjectName-TargetPlatform
    restore-keys: |
      Library-MyProjectName-
      Library-

How to Specify Target Platform​

Platform that the build should target. Must be one of the allowed values listed in the Unity scripting manual.

with:
  targetPlatform: WebGL

How to Specify Unity Version​

Version of Unity to use for building the project. Use "auto" to get from your ProjectSettings/ProjectVersion.txt.

with:
  unityVersion: 2020.3.11f1

How to Specify Custom Docker Image​

Specific Docker image that should be used for building the project.

with:
  customImage: 'unityci/editor:2020.1.14f1-base-0'

How to Specify Project Path​

Specify the path to your Unity project to be built. The path should be relative to the root of your project.

with:
  projectPath: path/to/your/project

How to Specify Build Name​

Name of the build. Also the folder in which the build will be stored within buildsPath.

with:
  buildName: MyUnityGame

How to Specify Builds Path​

Path where the builds should be stored. In this folder, a folder will be created for every targetPlatform.

with:
  buildsPath: build

How to Specify Build Method​

Custom command to run your build. The method must reference a valid path to a static method residing in the Assets/Editor directory (or in an Editor Assembly).

with:
  buildMethod: EditorNamespace.BuilderClassName.StaticBuildMethod

How to Specify Custom Parameters​

Custom parameters to configure the build. Parameters must start with a hyphen (-) and may be followed by a value (without hyphen). Parameters without a value will be considered booleans (with a value of true).

with:
  customParameters: -profile SomeProfile -someBoolean -someValue exampleValue

How to Specify Versioning Strategy​

Configure a specific versioning strategy.

with:
  versioning: Semantic

How to Configure Android Version Code​

Configure the Android versionCode.

with:
  androidVersionCode: 1000000

How to Specify Android Export Type​

Set the export type for Android builds. Options include androidPackage, androidAppBundle, or androidStudioProject.

with:
  androidExportType: 'androidAppBundle'
  androidKeystoreName: user.keystore
  androidKeystoreBase64: ${{ secrets.ANDROID_KEYSTORE_BASE64 }}
  androidKeystorePass: ${{ secrets.ANDROID_KEYSTORE_PASS }}
  androidKeyaliasName: ${{ secrets.ANDROID_KEYALIAS_NAME }}
  androidKeyaliasPass: ${{ secrets.ANDROID_KEYALIAS_PASS }}

How to Configure Android Keystore Options​

Configure the Android keystore options.

with:
  androidKeystoreName: user.keystore
  androidKeystoreBase64: ${{ secrets.ANDROID_KEYSTORE_BASE64 }}
  androidKeystorePass: ${{ secrets.ANDROID_KEYSTORE_PASS }}
  androidKeyaliasName: ${{ secrets.ANDROID_KEYALIAS_NAME }}
  androidKeyaliasPass: ${{ secrets.ANDROID_KEYALIAS_PASS }}

How to Configure Android Target SDK Version​

Configure the Android target API level.

with:
  androidTargetSdkVersion: 30

How to Export Android Symbols​

Export Android symbols alongside the build. Options are none, public, or debugging.

with:
  androidSymbolType: public

How to Specify SSH Agent Path​

SSH Agent path to forward to the container.

with:
  sshAgent: /path/to/ssh-agent

How to Specify SSH Public Keys Directory Path​

SSH directory path to mount in the container on ~/.ssh.

with:
  sshPublicKeysDirectoryPath: /path/to/public/keys

How to Specify GitHub Private Token​

GitHub private token to pull from GitHub.

with:
  gitPrivateToken: ${{ secrets.GITHUB_PRIVATE_TOKEN }}

How to Run as Host User​

Run the container as the host user based on the file permissions of the cloned project.

with:
  runAsHostUser: true

How to Specify User and Group for File Ownership​

User and optionally group to give ownership of the resulting build artifacts.

with:
  chownFilesTo: user:group

How to Allow Dirty Build​

Allows the branch of the build to be dirty, and still generate the build.

with:
  allowDirtyBuild: true

How to Specify Unity Licensing Server​

Sets the URL to a Unity license server for acquiring floating licenses.

with:
  unityLicensingServer: http://my.unity.license.server

How to Cache Unity Installation on Mac​

Enables caching the Unity Hub and Editor installation for macOS runners.

with:
  cacheUnityInstallationOnMac: true

How to Specify Unity Hub Version on Mac​

Allows pinning the Unity Hub version used on macOS runners.

with:
  unityHubVersionOnMac: 3.4.0

How to Specify Docker Workspace Path​

Allows customizing the build path within the container.

with:
  dockerWorkspacePath: /tmp/build

How to Specify Docker CPU Limit​

Number of CPU cores to assign to the Docker container.

with:
  dockerCpuLimit: 4

How to Specify Docker Memory Limit​

Amount of memory to assign to the Docker container.

with:
  dockerMemoryLimit: 4g

How to Specify Docker Isolation Mode​

Isolation mode to use for the Docker container when running on Windows.

with:
  dockerIsolationMode: hyperv

How to Specify Container Registry Repository​

Container registry and repository to pull the image from.

with:
  containerRegistryRepository: ghcr.io/namespace/imagename

How to Specify Container Registry Image Version​

Container registry image version.

with:
  containerRegistryImageVersion: 3

How to Skip Activation​

Skips the activation step. Useful for macOS self-hosted runners.

with:
  skipActivation: true

How to Enable GPU​

Omits passing the -nographics parameter when launching Unity to perform the build. Useful when using runners that have GPU available.

with:
  enableGpu: true