CICD Automation using Unity CLI for publishing Android App
Unity is a widely used game development engine and is preferred by many for developing games for various platforms.
This article contains the following sections:
- Introduction
- Prerequisites
- Step 1: Build and Test on your local server using command line
- Step 2: Build, Test and Publish using a CI/CD tool
- Conclusion
- References
Introduction
In this article, we will see how we can build and test our android project in an automated way by using unity commands through the command line and publish it to the App Center. While in this article we’ll be using screenshots of Jenkins pipeline in the steps for reference, you may choose to use any other CI/CD tools of your choice as the approach will remain the same for all tools.
The commands that we are going to use are provided by Unity Technologies and can be accessed using the Unity command line Documentation.
The article is divided into two main parts. In the first part, we will build the apk locally using command line utility and in the second part we will see how we can use DevOps tools to build, test and deploy the same project.
Prerequisites
- Unity Hub installed on a local machine with an active license. Unity hub can be downloaded from it’s official website.
- Unity version should be the same as that of the project version installed with the required Target’s support. Example — Android SDK and NDK should be installed and configured if building an apk file.
- App Center account. You can create one for free if you don’t have it.
Step 1: Build and Test on your local server using command line
- Create an execute method file:
In order to build a project through the command line, an execute method is required. This execute method is invoked first which will build the scenes listed in the execute method one after the other.
Following is a sample execute method to include in your project which defines three scenes, the location of the output file and the platform target (Android in this case):
using UnityEditor;
class AndroidBuilder
{
static void ProductionBuild()
{
BuildPlayerOptions buildPlayerOptions = new BuildPlayerOptions();
buildPlayerOptions.scenes = new[] { "Assets/Scenes/Scene1.unity", "Assets/Scenes/Scene2.unity", "Assets/Scenes/Scene3.unity" };
buildPlayerOptions.locationPathName = "/builds/OutputApkName.apk";
buildPlayerOptions.target = BuildTarget.Android;
buildPlayerOptions.options = BuildOptions.None;
BuildPipeline.BuildPlayer(buildPlayerOptions);
}
}- Next, you need to commit this file in your repo. You may create the following directory structure to save the file as AndroidBuilder.cs in your project:
Assets/Editor/Builder/AndroidBuilder.cs- Open the command prompt and change the directory to the folder that contains Unity.exe for your project version:
cd C:\Program Files\Unity\Hub\Editor\<EditorVersion>\Editor- Run the build command with the following arguments:
Unity.exe -batchmode -quit -projectPath “<path to your project>” -buildTarget Android -executeMethod AndroidBuilder.ProductionBuild -logfile “<path to your project>/logfileName.log”- Quick peek into what these arguments are:
-batchmode: Executes Unity in background.
-quit: Exits Unity once the command execution has been completed.
-projectPath: Path to the project.
-buildTarget: Target platform such as Android/WebGL/iOS.
-logfile: Creates a build log file in the mentioned directory. - Run unit tests using the following command:
Unity.exe -batchmode -quit -runTests -testPlatform editmode -projectPath “<path to your project>” -testResults “<Output folder for test file>\TestResults.xml”-runTests and -testPlatform are two arguments specific to running unit tests. Tests can be run in either ‘playmode’ or ‘editmode’.
Step 2: Build, Test and Publish using a CI/CD tool
Now that we understand how we can build Unity projects through commands, we can make use of a DevOps tool to continuously build the code and distribute it to the testers and then finally to the Production environment without having to manually build it each time.
Let’s look at the steps required to configure an end-to-end system of publishing your app. We have used screenshots of Jenkins pipeline here, but the approach will be the same for other tools as well.
Following image shows the flow of steps to publish the apk file to Visual Center. The Developer will commit their code in the git repository. The build pipeline will be connected to the git repository and will build and test the code and output the apk as build artifact. The release pipeline will fetch the build artifact and publish it to the distribution group for the respective environment.
Build Steps:
- Create a new build pipeline. I have selected the Freestyle project in Jenkins.
- Link your code repository to the pipeline. If your code is on a local machine, you will have to first push it to a code repository such as Git and use the repo link to connect to the pipeline.
- Configure the pipeline for build triggers.
You can set up build triggers from the options available as per your requirement. Select ‘GitHub hook trigger for GITScm polling’ if you wish to enable Continuous Integration.
- Add a task/step for running command line script and input the build command. Note that in the screenshot below, I have used “%WORKSPACE%” which is a predefined variable for the working directory. You will have to change and use the predefined workspace variable for the tool that you are using.
- Add another command line task/step for running the test command.
- Add a task to Publish the build artifacts. Pass the path of the build output directory in the path to publish. In Jenkins, you can add a Post-Build Action to archive the artifacts.
Release Steps:
- Create a new Release pipeline and link the build artifacts to the release pipeline.
The release pipeline should be able to fetch the build output file. Here, I am using Azure DevOps to create my CD pipeline. I have linked my Jenkins server to Azure DevOps using a service connection on Azure DevOps and using that linked my Jenkins build pipeline output as artifacts in Azure DevOps release pipeline.
- Install the required plugin/task for VS App Center.
Before publishing to App Center, you will have to first install the required task/plugin for VS App Center and create a connection between your App Center application and your Deployment tool (in this case Azure DevOps pipeline). You will need the Server URL and API app token for this. API tokens can be created using the steps provided here. - Create a new stage for Dev and add a Visual Studio App Center task.
Fill in the details of your app such as the owner name/username, version, release notes and distribution group details
- You can create similar release stages for Test, Stage and Prod environments.
For Production, you will have to add an additional step to sign and align the apk. There are readily available tasks for Android Signing which you can use to Sign your app before you publish it. You can configure your app Center to connect to the Play Store and Publish to the store from your pipeline.
Additionally, you can setup CI/CD, Pull request, scheduled triggers as per your requirement on the build and release pipelines to implement Continuous Integration, Delivery and Deployment. This will ensure that your changes are tested and deployed more frequently.
Conclusion
We saw how by setting up a build and release pipeline for our Unity project we can continuously publish new releases to a distribution list such as App Center without the hassle of building and distributing it manually over and over again. You may use a different CI and CD tool like we have done here or just use a single tool for both. Jenkins as a build tool does the job perfectly and Azure DevOps provides an excellent multi stage release functionality with release pre deployment approvals which makes it easy to deploy to multiple environments.
References
Good to read:
