Getting started

GitHub Actions for Unity provide the fastest and easiest way to automatically test and build any Unity project.
There are a few parts to setting up a workflow. Steps may slightly differ depending on each license type.

Mental model#

Overall steps#

  1. Understand how Github Actions work.
  2. Configure a license for Unity.
  3. Set up a workflow for your project.
  4. Result: Merge pull requests with more confidence.

Setting up a workflow#

Setting up a workflow is easy!
Create a file called .github/workflows/main.yml in your repository and configure the following steps;
  1. Checkout your repository using Checkout.
  2. Cache Unity Library folder using Cache.
  3. Configure your test job using Test Runner.
  4. Configure your build job using Builder.
  5. Deploy your application.
Note: all steps will be explained in the next chapters.

Support#

First time using GitHub Actions?#

Read the official documentation on how to setup a workflow.
Any subsequent steps assume you have read the above.

Supported unity versions#

Unity Actions are using game-ci/docker since unity-builder version 2. Any version in this list can be used.

Video tutorial#

Simple example#

Below is a simple example. It is recommended to start from here.
This example assumes that your Unity project is in the root of your repository.
name: Actions 😎 on: [push, pull_request] jobs: build: name: Build my project ✨ runs-on: ubuntu-latest steps: # Checkout - name: Checkout repository uses: actions/checkout@v2 with: lfs: true # Cache - uses: actions/cache@v2 with: path: Library key: Library-${{ hashFiles('Assets/**', 'Packages/**', 'ProjectSettings/**') }} restore-keys: | Library- # Test - name: Run tests uses: game-ci/unity-test-runner@v2 env: UNITY_LICENSE: ${{ secrets.UNITY_LICENSE }} with: githubToken: ${{ secrets.GITHUB_TOKEN }} # Build - name: Build project uses: game-ci/unity-builder@v2 env: UNITY_LICENSE: ${{ secrets.UNITY_LICENSE }} with: targetPlatform: WebGL # Output - uses: actions/upload-artifact@v2 with: name: Build path: build

Simple example with Git LFS#

If you are using GitHub's git-lfs hosting service to store your large binary assets, you will want to cache them to avoid consuming massive amounts of bandwidth. The extra steps in this example try to restore your git-lfs assets from a cache before doing a git lfs pull.
name: Actions 😎 on: [push, pull_request] jobs: build: name: Build my project ✨ runs-on: ubuntu-latest steps: # Checkout (without LFS) - name: Checkout repository uses: actions/checkout@v2 # Git LFS - name: Create LFS file list run: git lfs ls-files -l | cut -d' ' -f1 | sort > .lfs-assets-id - name: Restore LFS cache uses: actions/cache@v2 id: lfs-cache with: path: .git/lfs key: ${{ runner.os }}-lfs-${{ hashFiles('.lfs-assets-id') }} - name: Git LFS Pull run: | git lfs pull git add . git reset --hard # Cache - uses: actions/cache@v2 with: path: Library key: Library-${{ hashFiles('Assets/**', 'Packages/**', 'ProjectSettings/**') }} restore-keys: | Library- # Test - name: Run tests uses: game-ci/unity-test-runner@v2 env: UNITY_LICENSE: ${{ secrets.UNITY_LICENSE }} with: githubToken: ${{ secrets.GITHUB_TOKEN }} # Build - name: Build project uses: game-ci/unity-builder@v2 env: UNITY_LICENSE: ${{ secrets.UNITY_LICENSE }} with: targetPlatform: WebGL # Output - uses: actions/upload-artifact@v2 with: name: Build path: build

Advanced example#

To get an idea of how to create a more advanced workflows, have a look at the example below.
name: Actions 😎 on: [push, pull_request] jobs: buildAndTestForSomePlatforms: 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: - StandaloneOSX # Build a macOS standalone (Intel 64-bit). - StandaloneWindows64 # Build a Windows 64-bit standalone. - StandaloneLinux64 # Build a Linux 64-bit standalone. - iOS # Build an iOS player. - Android # Build an Android player. - WebGL # WebGL. steps: - uses: actions/checkout@v2 with: fetch-depth: 0 lfs: true - uses: actions/cache@v2 with: path: ${{ matrix.projectPath }}/Library key: Library-${{ matrix.projectPath }}-${{ matrix.targetPlatform }}-${{ hashFiles(matrix.projectPath) }} restore-keys: | Library-${{ matrix.projectPath }}-${{ matrix.targetPlatform }}- Library-${{ matrix.projectPath }}- Library- - uses: game-ci/unity-test-runner@v2 id: testRunner env: UNITY_LICENSE: ${{ secrets.UNITY_LICENSE }} with: projectPath: ${{ matrix.projectPath }} unityVersion: ${{ matrix.unityVersion }} githubToken: ${{ secrets.GITHUB_TOKEN }} - uses: actions/upload-artifact@v2 if: always() with: name: Test results (all modes) path: ${{ steps.testRunner.outputs.artifactsPath }} - uses: game-ci/unity-builder@v2 env: UNITY_LICENSE: ${{ secrets.UNITY_LICENSE }} with: projectPath: ${{ matrix.projectPath }} unityVersion: ${{ matrix.unityVersion }} targetPlatform: ${{ matrix.targetPlatform }} customParameters: '-myParameter myValue -myBoolean -ThirdParameter andItsValue' - uses: actions/upload-artifact@v2 with: name: Build path: build
Edit on GitHub