Getting Started with Xcode Cloud

Xcode Cloud is Apple’s latest continuous integration and delivery service. With Xcode Cloud, you can test and distribute your apps through Apple’s servers. Best of all, it’s built right into Xcode!

This year, Apple released Xcode Cloud to all developers. Apple is offering 25 compute hours a month for free until December 2023.

In this Xcode Cloud tutorial, you’ll learn how to automate steps in your build process. You’ll run unit tests and create TestFlight builds any time code changes in your Git branch.

To follow along with the tutorial, you’ll need an Apple Developer account.

Why use Xcode Cloud?

Xcode Cloud is Apple’s implementation of Continuous Integration and Continuous Delivery, also known as CI/CD. Continuous Integration is a software development practice that allows you to merge several changes into a Git branch that maintains its stability through automated steps like unit tests. On the other hand, Continuous Delivery is a software development practice that allows you to automate most of your release process, which includes build and distribute to TestFlight.

Xcode Cloud allows you to create workflows to automate tasks you’d otherwise perform on your local machine. Xcode Cloud works with your Git repository on GitHub, GitLab or Bitbucket.

For example, you could create a workflow that builds your app and deploys to TestFlight when anyone on your team merges code to a specific Git branch.

You won’t need to worry about manually distributing your app to team members and testers! Xcode Cloud takes care of all the heavy lifting to build and distribute your app, while your local machine is free to work on other features…or watch YouTube videos. :]

Getting Started

Download the starter project by clicking the Download Materials button at the top or bottom of the tutorial.

The materials contain a project called Coffee. The app tracks your favorite coffees or teas, along with tasting notes and a flavor profile.

Open the starter project. Build and run. The + button at the top right lets you add a new coffee, and tapping a coffee in the list lets you edit it.

In this tutorial, you’ll create Xcode Cloud workflows for the Coffee app.

First things first, though. Xcode Cloud requires a series of prerequisites before configuring your workflows.

Setting Up Prerequisites

Xcode Cloud requires two setup steps outside of Xcode:

1. Enroll in the Apple Developer Program.
2. Use a Git source code management tool to host your code.

First, you’ll need to enroll in the Apple Developer program. It’s OK if your membership is via a team in the Apple Developer program, as long as you can create a new app record.

Next, you’ll need a place to store your code. This tutorial stores code in GitHub, and all the references in the tutorial point to GitHub. Open a web browser and navigate to GitHub. Create an account on GitHub if you don’t already have one, then create a new repository.

Click the + in the top right of GitHub. Then, click New Repository to create the repository.

Your browser will direct you to a screen to enter repository details.

Enter Coffee as the repository name. Or, if you want to enter something else, go for it! The specific name isn’t relevant to Xcode Cloud. Leave all the other repository settings as the default values.

Finally, upload the Coffee starter project to the new GitHub repository. Follow the steps GitHub provides after creating your new repository. Start by opening Terminal and navigating to the starter project folder. Replace path_to_coffee_starter_project with your actual path!

cd path_to_coffee_starter_project

Then, create a Git repository in the Coffee starter project folder.

// 1
git init
git add .
git commit -m "first commit"
git branch -M main

//2
git remote add origin git@github.com:your-username/Coffee.git

// 3
git push -u origin main

Here’s what’s happening in each command:

1. Initialize the repo by copy and pasting the first four commands in Terminal.
2. Add a reference to your git remote repository. Replace your-username with your GitHub username.
3. Push the code to the remote repository.

You’re almost done setting up prerequisites. Only a couple more steps before you can unleash the power of Xcode Cloud!

Updating the Coffee App Project

Xcode Cloud requires two more setup steps:

1. Add your Apple ID to Xcode.
2. Set the bundle identifier for your app in Xcode.

First, sign in to Xcode using your Apple ID. Open preferences using Xcode ▸ Preferences, then navigate to Accounts. Click the + in the lower right, and add your Apple ID.

Xcode Cloud also requires you to set the bundle identifier in the Signing & Capabilities tab.

Open the Coffee starter project again. Navigate to the Coffee project settings. Select the Coffee target, and navigate to the Signing & Capabilities tab.

Next, you’ll update the Team and Bundle Identifier.

For Team, select the team that matches your Apple Developer Program account. For Bundle Identifier, enter a bundle identifier in the following format: com.yourcompany.Coffee.

Phew, that was quite a bit of setup. Now, on to the fun stuff! Xcode Cloud workflows are ready to enhance your project with the magic of CI/CD.

Creating Your First Workflow

Your first workflow is the default Xcode Cloud workflow. The default workflow builds your app when you merge code to the main branch. Xcode Cloud notifies you via email if the build fails.

Before you begin, you’ll have to change the app’s Product Name to a unique name. The name “Coffee” is unfortunately already taken. You can come up with something fun, though. Open the starter project in Xcode and navigate to Project ▸ Build Settings. Select Filter on the top right, and enter Product Name.

Change the name to something no one else will think of. Try this format: Coffee[YourName][4-digit-number]. For example, CoffeeJoshBerlin5745. You won’t actually release this app, so the product name doesn’t matter much.

You’ll make two more changes using your new product name. First, open the Coffee project settings and select the CoffeeTests target.

Select Filter on the top right and enter Test Host. You’ll filter the list of options to the Test Host values for the debug and release configurations.

Xcode reads the Test Host path when running automated tests. You’ll need to update the path to use your new product name. Double-click the Debug test host value. Then, change the two references to Coffee to your new product name. Your new value will look like this, but with your name:

Next, open CoffeeViewModelTests.swift and change @testable import Coffee to your new name. Your new import will follow this format:

@testable import CoffeeJoshBerlin5745

Now that you have a unique product name, you can create your first workflow. Navigate to the Report Navigator.

The Report Navigator contains two tabs: Local and Cloud. Local displays all builds your computer runs locally. Cloud contains all builds Xcode Cloud runs in the cloud.

In the Cloud tab, click the Create Workflow button to create your first workflow.

Xcode Cloud works with apps and frameworks. Select your product and click Next.

Xcode allows you to review the workflow before continuing. For now, leave all the settings as the defaults and click Next. Xcode Cloud contacts GitHub to check permissions.

You haven’t set up any permissions yet, so Xcode Cloud asks you to grant access to your source code on GitHub. Click the Grant Access button to start the process.

Xcode opens App Store Connect in a web browser and prompts you to Connect Xcode Cloud with GitHub. Connecting is a two-step process:

1. Link your Apple ID with your GitHub account.
2. Install the Xcode Cloud app on your GitHub account.

Click Complete Step 1 in GitHub to open GitHub and link your Apple ID. App Store Connect opens GitHub for authorization.

Click Authorize Xcode Cloud to authorize Apple to link your Apple ID with GitHub. Now, GitHub prompts you to install the Xcode Cloud app.

Click Install to complete the authorization and installation process. GitHub redirects you back to App Store Connect.

A green check mark means you’ve connected Xcode Cloud with GitHub! Apple even provides a handy button to re-open Xcode. Go ahead and click the Continue in Xcode button.

Back in Xcode, the grant access button is no longer available, and you’ll see another green check mark.

Click Next to continue creating your first workflow. Xcode Cloud has GitHub permissions now, but it looks like you’ve hit a new roadblock!

Xcode Cloud requires an app on App Store Connect with your app’s bundle identifier. Lucky for you, Xcode can create the app without even opening a browser. Click Complete to create your app.

The final green check mark means Xcode Cloud is ready for launch! At this point, you can create and run workflows.

Go ahead and click Start Build to kick off your very first Xcode Cloud build. Xcode Cloud immediately starts the build and switches to the build info in Xcode. Xcode Cloud also sends you an email when the build finishes. Congrats on your first Xcode Cloud build. :]

In the next section, you’ll set up a workflow to run the app’s unit and UI tests.