How to build and release a standalone Unity App using Travis CI, Docker and GitHub
By: Carlos Castro
Tags: Docker, Github, Continuous Delivery, Travis Ci, Unity

How to build and release a standalone Unity App using Travis CI, Docker and GitHub Carlos Castro Mar 30, 2019·7 min read

Recently I worked in an application called Mindsweeper that enables users to visualize their facebook data in 3D. The application was built using Unity and we found ourselves having a hard time trying to build and distribute the standalone application.

We found a good solution using Gabriel Le Breton’s unity3d-gitlab-ci-example repo to use Docker containers and GitHub to be able to build and distribute our releases, but even then it was not as straight forward as we thought.

I will go over on how to use Travis CI, GitHub and Docker containers to build and release your standalone Unity application. Based on Gabriel’s repo but also providing my personal experience to make the process as smooth as possible.

Setting Up The Repository

Create and populate your Github repository with your unity application. I’ll be using a simple application that only displays a panel.

Setting Up Travis CI

Now we’ll be setting up Travis CI for automated builds, Travis CI is a tool that help with continuous integration and continuous deployment (a.k.a CI/CD). Travis will handle our builds and will be releasing new version to Github on demand.

Go to the Github Marketplace and search for Travis CI

Set up a new plan, Travis offers free usage for open source projects. Once you have selected the plan for Travis, click on the “Install” button.

You can give Travis access to all your repositories or to specific ones, for this occasion i will only give it access to the example repo.

Once you’ve selected the “Install” button, you will be redirected to the Travis Dashboard, form here you have an overview of all the repositories Travis has access to. Select your unity project and it will take you to a more detail view of it. In this screen you can view all the builds of your application as well as the current state of the build, you can also set up environment variables for your project.

Getting the necessary elements

Before we can start using Travis, its necessary to get certain files that will be needed for the project to build correctly, they include the license for the unity build as well as the scripts the service will be running, the latest were created by Gabriel Le Breton and can be found in this repository unity3d-gitlab-ci-example.

Creating the license file

For this step you will need to have Docker installed, instructions on how to install can be found here.

Here you can find the instructions on how to get the license file. It’s very important you DON’T commit that file to GitHub.

Once you get the license file their contents need to be in an environment variable for Travis to use it, but since Travis does not accept multiple-lines env variables, the file needs to be encrypted by the Travis CLI. You can do so with the following command.

Once its finished you should have an output like this.

The script encrypts the license file and creates the encrypted output in a file with the extension .enc

If you go to your Travis CI dashboard, under “Settings” you should be able to see the new environment variables.

These are necessary for the file to be unencrypted.

Getting the scripts

You need to download the scripts under the “ci” folder and put that folder in your project’s root folder. These folder contains the scripts that will prepare the environment for the docker containers to run correctly as well as start said containers.

Gabriel’s repo also includes “local_build.sh” to be able to build locally, but this script does not involve the docker containers, it uses your local unity installation and therefore you can not build targets you don’t have installed. If you want to test the local build using containers just as travis would do it, you can find “local_build_.sh” in the repository for this example.

Getting the GitHub key

To be able to release to GitHub an API key is needed. You can go here to get yours.

Make sure you only check the repo checkboxes.

Once you get your key, go to your Travis dashboard and create a new environment variable called GITHUB_API_KEY.

Getting the Build Class

Finally you need to create a build class to tell Unity how to build you project. By default the build.sh script looks for one called BuildCommand and a method PerformBuild, but you can change it.

This class should be under Assets/Scripts/Editor.

Setting up the configuration file

Now that we have all the necessary files for our project to build the next part is to configure the configuration file, this file tells Travis how your project should be built or tested, where are your files and (in this case) what to do with your applications once they finish building.

Start by creating a file in the root of your repository called “.travis.yml”.

Configuration File

In this section of the file the language in which Travis will work is defined as well as environment variables such as the docker image and the final build name.

Before Install

In the configuration file section Travis decrypts the license file, then it will export the content to an environment variable called UNITY_LICENSE_CONTENT, for the openssl command on line 10 you will need to replace encrypted_xxxxxx with your Travis’ environment variables which you can get from the dashboard.

Jobs

This sections includes the building stage, this is where you tell Travis what and how to build your app. The build target is set as an environment variable, these correspond to unity build targets, supported build targets can be found here.

The output of the building stage will be compressed into a zip file for the deployment stage.

In the deploy stage GitHub is set as our deploy provider, will make use of the GITHUB_API_KEY environment variable. Notice the “tags” flag on line 30, this tells Travis that only tagged commits are deployed. For more documentation about deploying to GitHub click here.

Building with Travis

To trigger a build on travis you only need to push changes to the master branch of your repo, Travis will automatically detect it and will start building.

The current configuration file builds for StandaloneLinux64, StandaloneOSX, StandaloneWindows64 and WebGL.

When the build is finished you should be able to see the following output

But it still has not been deployed to GitHub, because in the configuration file we told Travis to only deploy on tag commits.

Release to GitHub

To be able to deploy your built project to GitHub, you need to create a tag commit in your repo. For more information about tag commits go here.

When your tagged commit is pushed to the master branch it will trigger a build on Travis, and when this is finished Travis will deploy the output files to the GitHub that you can then check on the releases section in your repository.

This repo with all the build scripts and files can be found here.

Gabriel Le Breton’s repo can be found here.

The Mindsweeper app can be found here.