In this blog post, I’ll tell you about our experience with it and mention a few caveats.

Before

As an agency, we work with different clients. The mobile apps we build are not only distributed internally but also to the clients and their testers. Oftentimes we also coordinate their App Store releases.
Behind the scenes, there are quite a few certificates and provisioning profiles to juggle.

Traditionally, we’ve used Jenkins and App Center / HockeyApp to build and distribute our apps.
For iOS, our CI/CD workflow consisted mostly of Fastlane or build scripts, triggered by Jenkins on a dedicated machine.

Pain points

• Fastlane Match was used to sync certificates and profiles across the team. Configuring it for new projects was quite a time-consuming ordeal. Maybe we were just missing internal documentation for it. The few of us who had worked with it before couldn’t remember all the details of how to set it up consistently. Our Fastfiles were outdated and in need of a revision to follow current best practices.
• Build scripts are harder to maintain than Fastlane and are also harder to reason about, at least to someone new to them. Using this approach, certificates and profiles still had to be moved around manually.
  The huge raw build log isn’t fun to inspect. A syntax highlighting plugin could certainly improve that, but we didn’t look for one.

We had a meeting to discuss the state of affairs in our iOS CI/CD workflow and propose alternatives. Some of us had heard of Xcode Server before but hadn’t played with it yet.
The two main action items from that meeting were:

• Use a dedicated Apple ID for all CI/CD tasks.
• Try out Xcode Server.

The Road to Xcode Server

Apple added support for automatic signing to Xcode Server in 2017 and bought BuddyBuild sometime after.
Automatic code signing and device provisioning was the main selling point for us. On top of that, Xcode Server gives you a nice user interface.
It also has an API that allows integrating it with our own tools and processes, shall we ever need it.
Xcode Server features a web interface with simplified reports and the possibility to download the build artefacts — .xcarchive and .ipa files. Using the web interface, other team members can trigger builds without needing Xcode on their machine.
Conceptually, Xcode Server bots are similar to Jenkins jobs and integrations similar to Jenkins builds.

We were convinced. Time to get our hands on it!

Configuration

I’ll keep it short as there are already several resources out there with instructions on how to set it up.

• You need to activate it under Xcode > Preferences > Server & Bots on the machine where your CI/CD is.

• Each developer shall add an Xcode Server account to their own Xcode, in order to create and configure bots, trigger integrations and see the results. Bots are saved on the machine with Xcode Server.
• You can easily add pre-integration and post-integration scripts to carry out the tasks required by your project.
  An example of a pre-integration script could be running pod install, if your project uses CocoaPods.
  Post-integration script examples: uploading to App Store Connect / TestFlight (using altool) and posting the integration results to Slack.

If you’ve never configured Xcode Server before, you might want to check out a recent tutorial by Adam Rush on raywenderlich.com.

Caveats

Xcode upgrades

After upgrading Xcode to a newer version, Xcode Server also needs to be upgraded before new integrations are run.
Besides that, a bot can be configured to perform a test integration after each upgrade, to isolate any upgrades which might break an integration. However, before enabling this, you might want to check if the integration won’t have unintended consequences, such as uploading a new build to the client’s App Store Connect.

Building from a specific git branch

If you schedule an integration to run after new commits appear on a remote repository, it should run on the same branch you have checked out locally. However, this behaviour has changed between Xcode versions. You could add a pre-integration script with git checkout your-target-branch to prevent building from an unexpected branch.

Exporting to App Store Connect

You’ll need to provide a custom export options plist with method set as app-store. It’s one of the export options in the build configuration, inside Actions > Archive.
This is all you need if you have the necessary permissions to sign the app and automatic signing is enabled for this bot.
Example ExportOptions.plist for automatic signing:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>method</key>
    <string>app-store</string>
    <key>uploadSymbols</key>
    <true/>
</dict>
</plist>

The option to upload symbols can also be configured, as included in the example.

Code signing and provisioning

If you’re migrating an existing project and would like to take advantage of Xcode Server’s automatic code signing, you’ll need to ensure its build settings contain:

• A Code Signing Identity for automatic signing (e.g. iOS Developer or Apple Developer)
• Automatic Code Signing Style
• Automatic Provisioning Profile

In case you must use manual code signing and device provisioning: in the custom export options plist you’ll need to define the signing style as manual and specify the team id, signing certificate, and provisioning profile. You can then upload both the certificate and the profile from your machine to Xcode Server, all via the bot configuration pane.

Final Remarks

The experiment with Xcode Server went quite well. A few of us have already successfully migrated projects to it!

Xcode Server isn’t as widely used as Fastlane and Jenkins, therefore there are fewer ready-made integrations with other services. Luckily, the tasks we currently need can be carried out by relatively simple post-integration scripts.
Depending on your requirements, you might also have to write a few scripts 🙀. The good news is you can write them in Swift! 😎
Alternatively, Fastlane could also be used for the post-integration part of the process, leaving code signing, device provisioning, and app export to Xcode Server.

Considering our workflow, using both Jenkins and Xcode Server — although possible — would be redundant. Thus, we’re slowly transitioning away from Jenkins for iOS apps.
The downside is that we don’t have a central place to monitor the CI and CD for both our Android and iOS apps anymore.

Updating the existing tools and writing good documentation would probably have yielded similar results. However, when we met to discuss improvements to our iOS CI and CD, most of us seemed interested in checking out Xcode Server. After all, who doesn’t enjoy the opportunity to experiment with a promising tool?

We’re excited about the future of Xcode Server!

Further reading

These resources have been useful during the process.

• Apple’s documentation
• Xcode Server Environment Variable Reference
• XCBlog
• Honza Dvorsky’s 2015 write-ups

This article was written in December 2020.

A Tale of Xcode Server was originally published in Karlmax Berlin on Medium, where people are continuing the conversation by highlighting and responding to this story.