Getting Began with Xcode Cloud

Learn to use Xcode Cloud to check and deploy your app on TestFlight.

Xcode Cloud is Apple’s newest steady integration and supply service. With Xcode Cloud, you possibly can take a look at and distribute your apps by Apple’s servers. Better of all, it’s constructed proper into Xcode!

This 12 months, Apple launched Xcode Cloud to all builders. Apple is providing 25 compute hours a month totally free till December 2023.

On this Xcode Cloud tutorial, you’ll learn to automate steps in your construct course of. You’ll run unit exams and create TestFlight builds any time code modifications in your Git department.

To observe together with the tutorial, you’ll want an Apple Developer account.

Why use Xcode Cloud?

Xcode Cloud is Apple’s implementation of Steady Integration and Steady Supply, also called CI/CD. Steady Integration is a software program growth observe that means that you can merge a number of modifications right into a Git department that maintains its stability by automated steps like unit exams. Alternatively, Steady Supply is a software program growth observe that means that you can automate most of your launch course of, which incorporates construct and distribute to TestFlight.

Xcode Cloud means that you can create workflows to automate duties you’d in any other case carry out in your native machine. Xcode Cloud works along with your Git repository on GitHub, GitLab or Bitbucket.

For instance, you might create a workflow that builds your app and deploys to TestFlight when anybody in your workforce merges code to a selected Git department.

You gained’t want to fret about manually distributing your app to workforce members and testers! Xcode Cloud takes care of all of the heavy lifting to construct and distribute your app, whereas your native machine is free to work on different options…or watch YouTube movies. :]

Getting Began

Obtain the starter challenge by clicking the Obtain Supplies button on the prime or backside of the tutorial.

The supplies include a challenge known as Espresso. The app tracks your favourite coffees or teas, together with tasting notes and a taste profile.

Open the starter challenge. Construct and run. The + button on the prime proper permits you to add a brand new espresso, and tapping a espresso within the checklist permits you to edit it.

On this tutorial, you’ll create Xcode Cloud workflows for the Espresso app.

First issues first, although. Xcode Cloud requires a sequence of conditions earlier than configuring your workflows.

Setting Up Stipulations

Xcode Cloud requires two setup steps exterior of Xcode:

1. Enroll within the Apple Developer Program.
2. Use a Git supply code administration instrument to host your code.

First, you’ll must enroll within the Apple Developer program. It’s OK in case your membership is through a workforce within the Apple Developer program, so long as you possibly can create a brand new app file.

Subsequent, you’ll want a spot to retailer your code. This tutorial shops code in GitHub, and all of the references within the tutorial level to GitHub. Open an internet browser and navigate to GitHub. Create an account on GitHub if you happen to don’t have already got one, then create a brand new repository.

Click on the + within the prime proper of GitHub. Then, click on New Repository to create the repository.

Your browser will direct you to a display to enter repository particulars.

Enter Espresso because the repository identify. Or, if you wish to enter one thing else, go for it! The particular identify isn’t related to Xcode Cloud. Go away all the opposite repository settings because the default values.

Observe: Xcode Cloud helps GitHub, GitLab and Bitbucket. You’re welcome to make use of any of the three, however this tutorial will present screenshots and walkthroughs for GitHub.

Lastly, add the Espresso starter challenge to the brand new GitHub repository. Observe the steps GitHub offers after creating your new repository. Begin by opening Terminal and navigating to the starter challenge folder. Substitute path_to_coffee_starter_project along with your precise path!

cd path_to_coffee_starter_project

Then, create a Git repository within the Espresso starter challenge folder.

// 1
git init
git add .
git commit -m "first commit"
git department -M predominant

//2
git distant add origin git@github.com:your-username/Espresso.git

// 3
git push -u origin predominant

Right here’s what’s occurring in every command:

1. Initialize the repo by copy and pasting the primary 4 instructions in Terminal.
2. Add a reference to your git distant repository. Substitute your-username along with your GitHub username.
3. Push the code to the distant repository.

You’re nearly achieved organising conditions. Solely a pair extra steps earlier than you possibly can unleash the ability of Xcode Cloud!

Updating the Espresso App Mission

Xcode Cloud requires two extra setup steps:

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

First, check in to Xcode utilizing your Apple ID. Open preferences utilizing Xcode ▸ Preferences, then navigate to Accounts. Click on the + within the decrease proper, and add your Apple ID.

Xcode Cloud additionally requires you to set the bundle identifier within the Signing & Capabilities tab.

Open the Espresso starter challenge once more. Navigate to the Espresso challenge settings. Choose the Espresso goal, and navigate to the Signing & Capabilities tab.

Subsequent, you’ll replace the Crew and Bundle Identifier.

For Crew, choose the workforce that matches your Apple Developer Program account. For Bundle Identifier, enter a bundle identifier within the following format: com.yourcompany.Espresso.

Phew, that was fairly a little bit of setup. Now, on to the enjoyable stuff! Xcode Cloud workflows are prepared to reinforce your challenge 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 whenever you merge code to the principle department. Xcode Cloud notifies you through e-mail if the construct fails.

Earlier than you start, you’ll have to vary the app’s Product Title to a singular identify. The identify “Espresso” is sadly already taken. You possibly can give you one thing enjoyable, although. Open the starter challenge in Xcode and navigate to Mission ▸ Construct Settings. Choose Filter on the highest proper, and enter Product Title.

Change the identify to one thing nobody else will consider. Do this format: Espresso[YourName][4-digit-number]. For instance, CoffeeJoshBerlin5745. You gained’t really launch this app, so the product identify doesn’t matter a lot.

You’ll make two extra modifications utilizing your new product identify. First, open the Espresso challenge settings and choose the CoffeeTests goal.

Choose Filter on the highest proper and enter Check Host. You’ll filter the checklist of choices to the Check Host values for the debug and launch configurations.

Xcode reads the Check Host path when operating automated exams. You’ll must replace the trail to make use of your new product identify. Double-click the Debug take a look at host worth. Then, change the 2 references to Espresso to your new product identify. Your new worth will appear to be this, however along with your identify:

Subsequent, open CoffeeViewModelTests.swift and alter @testable import Espresso to your new identify. Your new import will observe this format:

@testable import CoffeeJoshBerlin5745

Now that you’ve got a singular product identify, you possibly can create your first workflow. Navigate to the Report Navigator.

The Report Navigator incorporates two tabs: Native and Cloud. Native shows all builds your pc runs regionally. Cloud incorporates all builds Xcode Cloud runs within the cloud.

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

Xcode Cloud works with apps and frameworks. Choose your product and click on Subsequent.

Xcode means that you can evaluate the workflow earlier than persevering with. For now, depart all of the settings because the defaults and click on Subsequent. Xcode Cloud contacts GitHub to test permissions.

You haven’t arrange any permissions but, so Xcode Cloud asks you to grant entry to your supply code on GitHub. Click on the Grant Entry button to begin the method.

Xcode opens App Retailer Join in an internet browser and prompts you to Join Xcode Cloud with GitHub. Connecting is a two-step course of:

1. Hyperlink your Apple ID along with your GitHub account.
2. Set up the Xcode Cloud app in your GitHub account.

Click on Full Step 1 in GitHub to open GitHub and hyperlink your Apple ID. App Retailer Join opens GitHub for authorization.

Click on Authorize Xcode Cloud to authorize Apple to hyperlink your Apple ID with GitHub. Now, GitHub prompts you to put in the Xcode Cloud app.

Click on Set up to finish the authorization and set up course of. GitHub redirects you again to App Retailer Join.

A inexperienced test mark means you’ve related Xcode Cloud with GitHub! Apple even offers a helpful button to re-open Xcode. Go forward and click on the Proceed in Xcode button.

Again in Xcode, the grant entry button is not obtainable, and also you’ll see one other inexperienced test mark.

Click on Subsequent to proceed creating your first workflow. Xcode Cloud has GitHub permissions now, nevertheless it appears such as you’ve hit a brand new roadblock!

Xcode Cloud requires an app on App Retailer Join along with your app’s bundle identifier. Fortunate for you, Xcode can create the app with out even opening a browser. Click on Full to create your app.

The ultimate inexperienced test mark means Xcode Cloud is prepared for launch! At this level, you possibly can create and run workflows.

Go forward and click on Begin Construct to kick off your very first Xcode Cloud construct. Xcode Cloud instantly begins the construct and switches to the construct data in Xcode. Xcode Cloud additionally sends you an e-mail when the construct finishes. Congrats in your first Xcode Cloud construct. :]

Within the subsequent part, you’ll arrange a workflow to run the app’s unit and UI exams.

Making a Workflow to Run Checks

Unit exams and consumer interface exams — also called UI exams — are vital to make sure you ship secure code. Everytime you change code in the principle Git department, it’s a good suggestion to run your take a look at suite. Wouldn’t it’s good in case your exams ran mechanically when code modified?

Excellent news — Xcode Cloud is right here to assist! Xcode Cloud can run your exams on code modifications, leaving your growth machine free for different duties.

The workflow you’ll configure on this part runs each the unit and UI exams everytime you replace the principle department. Xcode Cloud builds your app and runs all of your exams. You’ll obtain a full report of the exams as soon as they full. The report reveals which exams handed or failed, and it reveals screenshots of any failed take a look at.

The Espresso app has a set of unit and UI exams. Open the Espresso starter challenge and navigate to CoffeeViewModelTests.swift. The CoffeeViewModel saves new coffees and updates current coffees. The exams make sure that your espresso is all the time saved correctly. Run the take a look at case utilizing the diamond to the left of the take a look at case identify.

The exams within the take a look at case run within the simulator. As soon as full, the empty diamonds change to inexperienced test marks.

Subsequent, navigate to CoffeeUITests.swift. The CoffeeUITests incorporates one UI take a look at to substantiate the Add Espresso button works. Run the take a look at utilizing the diamond to the left of the take a look at identify.

The take a look at runs within the simulator, and the empty diamond modifications to a inexperienced test mark.

Subsequent, you’ll arrange a workflow to run these exams. Navigate to the Report Navigator.

Within the earlier part, you arrange a default workflow that constructed the challenge. Now you can edit it to run exams as a substitute. Proper-click Default and choose Edit Workflow.

The Edit Workflow window is the place you’ll discover all of the choices to configure a workflow.

Edit Workflow incorporates a wide range of configuration choices:

• Common configures high-level choices such because the workflow identify and description.
• Setting configures the Xcode and macOS variations for the construct machine. You can too set setting variables for customized construct scripts or take a look at actions.
• Begin Circumstances defines the circumstances that set off the workflow. You possibly can set off the workflow when code modifications on a git department, or whenever you create a Pull Request or Tag in GitHub. You can too set off workflows on a selected schedule.
• Actions defines the workflow steps, equivalent to Construct, Check, Analyze or Run.
• Publish-Actions defines any steps after the workflow completes. Workflows can deploy your app to TestFlight or notify through Slack or e-mail on success or failure.

As you possibly can see, Edit Workflow incorporates quite a lot of configuration choices. In your unit and UI take a look at workflow, you’ll deal with Common and Actions. Navigate to Common, and alter the Title to Check.

The workflow at the moment has an archive motion within the Actions part. The take a look at workflow solely runs exams, so you possibly can delete the archive motion. Navigate to Archive – iOS and delete the motion utilizing the trash icon within the prime proper.

Subsequent, add a take a look at motion utilizing the + subsequent to the Actions part title.

Choose Check so as to add a take a look at motion.

The take a look at motion means that you can configure varied choices:

• Platform defines which platform the exams run on. You possibly can create a separate take a look at motion for every platform you need to take a look at.
• Scheme defines the scheme to make use of for the exams.
• Requirement configures whether or not the exams must go or not. You need this workflow to fail if any exams fail, so Required To Go is the precise possibility.

The final part configures which units the exams run on. Click on the + so as to add iPads to your workflow.

Final, click on Save to complete creating your take a look at workflow.

Nice job! You configured a workflow to run any time you modify code on the principle department. Now nobody can overlook to run the exams, since Xcode Cloud will all the time run them for you :]

Testing the Check Workflow

On this part, you’ll put your new take a look at workflow to the take a look at. First, you’ll manually run the workflow. Then, you’ll replace a take a look at and watch Xcode Cloud begin the workflow mechanically.

Navigate to the Report Navigator and choose the Cloud tab. Proper-click predominant, and choose Begin Construct to begin the Check workflow on the principle department.

Choose Begin if Xcode asks you to substantiate.

Observe: Examine the Don’t ask once more checkbox if you happen to’d like future builds to begin with out affirmation.

Xcode switches your view to the construct overview. The overview reveals the standing of your construct, together with particulars and progress.

The construct runs on Apple’s construct machines and runs the exams on varied iPhone and iPad units. This would possibly take a couple of minutes. Seize a espresso or tea whilst you anticipate the construct to complete. :]

After Xcode Cloud finishes your take a look at construct, Xcode updates to point out a inexperienced test mark as a result of all of the exams handed! Subsequent, you’ll add a unit and UI take a look at to verify saving a espresso with an empty identify reveals an error.

Open the CoffeeViewModelTests.swift file. On the finish of CoffeeViewModelTests, add the next unit take a look at:

func testSaveCoffeeWithEmptyName() async throws {
  // 1
  var coffeeToSave = CoffeeViewModel.newCoffee
  coffeeToSave.identify = ""

  do {
    // 2
    attempt await mannequin.saveCoffee(coffeeToSave)
    XCTFail("Espresso with no identify ought to throw empty identify error")
  } catch CoffeeViewModel.CoffeeError.emptyName {
    // 3
    XCTAssert(mannequin.showCoffeeErrorAlert)
    XCTAssertEqual(mannequin.saveCoffeeError, .emptyName)
  } catch {
    // 4
    XCTFail("Espresso with no identify ought to throw empty identify error")
  }
}

Right here’s how the take a look at works:

1. You create a espresso to save lots of utilizing the default CoffeeViewModel.newCoffee. newCoffee is configured utilizing default values when saving a brand new espresso. Subsequent, you modify the identify to an empty string.
2. You attempt to save the espresso with the empty identify. The saveCoffee(_:) methodology is async and throws errors. So, it’s a must to add attempt await earlier than saving.
3. You catch the particular CoffeeViewModel.CoffeeError.emptyName error from saveCoffee(_:). You additionally test that the view mannequin’s showCoffeeErrorAlert is true. This implies the view mannequin is at the moment displaying an error alert, and the saveCoffeeError worth is .emptyName.
4. The take a look at fails for every other errors in addition to the emptyName error.

Open CoffeeUITests.swift and add this new UI take a look at on the finish of CoffeeUITests:

func testAddCoffeeWithNoNameShowsAlert() {
  // 1
  CoffeesScreen()
    .tapAddCoffeeButton()
  // 2
  CoffeeScreen()
    .tapSaveCoffee()
    .tapCloseSaveCoffeeErrorAlertButton()
}

Right here’s how the UI take a look at works:

1. On the Coffees display, the take a look at faucets the + button so as to add a brand new espresso.
2. On the Espresso Editor display, the take a look at faucets the Save button to save lots of the espresso. The default identify is empty, so the espresso is saved with out a identify. Subsequent, the take a look at tries to shut the Save Espresso error alert.

Observe: CoffeesScreen and CoffeeScreen encapsulate the actions to carry out the UI take a look at. Browse CoffeesScreen.swift and CoffeeScreen.swift for a take a look at how they work.

Subsequent, you’ll commit and push your new code to the principle department and watch Xcode Cloud run the exams. Open Terminal and navigate to the Espresso starter challenge folder. Run the next instructions to commit and push your modifications:

git commit -am "Including a brand new unit and UI take a look at"
git push -u origin predominant

Open the Espresso challenge and navigate to the Report Navigator. Choose the Cloud tab.

Xcode Cloud mechanically ran the Check workflow after you modified code on the predominant department. Now, you possibly can transfer on to the subsequent part whereas Xcode Cloud runs your exams. :]

Making a Workflow to Make TestFlight Builds

Xcode Cloud is an ideal match for TestFlight. Apple made it straightforward for builders to deploy builds to their groups with Xcode Cloud.

On this part, you’ll create a workflow to deploy a construct to inside testers in TestFlight any time you push modifications to the principle department. Earlier than you begin, you’ll must create a gaggle of inside testers in App Retailer Join. Open a browser and navigate to your app in App Retailer Join. Choose the TestFlight tab.

The Inside Testing part on the left sidebar is empty. Click on the + subsequent to Inside Testing so as to add a brand new group.

Enter Inside Testers because the identify on your group. Go away Allow computerized distribution chosen so the builds distribute to your testers with none additional steps. Click on Create to create your new group.

Click on the + subsequent to Testers (0) and add your self as a tester. Nice! You now have a gaggle of testers on your Xcode Cloud workflow. Now you’re able to open Xcode to arrange your new workflow.

Navigate to the Report Navigator. Choose the Cloud tab. This time, you’ll create a brand new workflow simply on your inside testers. Click on the circle button on the backside left and choose Create Workflow.

Choose your app product and click on Subsequent.

First, change the workflow Title to TestFlight. Subsequent, test the Prohibit Enhancing test field.

Apple requires restricted enhancing for any workflows with exterior deployments.

Subsequent, add an Archive motion by clicking the + subsequent to Actions and deciding on Archive. Xcode Cloud provides an archive motion for iOS by default.

By default, the Platform is about to iOS, and the Scheme is about to Espresso — which is exactly what you need. For this workflow, you’ll deploy an app to your inside testers. Change the Deployment Preparation to TestFlight (Inside Testing Solely).

Earlier than beginning an Xcode Cloud construct along with your new workflow, you’ll create a Publish-Actions step to deploy the TestFlight construct to a gaggle of inside testers. Xcode Cloud runs the Publish-Actions steps after the iOS archive is full.

Click on the + subsequent to Publish-Actions and choose TestFlight Inside Testing. Xcode Cloud provides the post-action, however shows a crimson X. The post-action doesn’t include any beta teams, so the motion shows an error.

Click on the + within the Teams part, and choose your new Inside Testers group. Your group has one tester — you!

Click on Add so as to add your group to the inner TestFlight deployment.

Now, the workflow deploys a construct to the Inside Testers group when the workflow runs. Click on Save to create your new workflow.

As a substitute of pushing new code, you’ll manually run the workflow to check the deployment. Proper-click your new TestFlight workflow and choose Begin Construct.

Because you began the construct manually, you’ll want to pick a department. Xcode Cloud shows a window so that you can choose the department.

Swap the filter from Mine to All to show all of the branches.

Choose the predominant department, and click on Begin Construct. Now, sit again and chill out whereas Xcode Cloud does all of the work to create your new TestFlight construct.

After Xcode Cloud completes the construct, you’ll obtain an invitation e-mail from TestFlight. Settle for the invite, and set up your new app!

The place to Go From Right here?

Obtain the finished challenge information by clicking the Obtain Supplies button on the prime or backside of the tutorial.

Apple’s Xcode Cloud documentation is an effective place to go if you happen to’d wish to be taught extra. You’ll discover an article about organising Xcode Cloud on your workforce. You’ll discover one other article about connecting Xcode Cloud to Slack.

We hope you loved this tutorial. When you have any questions or feedback, please be a part of the discussion board dialogue under!