Jenkins Android – Git, Gradle, TestFlight



If you are new to Continuous integration for multiple mobile platforms then you are in the right place. This article will explain how to setup a fully automated continuous integration environment. To do this we will use the following:

The life cycle of a build will look like this:

  1. Developer commits and pushes their changes to the Repo
  2. Jenkins Android Server Job monitors Git Repo and triggers a build on the developer commit
  3. Jenkins Android Server Job executes the Gradle Build Scripts checked in to the Repo
  4. Jenkins Android Server Uploads completed build to TestFlight
  5. An email is sent out if there is a build failure

Note: This is a tutorial that details how to setup, configure and run Continuous Integration environment using Jenkins. The Jenkins Android Server was setup on OSX environment to allow for Android and iOS builds. However, Jenkins is build on the Java Run-time so it is portable across platforms.

As you can tell by the workflow above, Jenkins is pretty much the orchestrator of this process. Jenkins essentially replaces the developers duties of building, checking for errors, running unit/functional/integration tests and publishes those builds out to the business or end users. Hence, the name Jenkins.

So lets get started:

Get Jenkins Android Installed on a Server Environment

Some quick prerequisites:

  • Ensure Android SDK is installed and your Environment variable are configured for Jenkins. More info here

Step 1: Download Jenkins Server.

Windows or Mac

if you are downloading for windows just note that you will not be able to perform iOS builds.

Step 2: Install Jenkins Android

As noted before Jenkins is built on the Java Run-time. You will need to install the Java Runtime if your system doesn’t already have it installed.

Jenkins will install a daemon (on a Mac) or service (on windows) that will allow it to run on its own, whether someone is logged in or not. Jenkins installer will create a user called Jenkins. It is recommend that you follow these setup to ensure the Jenkins user is correctly configured and the reminding of the setup goes smoothly.

  1. After installing Jenkins Android go to into system preferences –> Group and Users.
  2. Unlock the panel. Give the “Blank” user a full name so you recognize them.
  3. Change the password to something you know.
  4. Grant the user admin rights. Here is a how-to grant admin rights tutorial.
  5. Log off the current user and log in using Jenkins User and finish this tutorial while logged in with Jenkins user.

Setup 3: Open the dashboard

You will setup and manage Jenkins Android using a browser that points to a website URL. Typically it will be accessible via http://localhost:8080 while you are on the machine Jenkins is installed.

Jenkins Android Dashboard

Get Jenkins Setup

Jenkins Android Management Screen

Jenkins out of the box is fairly vanilla. This is good since it allows for it to be customized. Customization comes in the form of Plugins. For this tutorial, we are going to need the following Plugins:

  • Git Plugin: This will allow Jenkins Android to Monitor and pull code from our git repositories that will in turn trigger the build.
  • Gradle Plugin: This plugin make it possible to invoke Android Gradle build scripts.
  • TestFlight Plugin This will streamline the post build upload process for submitting your APK files to TestFlight.
  • Xcode Plugin: This plugin allows Jenkins to call Xcode command line tools. This is only usable if Jenkins is install on OSX

Setting up the server

Configuring Jenkins

Most of the default setting in the root Dashboard –> Manage Jenkins –> Configure System section is sufficient to get started. However, some build setups, such as the Gradle Build, relay on Environment variables. This can be setup system wide so it is available during job execution. So you will need to ensure Jenkins execution context has any necessary environment variables set, like $ANDROID_HOME. This Stackoverflow answer touches on some good options for setting this up

Create a Jenkins Job

This is usually done after everything has been setup. For the purposes of this tutorial, we will have an initial job setup in advance.

Create Jenkins Android Job

Select New Job –> Enter a Job Name –> Select Build a free-style software project

This will give use vanilla Jenkins job that we can customize our CI process with our desired plugins.

Manage Jenkins Android Job

Using the Git Plugin

In order to use the Git Plugin, your build server needs to have Git installed. For Mac, this comes installed along with XCode. If not, you should: Open terminal –> Execute command xcode-select --install

For Windows you can download and install Git from here.

Step 1: Install and Enable Git Plugin

At the Root of the Jenkins website Select Manage Jenkins –> Select Manage Plugins

Jenkins Android Manage Plugin

Select the Available Tab, Type Git in the search, Check the box and install/restart Jenkins.

Step 2: Setup Source Control Management Settings

The purpose of this setup is to perform a git Clone command on your configured Repository and the designated branch. This will pull down the latest commit locally so the build can be Invoked.

Using the Job that was created earlier we will configure it’s Source Control Management section to use Git. Starting at the Jenkins Dashboard you should see you list of Jobs created. Click on Android Job –> Then click on Configure on the left pane menu.

Jenkins Source Control Management

The 2.0 Version of this plugin seems to fail setting credentials on a mac. You might see this error when setting up could not lock config file .git/config. I used the 1.5 version over the 2.0 because of this BUG. You can find the git plugin version 1.5 here.

The 1.5 version of the Git Plugin doesn’t support credentials (only SSH). So it order to get this to work with a username and password I needed to pass the credentials via URL like this:

At this point, if you execute your job then Jenkins should perform a fetch against your configured Git repository and clone the project files into the job’s workplace (which should be: {Jenkins Home Folder}/jobs/<Your Job Name>).

So, give it a try.

Step 3: Add and Setup SCM Polling

In the Build Triggers section of the Job Configuration screen you will be able define the polling Interval. These configuration accepts cron syntax to define the polling schedule.

Simply Check the Poll SCM check box and define your cron schedule. Below illustrates a 5 min polling (this is too often of a schedule to run all the time but for tutorial and testing purposes it is acceptable).

Jenkins Git Polling Trigger

Ideally, I would like to use a Git Hook to push a trigger to Jenkins but unfortunately I am using TFS with a Git bridge interface that doesn’t support Git hooks. So, I am subjected to polling for changes.

If you would like for information about setting up a Git Hook to trigger Jenkins builds Kohsuke Kawaguchi wrote a great post on this.

At this point, if you do a commit to your repository Jenkins will identify the change execute the Job.

Go ahead, give it a try.

Step 4: Add and Setup Build Step – Android Job

There is where the magic comes in.

In the Build section of the Job we are using the Gradle Plugin we downloaded for Jenkins. This allows Jenkins to execute a build that has been scripted out using Gradle.

Jenkins Configuration Build Section

Setting your android project and creating the necessary Gradle build scripts is outside the scope of this discussion. Gradle build can be execute independently of Jenkins. This is a good tutorial I wrote on how to setup and write a Gradle build for Android.

My project includes the Gradle wrapper, which is pull from the repository in the SCM setup. The Gradle Plugin knows how to execute the Gradle build via the wrapper and knows where to look for the Gradle build script based on checking the From Root Build Script Dir box.

In the above screenshot, I am executing two Gradle build tasks. Clean, which cleans the old build, and Assembile, which compiles and assembles the Android APK.

To lessen your pain in troubleshooting the build task, ensure successfully build your project with this command on the root of your project (MAC): ./gradlew assembile

Step 5: Add and Setup Post Build Step – Jenkins Android TestFlight Upload

TestFlight is a great way to distribute beta and internal applications. I have used it with great success. Likely, there is a Jenkins TestFlight Plugin to assist in uploading your automated builds.

Once you have created a TestFlight account the configuration is simple. Navigate to the TestFlight API Doc page and get your API_Token and your Team_Token.

You token pair needs to be setup in: Jenkins Dashboard –> Configure System –> Scroll to TestFlight section, Enter your tokens and Click Save.

Back to the Jenkins Android job. All you need to do is Select your Token pair setup previously and enter your .APK file location (relative to your job’s workspace folder). Additionally, you can setup a distribution list on TestFlight for sending out notifications via Jenkins upload. After you setup a distribution list on TestFlight, supply that name in the advanced section of the Jenkins Plugin. Now you have email notifications via TestFlight.

Posted in Android, Continuous Integration, Mobile and tagged , , , , , .