Ever had to wait more than 20 minutes to get a build ready for your Unity project? Or have you ever had to build multiple target platforms for a single project? If you have faced one of the issues, you must have considered automating your Unity project's builds. So, in this blog, we will have a walkthrough on automating Unity Project builds with our GameCI GitHub Actions integrations.
GitHub Actions is a dynamic platform designed to help developers streamline their software development workflow. This is achieved by creating customized actions that respond to specific events like code modifications or release updates.
Developers can easily build, test and deploy their code. Thanks to the platform's extensive collection of pre-existing actions and the option to create custom ones. The workflows can be defined in a YAML file, which provides easy version control and efficient management of any changes made. The workflows can be triggered automatically and manually according to specific requirements.
Creating the Required Files
To dive into creating the workflow, we will first need to get inside our project repo and create a folder named
.github with a child folder named
workflows inside it. The following child folder
workflow will have two of the major files
This is a YAML file defining a GitHub Actions workflow called
Get Unity license activation file. It has one job called
requestManualActivationFile that runs on the latest version of Ubuntu.
The first step is to check the repository's source code using the
The second step uses a custom action called
webbertakken/unity-request-manual-activation-file to request a manual activation file for a Unity license. The output file path is stored in the
The third and final step uses the
actions/upload-artifact action to upload the output file from the previous step as an artifact with the name
Manual Activation File. This artifact can then be downloaded and used as needed. You can copy and paste the content below to your
Activation.yaml file too.
This YAML file defines a GitHub Actions workflow for building and testing a Unity game project.
The workflow consists of four jobs, each with its own steps.
testRunner: This job runs Unity Test Runner to run tests for the game in both Editor/PlayMode. Use this to check errors or do unit testing before the build process.
buildAndroid: These jobs build the game for WebGL, Windows and Android, respectively, and create an artifact of the build.
Each job runs on an Ubuntu environment and includes a set of steps that perform the following actions.
- Check out the code from the repository.
- Create a list of large files (LFS) needed for the build/test.
- Restore the LFS cache to avoid downloading large files on every run.
- Pull LFS files from the Git LFS server.
- Restore the Unity library cache to avoid downloading it on every run.
- Build the game for the specified target platform using Unity Builder.
- Upload the build artifact to the GitHub Actions artifacts storage.
The workflow is triggered by a
push event and requires the
UNITY_LICENSE secret to being defined, which contains a Unity license key. However, you can customize the trigger event to something like a custom event action or a release trigger action.
You can copy and paste the content below to your
Template.yaml file too.
Actions Page on GitHub
After successfully creating the files mentioned above and pushing those changes to your GitHub repo, you should be able to navigate to your repo's Actions page. The page will show you two workflows, one for the GameCI template and another called
Get Unity License activation. The GameCI template will generate the builds, and the
Get Unity License activation will generate your manual Unity license activation file.
Manually Activating Your Unity License For The Builder
First, you will need to get inside the
Get Unity License workflow, which will prompt you with an option to run your job. After some time, the job will be completed, and it will generate an
.ulfartifact called a
Manual Activation File. Then, download it in
.zip format and keep it safe for later usage. Also, a green icon should appear in the action workflow, indicating that the task has been successfully completed.
After you receive the manual activation artifact, head towards Unity's Manual Activation site. On the website, you can upload the
.alf file generated by the
Request manual activation file workflow. Proceed to choose your required Unity plan and continue. This process will also provide you with another file but in
.ulf a format which can be downloaded and saved.
On receiving the file, head over to your GitHub repo settings and create a new secret action variable called
UNITY_LICENSE. Ensure the variable name is the same as the one used for accessing the license in the YAML files above.
After creating the secret variable, open the license file of
.ulf the format in any text editor to copy its content and paste it into the content field of your secret token.
Preparing for the Build
After completing the license generation, move on to the GitHub action page, where you can see your latest commit being processed by the GameCI template workflow.
First, the workflow job will test the Unity project to verify that there are no remaining test cases or errors in both play & edit modes. Next, it will build for all the target platforms in your
template.yaml file. The build will take some time for the first run to ensure all the necessary Unity libraries and project dependencies are cached. Once the first build is completed, you may notice an increase in the speed of the builds.
Accessing your Build Files
Once the build is completed, you can find your files as artifacts below your workflow window. Transfer your files to respective platforms and test them out.
Using an automated build system can save you a lot of time & make your development flow smoother. This way, you won't get stuck in the build process and won't have to keep switching platforms to perform multiple target platform builds.
You can also configure this in a way that will upload all your build files to a destination like game servers or an FTP service. For example, while using a multiplayer game service, you can simultaneously test your game by uploading your server & client builds together simultaneously. Also, thanks to the GameCI community for creating an easy CI/CD backbone integration for Unity.
If you encounter any errors in the process, let me know by commenting below. Thanks for reading!