Skip to main content
Version: v1

Getting started

Unity Actions 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 versions

Unity Actions are based on the unity3d images from GabLeRoux. Any version in the list can be used to test and build projects.

It's generally considered good practice to use the same Unity version for Unity Actions as you do to develop your project.

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.

Note: this repository tests this workflow

name: Actions 😎

on:
pull_request: {}
push: { branches: [main] }

env:
UNITY_LICENSE: ${{ secrets.UNITY_LICENSE }}

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@v1.1.0
with:
path: Library
key: Library

# Test
- name: Run tests
uses: webbertakken/unity-test-runner@v1.7
with:
unityVersion: 2019.2.11f1

# Build
- name: Build project
uses: webbertakken/unity-builder@v1.5
with:
unityVersion: 2019.2.11f1
targetPlatform: WebGL

# Output
- uses: actions/upload-artifact@v1
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.

Note: this repository tests this workflow

name: Actions 😎

on:
pull_request: {}
push: { branches: [main] }

env:
UNITY_LICENSE: ${{ secrets.UNITY_LICENSE }}

jobs:
buildAndTestForSomePlatforms:
name: Build for ${{ matrix.targetPlatform }} on version ${{ matrix.unityVersion }}
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
projectPath:
- test-project
unityVersion:
- 2019.2.11f1
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.
- WebGL # WebGL.
steps:
- uses: actions/checkout@v2
with:
lfs: true
- uses: actions/cache@v1.1.0
with:
path: ${{ matrix.projectPath }}/Library
key: Library-${{ matrix.projectPath }}-${{ matrix.targetPlatform }}
restore-keys: |
Library-${{ matrix.projectPath }}-
Library-
- uses: webbertakken/unity-test-runner@v1.7
id: testRunner
with:
projectPath: ${{ matrix.projectPath }}
unityVersion: ${{ matrix.unityVersion }}
- uses: actions/upload-artifact@v1
with:
name: Test results (all modes)
path: ${{ steps.testRunner.outputs.artifactsPath }}
- uses: webbertakken/unity-builder@v1.5
with:
projectPath: ${{ matrix.projectPath }}
unityVersion: ${{ matrix.unityVersion }}
targetPlatform: ${{ matrix.targetPlatform }}
customParameters: '-myParameter myValue -myBoolean -ThirdParameter andItsValue'
- uses: actions/upload-artifact@v1
with:
name: Build
path: build