Introduction with Jenkins iOS
If you are new to continuous integration for 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:
- Jenkins: Our Continious integration server application
- Git: Our code repository,
- TestFlight: Our mobile testing distribution platform and each popular mobile platform
- XcodeBuild: The build tool for iOS
The life cycle of a build will look like this:
- Developer commits and pushes their changes to the Repo
- Jenkins iOS Server Job monitors Git Repo and triggers a build on the developer commit
- Jenkins iOS Server Job executes the Build Scripts (XcodeBuild) checked in to the Repo
- Jenkins iOS Server Uploads completed build to TestFlight
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.
Get Jenkins Installed on a Server Environment
Step 1: Download Jenkins Server.
Step 2: Install Jenkins
As noted before Jenkins is build on the Java Run-time. You will need to install the Java Runtime if your system doesn’t already have it installed.
Jenkins iOS will install a daemon that will allow it to run on it 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:
- After installing Jenkins go to into system preferences –> Group and Users.
- Unlock the panel. Give the “Blank” user a full name so you recognize them.
- Change the password to something you know.
- Grant the user admin rights. Here is a how-to grant admin rights tutorial.
- Log off the current user and log in using Jenkins. Finish this tutorial while logged in with Jenkins user.
Setup 3: Open the dashboard
You will setup and manage Jenkins iOS 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 iOS is installed.
Get Jenkins iOS Setup
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 to Monitor and pull code from our git repositories that will in turn trigger the build.
- TestFlight Plugin: This will streamline the post build upload process for submitting your ipa files to TestFlight.
- Xcode Plugin: This plugin allows Jenkins to call Xcode command line tools.
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 routines, such as the xcodebuild, relay on xcode being installed. So you will need to ensure Jenkins execution context has any necessary environment setup.
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.
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.
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
Step 1: Install and Enable Git Plugin
At the Root of the Jenkins website Select Manage Jenkins –> Select Manage Plugins
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 iOS Job –> Then click on Configure on the left pane menu.
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:https://username:password@github.com/you/example.git
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).
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 – iOS Job
This assumes your build environment has xcode, xcodebuild tools, provisioning profiles and necessary certifications installed.
The shell script I have written below performs a clean, run a build, create an signed archive and an exported ipa for adhoc deployments.
Navigate in finder or terminal to your job’s workspace (something like ~/jobs/{your Job Name}/workplace.
Create a file called iOS_Build.sh
Copy the script below into your newly create iOS_Build.sh file while replacing your project specific information (PROVISIONING_PROFILE, CODE_SIGN_IDENTITY, exportProvisioningProfile name and an appropriate name for your xcarchive/ipa files)
Create the following directories ./JenkinsBuild, ./JenkinsArchiveand./JenkinsIPAExport`.
xcodebuild -alltargets clean
rm -rf "./JenkinsBuild/*"
xcodebuild -target HelloJenkins PROVISIONING_PROFILE="00000000-0000-0000-0000-000000000000" CONFIGURATION_BUILD_DIR=JenkinsBuild
rm -rf "./JenkinsArchive/*"
xcodebuild -scheme HelloJenkins archive PROVISIONING_PROFILE="00000000-0000-0000-0000-000000000000" CODE_SIGN_IDENTITY="iPhone Developer: Justin Hyland (XXXXXXXXXX)" -archivePath ./JenkinsArchive/HelloJenkins.xcarchive
rm -rf "./JenkinsIPAExport/*"
xcodebuild -exportArchive -exportFormat IPA -exportProvisioningProfile iOS\ Team\ Provisioning\ Profile:\ com.yourAPP.HelloJenkins -archivePath ./JenkinsArchive/HelloJenkins.xcarchive -exportPath ./JenkinsIPAExport/HelloJenkins.ipaIf you get this error error: can‘t exec ‘/Developer/usr/bin/xcodebuild‘ (No such file or directory) you many need to run the following command in the terminal:
sudo xcode-select -switch /Applications/Xcode.app/Contents/DeveloperExecute this script via terminal while in your job’s workspace directory: sh iOS_Build.sh
I would recommend running each xcodebuild command one at a time to help ease any troubleshooting required.
If you where prompted for a password during the code signing/archiving command then you will need to change your certificate’saccess control settings.
Open Keychain Access
Click System and My Certificates in the left hand side of the window and Click the lock to unlock the system keychain.
Expand your iOS certificate to expose your private key and Double Click the key.
Click Access Control tab and ensure Allow all applications to access this item is selected.
Click Save Changes
If you where prompted for a password during the build script execution, try it again to make sure you are not required to enter a password.
Once your build is successfully simply add a new Execute Shell command build step in Jenkins and enter sh iOS_Build.shand your done.
Step 5: Add and Setup Post Build Step – Jenkins iOS 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 Plugin to upload your automated builds.
Once you have created a TestFlight account the configuration is simple. Navigate to the TestFlight API Doc page and get yourAPI_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 iOS job. All you need to do is Select your Token pair setup previously and enter your .ipa 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.