Built.io Blog

How to Set Up Customized Jenkins for iOS

,

Today we will learn how to setup a Continuous Integration (CI) environment for iOS projects using Jenkins. I will show you how to configure Jenkins to set up Xcode and deploy the build files to a WebServer so that they can be installed Over the Air within a Jenkins build job.

Hardware

The CI environment we will be using in this tutorial runs on dedicated hardware. We will be using a Mac Mini running OS X Mavericks (version 10.9.5). We have also created an OS X user named “jenkins”. This user is the only one on the system and the system is not used for other purposes. SSH and Screen Sharing have been enabled for this user. I am not going to cover running Jenkins as a daemon, as it causes issues with the Xcode toolchain, code-signing, and more, so I don’t recommend it.

Setting Up Jenkins

Instead of downloading the Jenkins Package from the Jenkins website, we use an OS X package manager named Homebrew to install it. This is because we don't want a headless server, and it allows us to login to the server, when required, for configuring Jenkins. Lets begin with the actual setup:

  • Install JENKINS and WGET using HomeBrew.
    $ brew install jenkins
    $ brew install wget
    	

Jenkins should always run, even after a system restart.

  • To launch, start jenkins at login:
    mkdir -p ~/Library/LaunchAgents
     ln -sfv /usr/local/opt/jenkins/*.plist ~/Library/LaunchAgents
    	
  • To load jenkins now:
    launchctl load ~/Library/LaunchAgents/homebrew.mxcl.jenkins.plist
    	

After restarting the system, the user "jenkins" is logged in automatically. Login by going to System Preferences → Users & Groups → Login Options → Automatic login and select the user `jenkins from the drop-down list.

Once everything is setup, VNC into the Jenkins Server and open http://localhost:8080 on your local machine. You should see the Jenkins page. If you type the IP address of the Jenkins Server and the Page doesn’t load then enable access from all IP addresses by editing the following file /usr/local/Cellar/jenkins/1.575/homebrew.mxcl.jenkins.plist and change the value to httpListenAddress=0.0.0.0.

Installing the Required Plugins

Most of the necessary plugins come with the default installation but we will need to add the following plugins and custom tools.

  1. XCode Integration Plugin
  2. Jenkins Mailer Plugin
  3. Email Extension Plugin
  4. Environment Injector Plugin

Custom Tool

  1. PROJMODIFY: A command line utility that helps in modifying the Xcode Project file. This is used for setting up the Code Signing Identity and Provisioning Profile. You can download it here.
  2. IPA2OTA: A command line utility that generates manifest.plist files and index.html files which can be used for Over the Air Installation of iOS apps. Download it here.

Setting up your first Jenkins iOS job

  1. Create a new Jenkins job. Lets call it "test-ios-app." Avoid having spaces in job name. Then select “Build a free-style software project” as your job type.
  2. Setup your "Source Code Management."
    1. Setup Subversion Repository URL.
    2. Setup Checkout strategy to “Emulate Clean Checkout.”
  3. Under Build Environment, check Inject Environment Variables and add the following Variables:
    PROJECT_DIR_NAME=test-ios-app-dir
     PROJECT_NAME=test-ios-app
     IPA_PATH=${WORKSPACE}/ipa-dir/${PROJECT_DIR_NAME}-${BUILD_ID}.ipa
     PROJFILENAME=${WORKSPACE}/${PROJECT_NAME}.xcodeproj
     TARGET=${PROJECT_NAME}
     PROVPROFILE_UUID=<<GET IT FROM PROVISIONING PROFILE>>
     INFOPLIST_FILE=${WORKSPACE}/${PROJECT_NAME}/${PROJECT_NAME}-Info.plist
    	
  4. Under Execute Shell add the following commands:
    projmodify ${PROJFILENAME} ${TARGET} "iPhone Distribution: COMPANY NAME REGISTERED ON APPLE DEV PORTAL" ${PROVPROFILE_UUID}
     /usr/libexec/PlistBuddy -c "Set :CFBundleVersion ${BUILD_NUMBER}" "${INFOPLIST_FILE}"
    	
  5. Jenkins-Xcode1.pngJenkins-Email.png 
  6. Click on “Add build step“. Select “Xcode” from the drop down menu and set the parameters as show in the below image: Since we are already Editing the Project File with our Custom Ruby Script we will not be using “Unlock Keychain.” We are also setting up CFBundleVersion via the above shell command, so we don’t need to set it again by using “Versioning” provided by the XCode Plugin.
  7. Again, “Add build step“ and select "Execute Shell" and add the following commands to be executed in the following sequence:
    mkdir -p ${WEBSERVER_LOCAL_PATH}/${PROJECT_DIR_NAME}/ cd ./ipa-dir ipa2ota ${IPA_PATH} ${WEBSERVER_URL}/${PROJECT_DIR_NAME} >index${BUILD_ID}.html cp ./${PROJECT_DIR_NAME}-${BUILD_ID}.plist ${WEBSERVER_LOCAL_PATH}/${PROJECT_DIR_NAME}/ cp ./${PROJECT_DIR_NAME}-${BUILD_ID}.ipa ${WEBSERVER_LOCAL_PATH}/${PROJECT_DIR_NAME}/ cp ./index${BUILD_ID}.html ${WEBSERVER_LOCAL_PATH}/${PROJECT_DIR_NAME}/
        
    	
  8. The above command will create the required files needed for Over the Air Installation of an iPhone Application and copy it to your Webserver Documents directory.
  9. The final step is to setup email notifications. We can do this by adding a “Post-Build Action” and selecting “Editable Email Notification." We can use this plugins to send emails when the build is successful. In the editable email notification, click on Advanced Settings, click on Triggers and Select Success, then click on Advanced, and enter the recipient's email address. Under the content field, add the following to create the body of the email.
The OTA installation is available at:
${WEBSERVER_URL}/${PROJECT_DIR_NAME}/index${BUILD_ID}.html
IPA is available at:
{WEBSERVER_URL}/${PROJECT_DIR_NAME}/${PROJECT_DIR_NAME}-${BUILD_ID}.ipa

Jenkins-Email.png

The email configuration should look something similar to the image below:

Now you can automate your build development and testing to easily distribute OTA builds whenever they're ready for testing.

Subscribe to our blog