Build Unity

The Build Unity workflow in Buildalon automates the process of compiling Unity projects across multiple platforms. By configuring a job matrix and using specific actions, this workflow handles Unity project setup, licensing, building, and artifact management. This setup ensures efficient builds across different platforms and simplifies artifact handling for release and testing.

See a full example workflow by generating one at buildalon.com/start.

Job Matrix

A job matrix allows you to define multiple configurations within a single workflow. Each configuration specifies an operating system and build target, letting you build for multiple platforms concurrently. Below is an example of a job matrix configured to build for the Windows platform using the StandaloneWindows64 target.

Example Job Matrix Configuration

jobs:
  build:
    env:
      UNITY_PROJECT_PATH: ''
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [buildalon-windows]
        include:
          - os: buildalon-windows
            build-target: StandaloneWindows64
            build-args: ''

Steps

Here are the minimum recommended steps to build Unity.

1. Checkout the Code

Clones the repository with submodules, Git LFS, and options for a clean checkout.

If your project depends on packages or repositories outside of your repository, refer to the Accessing Dependencies page.

- uses: actions/checkout@v4
  with:
    clean: ${{ github.event.inputs.clean == 'true' }}
    lfs: true
    submodules: 'recursive'

Documentation for actions/checkout

2. Setup Unity

Installs Unity Hub and the version of Unity used by your project. If you have more than one project, you need to specify the path to the ProjectVersion.txt file.

- uses: buildalon/unity-setup@v1
  with:
    version-file: 'path/to/your/unity/project/ProjectSettings/ProjectVersion.txt'
    build-targets: '${{ matrix.build-target }}'

Documentation for buildalon/unity-setup

3. Activate Unity License

Authenticates Unity using personal or professional license credentials.

Personal License:

- uses: buildalon/activate-unity-license@v1
  with:
    license: 'Personal'
    username: '${{ secrets.UNITY_USERNAME }}'
    password: '${{ secrets.UNITY_PASSWORD }}'

Professional License:

- uses: buildalon/activate-unity-license@v1
  with:
    license: 'Professional'
    username: '${{ secrets.UNITY_USERNAME }}'
    password: '${{ secrets.UNITY_PASSWORD }}'
    serial: '${{ secrets.UNITY_SERIAL }}'

Documentation for buildalon/activate-unity-license

4. Add Build Pipeline Package

Adds the Build Pipeline package to your project. This package is required to build your project from the command line.

- name: Add Build Pipeline Package
  working-directory: ${{ env.UNITY_PROJECT_PATH }}
  run: |
    npm install -g openupm-cli
    openupm add com.virtualmaker.buildalon

Documentation for com.virtualmaker.buildalon

5. Project Validation

Validates the Unity project by opening it, importing all assets, and checking for script compile errors.

- uses: buildalon/unity-action@v1
  name: Project Validation
  with:
    log-name: 'project-validation'
    build-target: '${{ matrix.build-target }}'
    args: '-quit -batchmode -executeMethod Buildalon.Editor.BuildPipeline.UnityPlayerBuildTools.ValidateProject'

Documentation for buildalon/unity-action

6. Build Unity Project

Executes the Unity build process for the specified platform target.

- uses: buildalon/unity-action@v1
  name: '${{ matrix.build-target }}-Build'
  with:
    log-name: '${{ matrix.build-target }}-Build'
    build-target: '${{ matrix.build-target }}'
    args: '-quit -batchmode -executeMethod Buildalon.Editor.BuildPipeline.UnityPlayerBuildTools.StartCommandLineBuild${{ matrix.build-args }}'

7. Upload Artifacts

Zips and upload the build artifacts to the GitHub Actions server for download. Note that the set of paths to upload will vary per-platform. What is shown here is good for Windows.

If you generate a workflow at buildalon.com/start, you’ll get an upload step with the correct paths for your selected platforms.

- uses: actions/upload-artifact@v4
  id: upload-artifact
  name: 'Upload ${{ matrix.build-target }} Artifacts'
  if: success() || failure()
  with:
    compression-level: 0
    retention-days: 1
    name: '${{ github.run_number }}.${{ github.run_attempt }}-${{ matrix.os }}-${{ matrix.build-target }}-Artifacts'
    path: |
      ${{ github.workspace }}/**/*.log
      ${{ env.UNITY_PROJECT_PATH }}/Builds/StandaloneWindows64/**/*.exe
      ${{ env.UNITY_PROJECT_PATH }}/Builds/StandaloneWindows64/**/*.dll
      ${{ env.UNITY_PROJECT_PATH }}/Builds/StandaloneWindows64/**/*_Data
      ${{ env.UNITY_PROJECT_PATH }}/Builds/StandaloneWindows64/MonoBleedingEdge

8. Clean Artifacts

Removes all build artifacts and logs from the project directory. This is recommended for Buildalon Cloud Runners reclaim disk space between runs.

- name: Clean Artifacts
  if: always()
  shell: pwsh
  run: |
    # Clean Logs
    Get-ChildItem -Path "${{ env.UNITY_PROJECT_PATH }}" -File -Filter "*.log" -Recurse | Remove-Item -Force

    $artifacts = "${{ env.UNITY_PROJECT_PATH }}/Builds"
    Write-Host "::debug::Build artifacts path: $artifacts"

    if (Test-Path -Path $artifacts) {
      try {
        Remove-Item $artifacts -Recurse -Force
      } catch {
        Write-Warning "Failed to delete artifacts folder file: $_"
      }
    } else {
      Write-Host "::debug::Artifacts folder not found."
    }

Additional Build Steps for Specific Platforms

Some platforms require additional steps to complete the build process.

iOS, macOS, and visionOS IL2CPP builds require an additional step to build the generated XCode project.

Universal Windows Platform (UWP) builds require an additional step to build the generated Visual Studio solution.

Having Trouble?

Next Steps

  • Triggers: Set up triggers to start workflows automatically.
  • Build Unity: Set up automated builds for your Unity project.
  • Buildalon Actions: Explore the actions available to use in your workflows.
  • Unit Testing: Automate unit testing to ensure stability and quality.
  • Deploy to Stores: Add deployment steps to distribute your app to users.
  • Dependencies: Learn what to do if your project depends on other private packages or repositories.

© 2024 Virtual Maker Corporation