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
- Documentation for actions/upload-artifact
- See where to download the build artifacts.
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.
- See the unity-xcode-builder action for more information.
Universal Windows Platform (UWP) builds require an additional step to build the generated Visual Studio solution.
- See the unity-uwp-builder action for more information.
Having Trouble?
- Visit our troubleshooting guide for common build issues.
- Reach out on Discord if you need help!
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.