I recently began doing some work on a personal project in Unity Engine. As with any of my projects, the first thing I set up is a working CI pipeline for it. I find doing this early reinforces best practices. I liked the option of using GitHub Actions, since it is a relatively small project. Here’s how I did it!
First, familiarize yourself with the community offerings for GitHub Actions - game-ci/unity-actions. There’s a good overview here in the readme of the supported actions.
The other thing to check would be the official game-ci getting starting docs.
Setting up License
The instructions in the official docs aren’t the most verbose, but it’s actually quite simple.
I’ll just go into a little more detail here to try to make things super clear.
Step 1 - Request Activation File on GitHub
This is an action that is intended to be a one-time use. Its purpose is to create a “license request file” that will be needed for the next step. This is what will allow unity to run builds on the GitHub Actions servers.
The file should end up looking something like this:
After you push it up, you can manually run the worfklow to generate your license.
To find this file, go to
Your Repository >
Actions. Click on the commit that last ran. You should find a file named something like
Unity_v2019.3.14f1.alf. (The exact name depends on the version string that you put in
You’ll need to save this file locally for use in the next step.
Step 2 - Request License from Unity
Head over to the Unity Manual Activation link.
Here you simply upload your
.alf file from the previous step. Fill out the form with your license details.
On the last step you should be able to download a file that ends in
This is your license you will put in GitHub secrets for use in your build actions.
Step 3 - Save License in GitHub Secrets
Your Repository >
Create a secret called
UNITY_LICENSE and add the contents of the obtained license file (
.ulf). Yes, add the entire XML contents to the GitHub secret.
Now that this step is done, you can delete the
Set up workflow
Now’s the fun stuff! Now that you have your license ready to go, you can start setting up actions.
A couple of best practice recommendations:
- Cache your
Libraryfolder. This is where all your cached packages and large files end up during builds.
- Note caches created on branches are scoped to that branch, regardless of key matches. Same goes for tags.
- Use GitHub Releases to store your file, not actions artifacts. You will quickly run into free limits using artifacts
- Due to the size and time of full builds, I like to generate target builds only on tags.
Here’s an example of a couple of workflow files.
Test - Runs on every commit
Build - Runs on tagged commits
This file uses this
on.push.tags trigger to only run when tags are pushed.
It then uploads artifacts, zips up the binaries, creates a GitHub release for the tag, and uploads the release assets to it.
Depending on your usage, you might not want to upload the artifacts. You’ll quickly run into limits if you use it too much.
Note: If you’re using the above workflow, and experience an error on the build step like this:
You will need to add the artifacts folder to your
.gitignore file, as referenced in this GitHub issue.
Another option would be using the allowDirtyBuild flag if you are still running into dirty branch issues.
Feel free to customize for your use case, as this workflow only outputs windows binaries. However, as mentioned in game-ci/unity-actions, there’s a ton more supported actions/options.
Setting up a CI flow early tends to keep me honest in following best practices. I like to do it even for my hobby projects.
A good side effect, is if I have to let projects idle for a while, I can always come back and expect my builds to work.
Note: Unity referral links are used in product links.