Understanding Xcode Cloud, Apple's CI build service

Xcode Cloud is Apple's Continuous Integration build service for developers. Here's how to get started using it for your own software creations.

At WWDC 2021, Apple introduced its new cloud build service for its development IDE called Xcode Cloud.

Xcode Cloud is a continuous integration (CI) build service hosted on Apple's servers that allows development teams to collaborate and automate build and software packaging services for software configuration and builds.

The idea behind continuous integration is that a bot or set of bots monitors source code repositories for code changes, and then at specific intervals, it retrieves source code, builds software components automatically, and distributes them to stakeholders automatically.

Using CI, developers and companies can speed up build and distribution times by allowing other computers to manage the build process manually. With CI, gone are the days of developers having to spend time doing manual builds.

Think of CI as an automated Build Engineer - a bot that can manage all aspects of builds and distribution for you.

Requirements

To use Xcode Cloud you must meet the following requirements:

1. Be enrolled in the Apple Developer Program
2. Use Xcode 14.0.1 or later
3. Add your Apple ID in Xcode's settings
4. Have an app record for your app in App Store Connect
5. Connect Xcode Cloud to your online source code management system

Cost

Apple now provides 25 free compute hours for Xcode Cloud with each Apple developer account. Additional compute hours are available at 100, 250, and 1000 compute hours, ranging from $49.95 to $399.99 per month.

For more info, see the Xcode Cloud overview page.

Complexity

Be forewarned, using Xcode Cloud is not trivial. Apple has attempted to make it easy to get started with Xcode Could but those efforts were a failure.

Xcode Cloud is complex, and to fully understand how to use it you may need to read up to ten or more different sections of Apple's developer documentation - and Apple's developer documentation is already far too verbose and scattered.

You may find yourself jumping from one link to the next across Apple's Xcode Cloud developer pages, only to discover you've traversed the documentation so far that you forgot what topic you set out to understand.

App Store Connect is Apple's web portal where developers and teams manage team members, app setup, details, and collaboration between developers. For both App Store Connect and Xcode Cloud you'll need to have an Apple Developer Account and an Apple ID to sign in with.

There are account issues, team and permissions issues, source code management setup and configuration, and App Store Connect issues.

In particular, if you have an older App ID in the Certificates, Identifiers & Profiles section of App Store Connect, and didn't set it up after Xcode Cloud was released, you may find the Xcode Cloud tab in the App Store Connect portal simply won't work for that app:

Apple doesn't have any current explanation for this, and your only recourse in this case is to first remove the app from the App Store, delete the App ID, then create a new one with the same app bundle ID, then set up Xcode Cloud in App Store Connect for that App ID.

This is a ridiculous and inexcusable oversight on Apple's part.

Worse, if you do have to remove and recreate the App ID you will likely also lose all past metrics and analytics data for the app, and you'll have to re-enter and re-upload all app specifics, screenshots, and movies to App Store Connect.

You or one of your team members will also need to be familiar with source code management, such as git, GitHub, or one of the other supported source code management systems.

At a bare minimum you'll need to read most of the documentation for:

1. App Store Connect
2. Certificates, Identifiers & Profiles for App Store Connect
3. Team and member management for App Store Connect
4. Xcode source code management
5. Xcode Singing and Capabilities
6. Xcode Schemes and sharing
7. About continuous integration and delivery with Xcode Cloud
8. Configuring Xcode Cloud for your team
9. Making dependencies available to Xcode Cloud
10. Requirements for using Xcode Cloud
11. Source Control Requirements
12. Configuring your first Xcode Cloud workflow

In addition, Apple changed Xcode's build system in Xcode 10 so if you're not familiar with those changes yet, you'll need to read the page Build System Release Notes for Xcode 10 in Xcode 10 Release Notes.

Be ready to spend hours or even days reviewing Apple's developer documentation.

Project and Workspace requirements

There is a long list of things you must have configured in your project or workspace in order to use Xcode Cloud. The list is huge so we won't get into it here.

You can read more about Xcode Project and workspace requirements in the Apple Xcode Cloud Requirements page.

Once your project meets the requirements, you must configure Xcode Cloud to access your project's source code management account on GitHub, GitLab, on BitBucket, or a BitBucket server. Xcode Cloud requires a git-based, network-enabled SCM system to work.

If your project has an SCM (Source Code Management) administrator, ask them to configure Xcode Cloud and your development team's account to access your SCM account in Xcode Cloud, using one of the above-mentioned SCM services.

Apple has more info on the page Configuring Xcode Cloud for your team.

Apple also provides this warning on the Xcode Cloud requirements page about using third-party tools that generate or modify Xcode projects or workspaces:

Important
Xcode Cloud requires a consistent Xcode project or workspace that's always present. If you use a third-party tool that dynamically generates or edits your project or workspace, the initial configuration of Xcode Cloud and subsequent builds may fail.

If you haven't already connected Xcode Cloud to your SCM system, when you open an Xcode project whose App ID and bundle ID have been set in App Store Connect, you may see the following alert in Xcode the next time you open your Xcode project:

Diving deeper into build specifics

Once you have reviewed and understand all the Xcode Cloud and App Store Connect developer information, have connected Xcode Cloud to GitHub or another supported cloud SCM service, and have configured your App ID to use Xcode Cloud, you can start to use it from within Xcode itself.

As a CI service, Xcode Cloud allows you to specify source code repos to monitor, including which branches to use, configure builds, run and monitor builds, and check builds for errors. The Xcode Cloud bot allows you to configure when to run builds, monitor builds, and automate when to distribute builds using Apple's TestFlight build distribution app and service.

For example, you might set up Xcode Cloud bots to run a nightly build, as well as builds at specific project milestones, when source code commits occur, or only when changes to certain branches in repos occur.

Xcode Cloud bots can tell you when and if a build fails, what caused it, and who was responsible.

Once you've set up your Xcode Cloud bots, builds run automatically at the times you've indicated and you no longer need to worry about building software - Xcode Cloud handles all the builds for you.

The current version of Xcode Cloud has the ability to log into your GitHub repos once you authorize it, and retrieve source code for building automatically privately on Apple's Xcode Cloud servers. All the code downloads and builds happen on Apple's servers so you don't have to worry about configuring build machines to act as build servers.

You can also review all build status and errors by entire teams or only for you by clicking the "Mine" tab in the Xcode Could build summary tab.

Using Xcode Cloud from within Xcode

Once all the setup and documentation hassles are out of the way, Apple has made Xcode Cloud fairly easy to use from within the Xcode IDE app. You can also view and configure some Xcode Cloud details from within Apple's App Store Connect web portal for developers.

To get started with Xcode Cloud in the Xcode IDE on your Mac, launch Xcode, then select Xcode Cloud->Create Workflow... from the Product menu in the menu bar at the top of the screen:

Note that until an Xcode project's App ID, team and signing settings, and SCM info are connected to Xcode Cloud, the Xcode Cloud menu item doesn't show up in Xcode.

Next, in Xcode's Project Editor on the left side of your project or workflow window, select the Cloud tab next to the Local tab. This switches the view in Xcode to the Xcode Cloud view.

In the Cloud view, you can see all the build workflows and tasks for the current project. You can also view the results of recent builds in this view.

There is also a Start Build button on the right of the Cloud view to start builds running immediately. The build layout view in App Store Connect is similar on the web.

If a build fails due to errors, a Rebuild button appears in the overview pane.

Xcode Cloud workflows

Xcode Cloud uses Workflows to set up build conditions to run when builds start.

To create a new Xcode Cloud workflow in your Xcode project, select the Cloud tab in the project window navigator on the left, then select Product->Xcode Cloud->Create Workflow from Xcode's menu bar.

This opens the Xcode Cloud project onboarding sheet in Xcode:

From here you can grant access to your source code repo on GitHub or one of the other supported Git-based services. This assumes your SCM system is already connected in the Xcode Cloud setup steps mentioned above.

Once you've granted access, you can set up the initial conditions for the Xcode Cloud workflow in the sheet. These include start conditions, environment, actions, and post actions.

You can also set up notifications via email or Slack.

Under the General row you can give the workflow a name and description, select a repo from the popup menu, and select a project or workspace. You'll want to set these before setting the initial build conditions in the next step.

Under Start Condition you can choose which git branch to use for your build, when to trigger a build based on SCM changes, and whether to start a build when any file changes, or based on custom conditions.

When you've set all the start conditions for a build, click the Save button.

You can also set environment settings and actions to take during and after builds.

Once your Xcode Cloud workflow is configured, Xcode Cloud will begin running cloud-based builds based on the conditions you set.

Monitoring

At any time you can check the status of builds by clicking the Cloud tab in the Xcode project's navigator window, or on App Store Connect under the Xcode Cloud tab.

The Cloud tab in Xcode's project navigator provides a summary of all builds, the results of each build, and any errors that may occur for each contributor to the project. The Overview summary pane provides a quick glance at all build results.

Steep learning curve, but very useful

Xcode Cloud has a lot of potential once you get past the steep learning curve. But unless you are an extremely fast reader, be prepared to spend at least a few days reviewing the documentation and playing with the features of Xcode Cloud and Xcode to master the product.

To make Xcode Cloud seamless and easy to use, Apple needs to first fix the App Store Connect issues, and then make configuration easier within Apple Store Connect. Some automatic configuration in the way the Signing and Capabilities features have been upgraded would be nice.

Of paramount importance is that Apple reduce, shorten, streamline, and consolidate the developer documentation to make learning and using Xcode cloud quicker and easier.

From a team and automation perspective, there is no doubt Xcode Cloud is beneficial. Being freed from build server infrastructure and management is a win for any development team.

And even at the highest tier, monthly Xcode Cloud costs are likely to be much lower than an equivalent team of build and server engineers.

Once Apple fixes the issues mentioned above, Xcode Cloud will be a huge asset to any company or development team.

In future articles we'll delve deeper into using Xcode workflows, and how to run tests in Xcode Cloud.