Getting Started with Xcode Cloud

Learn how to use Xcode Cloud to test and deploy your app on TestFlight. By Josh Berlin.

5 (2) · 1 Review

Download materials
Save for later

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.

TestFlight Xcode Cloud workflow

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.

Coffees list in the iPhone 14 simulator

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.

Action menu on GitHub

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

Create a new repository on GitHub

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.

Note: Xcode Cloud supports GitHub, GitLab and Bitbucket. You’re welcome to use any of the three, but this tutorial will provide screenshots and walkthroughs for GitHub.

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

git remote add origin

// 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.

Add Apple ID account in Xcode

Note: Learn more about signing in with your Apple ID from Apple’s documentation:

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.

Xcode Signing & Capabilities tab

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

Xcode 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.

Xcode entered team and bundle identifier

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.

Xcode updated 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.

Coffee test build settings

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 Test Host configuration option

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:

Xcode updated Test Host value

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.

Xcode navigate to Assistant Editor

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 select product in create workflow

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

Xcode review workflow

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.

Xcode grant access to source code

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.

Connect Xcode Cloud with GitHub

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

Grant Xcode Cloud GitHub permissions

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

Install Xcode Cloud on GitHub

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

Xcode installed on GitHub successfully

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.

Xcode access granted to source code

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 create app on App Store Connect

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.

Xcode Cloud app created

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.