Jenkins setup for Android on Mac OS

Jenkins is one of the best CI tools available on the market — it is free, it has a solid history and dozens of plugins. The only tricky part here is to set it up correctly. I’ll cover Jenkins installation on Mac OS.

Install via .pkg

Jenkins can be found on the official site in the .pkg format. Right after the installation, you will see localhost:8080 page opened in your browser with Jenkins running. This page offers to set up account for secure CI access.

Basic environment set up

You need to be aware of the fact new Jenkins’ user has been created (/Users/Shared/Jenkins) by default. Assuming the fact — keep in mind that all files and variables declared under default user will not be visible for Jenkins.

To make your Android SDK visible for Jenkins it needs to be installed in one of the shared folders like /usr or /opt.

Download the stand-alone Android SDK from the developers site and put it under /opt/android-sdk. If you don’t have an ‘opt’ folder, create it by running:

sudo mkdir /opt

As soon as the sdk is downloaded, run /opt/android-sdk/tools/android in the terminal to open the SDK manager where you can pre-install all packages and android versions required for CI to run your project.

After, check if environment variables are visible to Jenkins’ user. To do this log in as Jenkins’ user using:

sudo su jenkins

Now check visibility of your environment variables like ANDROID_HOME, JENKINS_HOME, ANDROID_SDK_HOME.


If they are not visible create them globally, editing /etc/profile:

export ANDROID_HOME=/opt/android-sdk

Lastly, make sure you can connect to your Git host using ssh connection:

ssh -T

If the connection is denied saying ‘Invalid keys’, check /Users/Shared/Jenkins/.ssh exists. If not create a folder and generate new SSH key for Jenkins. Link ssh key to your Git server. Here is a nice guide from Github how to generate and add SSH key.

Basic Jenkins set up

It is recommended to create a separate account on GitHub for CI. An account should have admin rights for a repository in order to create integration hook automatically. Check Jenkins’ configurations. There should be some fields connected with Android root, needs to be filled. Also, add credentials for preferred git server.

If you are using Github private repository also configure GitHub private token to use with Github API. Go to the GitHub settings and generate new token to access the repository. Then add it as Secret text authorization strategy to Jenkins. ID and description here are optional.

Finally, we have completed basic Jenkins set up and now can create a job for our project.

Basic job set up

We are creating freestyle-project. All fields there are pretty self-explained and click on the ‘?’ button will reveal quite good tips.

Here are some tricky things you can face during the job setup.

Source control management — if you selected Git and have ssh key set up, credentials can be empty. (set to none)

Branch — select a particular branch for this job or leave it empty. I would recommend not to leave it empty, but to specify patterns to build, like master, dev, feature/*, fix/* etc. This way you have more control. Or you can even create a separate job for release builds or daily builds.

Build triggers — Build when a change is pushed to Git. Also install and set up Pull Request Builder plugin to build on the pull request. Don’t forget to select the option to use git hooks for build triggering if it is available.

To make this option work your Jenkins should be available from the outside by URL. It can be used to integrate webhooks for Github or access our CI tool from the outer world.

Don’t forget to update Jenkins’ config and change public URL. It will allow Jenkins to create a correct link in, for example, email reports.

Build — the most simple way is to run shell script or invoke gradle script. As for me, it is more convenient to use ‘Terminal’ format and write several shell commands to execute.

Shell script — versatile tool to build the Android project


As soon as Jenkins going public we need to setup security and account system. During the first launch Jenkins already asked to create an admin account. If you want to create more with different access level welcome to the Configure Security menu.

Two steps are required:

  • Select Jenkins’ own user database -> tick Allow users to sign up.
  • Select Matrix-based security -> type account name and click Add.

After that, you can define access level for that account and also for an anonymous user.

Here we are! At this point you should have basic job for your Android project running. Push something to one of selected branches and observe build triggered on Jenkins.

Tips and tricks

1. Android project with submodules

If you have Android project with submodules, it requires additional configuration. In global Jenkins’ settings under Source Code Management select Additional behaviours -> Add -> Advanced submodules behaviour and tick Recursively update submodules. This option will allow to sync submodules before every build.

NOTE: There can be fetch problem when assembling build with submodules using GitHub pull request hook. If you use https:// reference to the repository use username password credentials, if you are using SSH reference such as git@ use SSH key. Mixed way can lead to problems. Check your submodule url as well.

2. Jenkins’ system logs

Use Jenkins’ logs extensively if something is going wrong. You can access them by going to Configure → System Logs → All Jenkins logs. There are a lot of useful information about errors. Details about each can be easily found on the stackoverflow. Generally, you are looking for logs like this:

Received POST for

If you see this line — it means hooks work. You can examine other logs for more details.

3. Ngrok tool

By default Jenkins runs on your local machine. To make it available from the outer world you need to deal with services like Heroku or AWS. If you want something really simple and fast here is a tool called ngrok available. Two steps installation allows to create a tunnel to your localhost and generate a secure public URL.


Of course, that’s just the most basic things you can do with Jenkins. Want to customise the behaviour to serve your needs? Check this github pull request builder, slack plugin, Google Play publisher plugin or just search for any other plugin you may need.

That’s it from my side. If you like the article recommend & share.