Jascha Grübel

So you want to build your Unity project on a private jenkins for iOS and Android?

This is a question that recently haunted me. Previously, at the Game Technology Center (GTC) at ETH Zürich, I was privileged enough to sit on a deployed pipeline. It creaks sometimes but in general, it works well. For a new project with Future Health Technologies at the Singapore ETH Center, there was no such luck. But given my experience, I was asked to set up a similar pipeline. Luckily, the GTC gave me a copy of a project I recently worked on as a starting point.

We want to deploy new versions of the software for testing to android devices with firebase and to iOS devices with Testflight. We also want to collect meta data with firebase. We also want to create backups of the versions.

I tried to look up all I needed for it but it was often difficult to piece things together, so here, without further ado you get a step by step instruction how to setup jenkins for unity.

The hardware and software (preparation)

To build for iOS, macOS is required. The only choice really becomes a Mac Mini. It is not as expensive as a Mac Pro (but I haven’t tried the new Mac Studio). My Mac Mini is in a private network and VPN is required to access it. I install the necessary software (explained in more detail later) including:

Once all is installed and you can access jenkins, it is time to setup our project for jenkins.

Since our production server is automatically restarted every once in a while, we add Launch Agent for jenkins.

Getting jenkins ready

We need to create a pipeline project in jenkins and we need to have the following plugins installed

  • git
  • xcode
  • gitlab
  • emailext (note that gmail may require you to disable safety so run it on a throw-away account and if you have money get an email automation account)

We need to setup the gitlab id for the authentication token as a global credential.

Also, set environmental variables for language to be UTF-8, so that the pod creation with cocoapod uses that. Otherwise xcode will not compile

Getting apple developer ready

Create identifier for your project in apple developer with the endings dev for the development branch, tf for the Testflight and public for the release.

Getting firebase ready

Setup identifiers for your project for dev, tf, public and no ending for the public android release. Make dev for both iOS and Android to check local builds.

Getting Unity ready

Make sure that Unity > Preferences > External tools > XCode Settings has the automatically signing and team ID set.

Getting the unity project ready

Hopefully, your project is on some kind of version control (I use git). If not it is time to get it on version control and for this tutorial I’ll use git but you can figure out how to use another version control with a bit of fiddling around.

We need to organize the build pipeline for jenkins and it is best to separate the processing infrastructure from the project itself. So first, we place the unity project into a folder in our version control called unity-project in the root of the repository. We also place our jenkins-files at the root – one for android and one for iOS.

To ease the processing of the project, we need a few helper scripts both for the pipeline in jenkins as bash scripts and within unity to manage the building process. There are complex interactions ongoing during building and while many production environments require iterative builds on the change in version control, I opt for a clean slate each time which is reasonable for small projects. Note that in large project that can take hours to days and cannot be done. The bash scripts provide the cleaning of the workspace as well as triggering the batch building in Unity for iOS and Android. Batch building in Unity uses a function that the user needs to provide. So I add a build script to the project. Lastly, while not strictly necessary, we also add build information into the project using the hash of the commit in the repository and the build number to display a unique version number automatically.

jenkins file

While there are some specific differences between iOS and Android, most of the files stays the same. Yes this could be joined but I leave that for another time.

  • The work space is cleaned up using the bash script.
  • The repository is cloned.
  • The build number is inserted.
  • The build is created.
  • The backup is stored.
  • The build is deployed to Firebase/Testflight.

Unity Firebase integration

Setup firebase unity sdk.

Unity build settings

Use iOS.Resolver to switch to cocoapods

Hacky solution that needs better fix: open unity project in workspace and call “sudo gem install cocoapods”.

XCode settings

You need to build and submit your project once from the mac mini to apple connect or otherwise the automated submission will fail. XCode will ask you several times to access the keychain and you need to use “Always Allow” so that the automated setup can sign your project. This is not written anywhere and I only got this golden nugget of knowledge from Fabio Zünd (thanks again!).