Um ein breiteres Publikum anzusprechen, ist dieser Post ausschließlich auf Englisch verfügbar.

So your organization finally decided to get a continuous integration system to improve the workflow and workload during the development process. While setting up a Xcode-job is usually quite simple, building CocoaPod-Projects with custom certificates and specific profiles is a bit tricky. This is just a quick walk-through outlining the necessary steps. If you have any questions or spot an error, reach out on twitter: @moritzhaarmann.

Make sure your project is set up correctly

Before we even touch anything in Jenkins, let’s make sure your project is ready to be built using Jenkins. There are two things we need to ensure in order for your project to work in Jenkins.

The first requirement is that the scheme used to build the project is shared, which basically means that it becomes a file in the project directory that you need to add to version control. To do that, Just click on the target (it’s on the upper left side, just left of the device selection) and select ‘Manage Schemes’. Once in that dialog, just tick ‘Shared’ next to your project’s scheme. There is no need to to share the CocoaPod-schemes here.

Manage Schemes: Tick the Shared-Checkbox

The next step is to make sure that all required dependencies and files are added to your source control system. This specifically means that the contents of the Pods-directory are added, as well as Podfile.lock and Podfile. And don’t you forget about the scheme we just marked as shared. You will find it below the xcodeproj-directory, somewhere in ./xcshareddata/xcschemes/.

Commit everything and push it to wherever your Jenkins has access to.

Install necessary Jenkins plugins

True, building a project using a collection of shell scripts is a perfectly viable solutions (if you’re into pain and unmaintainable software stacks). We chose a different route. Today, there are great plugins for Jenkins available that make it super easy to build IPAs.

The first one we will need is called Xcode Integration. Suprisingly, it’s the bridge between Xcode and Jenkins. Who would’ve guessed it from the name. The version we use in this guide is 1.4.2. Probably later versions will work as well.

Second comes Keychains and Provisioning Profiles Management. This is a rather new plugin that simplifies the management of, well, provisioning profiles and developer profiles for Jenkins massively – you can simply upload a keychain and matching provisioning profiles which will then be used to build your project.

Create a custom keychain for Jenkins

The plugin mentioned above allows us to upload keychains containing your Developer Certificate which will be used later to codesign your IPA. You could technically simply upload your normal login.keychain, but since this keychain also contains all of your other sensible data, it’s not a good idea to have that stored anywhere else but on your machine.

Creating a custom keychain is simple. Open the Keychain-Tool that comes with Mac OS and go to File -> New Keychain. Choose a strong password and put the file somewhere not too hidden. Desktop or something.

Switch again to your login or system keychain and just copy your developer identity to the newly created keychain. It’s just normal copy and paste. Once you’re done, open Jenkins in your browser, navigate to ‘Manage Jenkins’ and select ‘Keychains and Provisioning Profiles Management’. On top, there is a file upload field, just select the keychain you created and press upload.

Now that your keychain is stored, the password used to create the keychain must be provided, as well as your developer identity’s name. You can simply copy that from the keychain-utility: double-click on the certificate and select the part in Common Name. When finished, it should look something like the screenshot below.

Configuring the Keychain used for signing a project.

The next logical step is to upload the provisioning profile for your project. **Important: You need to set the provisioning profile path, if you installed jenkins using the provided installer this is /Users/Shared/Jenkins/Library/MobileDevice/Provisioning Profiles. **

Configure the job

With everything in place now, let’s get your job configured. Using the plugins provided, this is quite simple.

I assume you already set up a freeform project that grabs the sources from $someplace. What you need now is to tick the ‘Keychains and Code Signing Identities’-checkbox in the Build-Environment section. Make sure you check both Overwrite existing keychains and Delete copied keychains after build. Select the keychain you just created a minute ago and the provisioning profile you uploaded. The provisioning profile will be placed in the configured directory so that xcodebuild can find it.

The Build Enviroment setup

Next we need the Build phase for Xcode. Simply click on add build step and select Xcode. Step-by-step, this is what has to be set:

  • Enter the Target you’d like to build in the General build settings section. Expand the section and tick the “Pack application and build .ipa”-Checkbox.
  • Expand the Code signing.. section and make it look like this (**Note: The value in the password field is ${KEYCHAIN_PASSWORD}, a variable set by the Keychain-plugin. **): Code signing in Xcode build phase
  • This is for CocoaPods: Expand the Advanced Xcode build options and enter the the scheme name in Xcode schema name. Also, specify the Workspace file (no extensions here. If your workspace name is Project.xcworkspace, just enter Project.)

Now that Xcode is ready to go, let’s just create a quick and simple Post-build action that archives the .ipa and for later use or debugging. To do that, add a new post-build action ‘Archive the Artifacts’ and enter build/Debug-iphoneos/*.ipa, build/Debug-iphoneos/*.zip in Files to archive.

Just click on save and build your project. If everything is right, it should build an IPA now. Congratulations :). If not (Jenkins is somewhat difficult from time to time), reach out. We are also offering a setup package for Jenkins, if you need a more complex setup or don’t have time to do it yourself. In case you’re interested, just drop us a line and we’ll get in touch.