ddengler/unity-actions

Github actions for testing and building Unity projects

Unity Actions

---

The fastest and easiest way to automatically test and build any Unity project!

---

Supported versions

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

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

Project Status

Main workflow actions	Status
Test runner
Builder
Supporting actions
Request activation
Activate license
Return license

Setup

Mental model

There are two parts to setting up Unity Actions;

• Configuring a license
• Setting up a workflow

First time using GitHub Actions?

Read the official documentation on how to setup a workflow.

Any subsequent steps assume you have read the above.

Setting up license

All actions utilize an installment of Unity, and as such need to be activated.

To set up your license for use in Unity Actions, create a file called .github/workflows/activate.yml in your repository and follow the steps for either personal or professoinal license below.

Personal license

1. Request your activation file for usage on GitHub using Request Manual Activation File.
2. Request your license on license.unity3d.com.
3. Open Github > <Your repository> > Settings > Secrets
4. Create a secret called UNITY_LICENSE and add the contents of the obtained license file.

Professional license

1. Open Github > <Your repository> > Settings > Secrets
2. Create the following secrets;
   • UNITY_SERIAL - (Add the code that looks like XX-XXXX-XXXX-XXXX-XXXX-XXXX)
   • UNITY_EMAIL - (Add the email address that you use to login to Unity)
   • UNITY_PASSWORD - (Add the password that you use to login to Unity)

Optional steps

• Verify your license using Activate and for pro licenses also Return License. This is to free up the license allocation after usage.

  Note: Test runner and Builder already include these steps.

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 a repository using Checkout.
2. Cache your library folder using Cache.
3. Configure your test job using Test Runner.
4. Configure your build job using Builder.
5. Deploy your application.

Detailed instructions for each step can be found in the corresponding actions.

Simple example

Below is a simple example.

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: [master] }

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.3
        with:
          unityVersion: 2019.2.11f1

      # Build
      - name: Build project
        uses: webbertakken/unity-builder@v0.10
        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: [master] }

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.3
        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@v0.10
        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

Licence

MIT