Continuous integration for Unity 3D projects using Azure Pipelines

When working with Unity 3D, have you ever found yourself thinking “Wouldn’t it be cool if I could just push my code to the repository and then magically I get a build with the latest changes ready for distribution to my testers or the client?” — Think no more! This article will teach you how to setup continuous integration for your Unity project using Microsoft’s Azure Pipelines, which are part of the awesome Azure DevOps suite.

Step 1: Install the required extension to build Unity projects

As of now Azure Pipelines does not have a built-in task for building Unity projects. Luckily it’s extendible and we can create our own build task for use in our pipelines. “Ain’t nobody got time for this!” you say? No worries, I already went ahead and created an extension for you to use. Head to the marketplace and install it for use in your organization:

Searching for “Unity” in the marketplace to install the needed extension

Please note: There is another Unity build extension. But that one targets specifically HoloLens Unity projects and requires the HoloToolkit to be in the project. Make sure you get the right one for this article, which is the one titled “Unity Build”.

Please note also: I’ve made the extension open source on GitHub. If you feel the need to improve on it please feel free to do a pull request. Also please report any issues over there, so I can fix them.

Step 2: Create and configure your custom build agent

While you could use the Microsoft hosted agents, I recommend setting up your own agent for Unity builds. This gives you full control over the available Unity versions and modules. Let’s get started. Navigate to your Azure DevOps homepage and in the top right corner click on your profile picture, in the menu then select “Security”.

Opening the security settings for your Azure DevOps account

This will open the security settings when you can create a Personal Access Token (PAT) that your agent can use to configure itself with the DevOps Organzation.

Creating the PAT for your agent

Select “New Token” right below the page header, then give a meaningful name to your PAT. Select “Custom defined” scopes and in the lower end of the panel find “Show more scopes”. Now find the “Agent Pools” scope and tick the “Read & manage” checkbox. Finally click “Create” to create the PAT. Make sure to note the PAT somewhere until we need it. You will not be able to see it again, once the panel has closed. Next we will setup the agent.

Creating a new agent pool

Select “Organzation settings” and then “Agent pools”. Click “New agent pool…” to create a new pool. Name it Unity Windows Agents e.g. If you are creating a Mac agent, name the pool accordingly. You will need this name later. Last but not least click “Download agent”. Please follow the instructions to download and configure your agent. You will need the PAT and Agent pool name in this process. Let me know in the comments, if you have any issues. Last but not least, please install the Unity Hub on the agent and install the Unity versions you need.

Installilng Unity versions you need using the Unity Hub

Step 3: Setting up an example build pipeline

For this article we’ll create a build pipeline targeting the Android platform. The steps may differ a bit depending on your project’s target platform but should generally be similar. So head over to your Azure DevOps project and in the pipelines section, create a new build pipeline, by clicking “New” -> “New build pipeline”:

Creating a new Azure Pipeline

Next you need to tell the pipeline wizard where to get the source code from. In my case, it’s all hosted on Azure Repos. You can change these settings later on, if you need to:

Selecting the repository to build from

The wizard will now offer some templates to start from. Please select the empty job template. We want to start from scratch:

Creating an empty pipeline using the Empty job template

Alright. Now click the plus icon button as highlighted in the screenshot below, enter “Unity” in the task search textbox and add the Unity Build task, you installed in the beginning of this article, to the job:

Adding the Unity build task to your pipeline

Now please repeat and add the following tasks as well “Android Signing”, “Copy Files” and “Publish Build Artifacts”. Your pipeline should now look something like this:

Example pipeline for building a signed Android APK

I am not going into details with the Microsoft built-in tasks. If you have issues configuring them, please refer to the official documentation or let me know, maybe I can help out. We’ll focus on the Unity Build task and how to configure it.

Configuring the Unity build task

Basically the only thing you need to do here, is tell the task which target platform you are building for. We are targeting Android in this example, so make sure to select “Android” in the “Build Target” dropdown. For “Unity Version” select “Project Version”. This will build the project with the Unity version it was last opened with. Make sure it’s installed on the agent.

Assigning a reference name to access output variables

Next unfold the “Output Variables” section of the task and enter a reference name here. The task provides a buildOutputPath variable you can use in following tasks to get the build output files.

That’s it! This pipeline will build your Unity project, sign the APK and publish it to the Azure DevOps artifact store so others can download it. In an advanced scenario you could let the pipeline publish it to the App center or some store e.g. for testing.

Conclusion

Setting up your own build agent is a one time process that will definitely pay out once you get comfortable building your projects using Azure Pipelines. Once you’ve done that, you can use it across all projects in your organization.

Please share your feedback and let me know if it worked for you or you want to discuss things for advanced scenarios. Happy building!