GitHub Action to build Unity projects for different platforms.
Part of the Unity Actions collection.
Github Action to build Unity projects for different platforms.
It is recommended to run the Test action from the Unity Actions collection before running this action. This action also requires the Activation step.
See the Unity Actions collection repository for workflow documentation and reference implementation.
By default the enabled scenes from the project's settings will be built.
Create or edit the file called .github/workflows/main.yml and add a job to it.
Personal licenses require a one-time manual activation step (per unity version).
Make sure you acquire and activate your license file and add it as a secret.
Then, define the build step as follows:
- uses: webbertakken/unity-builder@v0.11
env:
UNITY_LICENSE: ${{ secrets.UNITY_LICENSE }}
with:
projectPath: path/to/your/project
unityVersion: 2020.X.XXXX
targetPlatform: WebGLProfessional licenses do not need any manual steps.
Instead, three variables will need to be set.
UNITY_EMAIL(should contain the email address for your Unity account)UNITY_PASSWORD(the password that you use to login to Unity)UNITY_SERIAL(the serial provided by Unity)
Define the build step as follows:
- uses: webbertakken/unity-builder@v0.11
env:
UNITY_EMAIL: ${{ secrets.UNITY_EMAIL }}
UNITY_PASSWORD: ${{ secrets.UNITY_PASSWORD }}
UNITY_SERIAL: ${{ secrets.UNITY_SERIAL }}
with:
projectPath: path/to/your/project
unityVersion: 2020.X.XXXX
targetPlatform: WebGLThat is all you need to build your project.
To be able to access your built files, they need to be uploaded as artifacts. To do this it is recommended to use Github Actions official upload artifact action after any build action.
By default, Builder outputs it's builds to a folder named build.
Example:
- uses: actions/upload-artifact@v1
with:
name: Build
path: buildBuilds can now be downloaded as Artifacts in the Actions tab.
In order to make builds run faster, you can cache Library files from previous builds. To do so simply add Github Actions official cache action before any unity steps.
Example:
- uses: actions/cache@v1.1.0
with:
path: path/to/your/project/Library
key: Library-MyProjectName-TargetPlatform
restore-keys: |
Library-MyProjectName-
Library-This simple addition could speed up your build by more than 50%.
A complete workflow that builds every available platform could look like this:
name: Build project
on:
pull_request: {}
push: { branches: [master] }
env:
UNITY_LICENSE: ${{ secrets.UNITY_LICENSE }}
jobs:
buildForSomePlatforms:
name: Build for ${{ matrix.targetPlatform }} on version ${{ matrix.unityVersion }}
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
projectPath:
- path/to/your/project
unityVersion:
- 2019.2.11f1
- 2019.3.0f1
targetPlatform:
- StandaloneOSX # Build a macOS standalone (Intel 64-bit).
- StandaloneWindows # Build a Windows standalone.
- StandaloneWindows64 # Build a Windows 64-bit standalone.
- StandaloneLinux64 # Build a Linux 64-bit standalone.
- iOS # Build an iOS player.
- Android # Build an Android .apk standalone app.
- WebGL # WebGL.
- WSAPlayer # Build an Windows Store Apps player.
- PS4 # Build a PS4 Standalone.
- XboxOne # Build a Xbox One Standalone.
- tvOS # Build to Apple's tvOS platform.
- Switch # Build a Nintendo Switch player.
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-builder@v0.11
with:
projectPath: ${{ matrix.projectPath }}
unityVersion: ${{ matrix.unityVersion }}
targetPlatform: ${{ matrix.targetPlatform }}
- uses: actions/upload-artifact@v1
with:
name: Build
path: buildNote: Environment variables are set for all jobs in the workflow like this.
Below options can be specified under with: for the unity-builder action.
Specify the path to your Unity project to be built. The path should be relative to the root of your project.
required: false
default: <your project root>
Version of Unity to use for building the project.
required: false
default: 2019.2.1f11
Platform that the build should target.
Must be one of the allowed values listed in the Unity scripting manual.
required: true
Name of the build. Also the folder in which the build will be stored within buildsPath.
required: false
default: <build_target>
Path where the builds should be stored.
In this folder a folder will be created for every targetPlatform.
required: false
default: build
Custom command to run your build.
There are two conditions for a custom buildCommand:
- Must reference a valid path to a
staticmethod. - The class must reside in the
Assets/Editordirectory.
example:
- uses: webbertakken/unity-builder@<version>
with:
buildMethod: EditorNamespace.BuilderClassName.StaticBulidMethodrequired: false
default: Built-in script that will run a build out of the box.
The versioning strategy to use.
Strategies only work when no custom buildMethod is specified.
required: false
default: Auto
No version will be set by Builder.
- uses: webbertakken/unity-builder@<version>
with:
versioning: NoneNote that the version set in the project will be used instead.
Builder automatically generates a version based on semantic versioning out of the box.
The version works as follows: <major>.<minor>.<patch> for example 0.1.2.
The latest tag dictates <major>.<minor> and the number of commits since that tag is used in <patch>.
- uses: webbertakken/unity-builder@<version>
with:
versioning: SemanticThis strategy works well for the following reasons:
- All builds have their unique version
- No version related commits are created
- No knowledge of git or versioning is required
- Developer keeps control over
majorandminorversions using tags. - Zero configuration; It works out of the box
Uses the tag that points at HEAD as the version.
- uses: webbertakken/unity-builder@<version>
with:
versioning: TagThis strategy works well when using a pipeline that specifically runs for tags.
The tag must be a version tag.
Allows specifying a custom version in the version field.
- uses: webbertakken/unity-builder@<version>
with:
versioning: Custom
version: <some_version>If there is a use case missing from Builder, feel free to create a feature request.
Custom parameters to configure the build.
Parameters must start with a hyphen (-) and may be followed by a value (without hyphen).
Parameters without a value will be considered booleans (with a value of true).
example:
- uses: webbertakken/unity-builder@<version>
with:
customParameters: -profile SomeProfile -someBoolean -someValue exampleValuerequired: false
default: ""
Visit Unity Actions to find related actions for Unity.
Feel free to contribute.