Getting Began with Xcode Cloud

Discover ways 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’ll be able to check and distribute your apps via 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 without cost till December 2023.

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

To comply with 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 referred to as CI/CD. Steady Integration is a software program growth apply that lets you merge a number of adjustments right into a Git department that maintains its stability via automated steps like unit exams. Alternatively, Steady Supply is a software program growth apply that lets you automate most of your launch course of, which incorporates construct and distribute to TestFlight.

Xcode Cloud lets you 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 can create a workflow that builds your app and deploys to TestFlight when anybody in your crew merges code to a selected Git department.

You gained’t want to fret about manually distributing your app to crew 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 mission by clicking the Obtain Supplies button on the high or backside of the tutorial.

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

Open the starter mission. Construct and run. The + button on the high proper enables you to add a brand new espresso, and tapping a espresso within the listing enables 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 collection of stipulations earlier than configuring your workflows.

Setting Up Stipulations

Xcode Cloud requires two setup steps outdoors of Xcode:

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

First, you’ll have to enroll within the Apple Developer program. It’s OK in case your membership is by way of a crew within the Apple Developer program, so long as you’ll be able to 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 should you don’t have already got one, then create a brand new repository.

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

Your browser will direct you to a display screen 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.

Notice: 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 mission to the brand new GitHub repository. Observe the steps GitHub supplies after creating your new repository. Begin by opening Terminal and navigating to the starter mission folder. Exchange 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 mission folder.

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

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

// 3
git push -u origin essential

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. Exchange your-username along with your GitHub username.
3. Push the code to the distant repository.

You’re virtually performed establishing stipulations. Solely a pair extra steps earlier than you’ll be able to unleash the ability of Xcode Cloud!

Updating the Espresso App Venture

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, sign up 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 mission once more. Navigate to the Espresso mission 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 crew 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 boost your mission 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 by way of electronic mail if the construct fails.

Earlier than you start, you’ll have to vary the app’s Product Title to a novel identify. The identify “Espresso” is sadly already taken. You may provide you with one thing enjoyable, although. Open the starter mission in Xcode and navigate to Venture ▸ 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 adjustments utilizing your new product identify. First, open the Espresso mission settings and choose the CoffeeTests goal.

Choose Filter on the highest proper and enter Check Host. You’ll filter the listing 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 have to replace the trail to make use of your new product identify. Double-click the Debug check 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 comply with this format:

@testable import CoffeeJoshBerlin5745

Now that you’ve a novel product identify, you’ll be able to create your first workflow. Navigate to the Report Navigator.

The Report Navigator comprises two tabs: Native and Cloud. Native shows all builds your pc runs regionally. Cloud comprises 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 lets you evaluation 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 examine 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 examine mark means you’ve related Xcode Cloud with GitHub! Apple even supplies a useful 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 examine mark.

Click on Subsequent to proceed creating your first workflow. Xcode Cloud has GitHub permissions now, however it seems 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 examine mark means Xcode Cloud is prepared for launch! At this level, you’ll be able to 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 information in Xcode. Xcode Cloud additionally sends you an electronic 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 Assessments

Unit exams and consumer interface exams — also referred to as UI exams — are necessary to make sure you ship steady code. Everytime you change code in the principle Git department, it’s a good suggestion to run your check suite. Wouldn’t it’s good in case your exams ran routinely when code modified?

Excellent news — Xcode Cloud is right here to assist! Xcode Cloud can run your exams on code adjustments, 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 check.

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

The exams within the check case run within the simulator. As soon as full, the empty diamonds change to inexperienced examine marks.

Subsequent, navigate to CoffeeUITests.swift. The CoffeeUITests comprises one UI check to verify the Add Espresso button works. Run the check utilizing the diamond to the left of the check identify.

The check runs within the simulator, and the empty diamond adjustments to a inexperienced examine 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 mission. 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 comprises 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. It’s also possible to set setting variables for customized construct scripts or check actions.
• Begin Circumstances defines the circumstances that set off the workflow. You may set off the workflow when code adjustments on a git department, or whenever you create a Pull Request or Tag in GitHub. It’s also possible to 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 by way of Slack or electronic mail on success or failure.

As you’ll be able to see, Edit Workflow comprises lots of configuration choices. To your unit and UI check workflow, you’ll concentrate on Common and Actions. Navigate to Common, and alter the Title to Check.

The workflow presently has an archive motion within the Actions part. The check workflow solely runs exams, so you’ll be able to delete the archive motion. Navigate to Archive – iOS and delete the motion utilizing the trash icon within the high proper.

Subsequent, add a check motion utilizing the + subsequent to the Actions part title.

Choose Check so as to add a check motion.

The check motion lets you configure numerous choices:

• Platform defines which platform the exams run on. You may create a separate check motion for every platform you need to check.
• Scheme defines the scheme to make use of for the exams.
• Requirement configures whether or not the exams have to go or not. You need this workflow to fail if any exams fail, so Required To Move is the correct choice.

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 check workflow.

Nice job! You configured a workflow to run any time you alter 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 check workflow to the check. First, you’ll manually run the workflow. Then, you’ll replace a check and watch Xcode Cloud begin the workflow routinely.

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

Choose Begin if Xcode asks you to verify.

Notice: Examine the Don’t ask once more checkbox should you’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 numerous iPhone and iPad units. This may take a couple of minutes. Seize a espresso or tea whilst you watch for the construct to complete. :]

After Xcode Cloud finishes your check construct, Xcode updates to indicate a inexperienced examine mark as a result of all of the exams handed! Subsequent, you’ll add a unit and UI check 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 check:

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

  do {
    // 2
    strive 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 check 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 alter the identify to an empty string.
2. You attempt to save the espresso with the empty identify. The saveCoffee(_:) technique is async and throws errors. So, you must add strive await earlier than saving.
3. You catch the precise CoffeeViewModel.CoffeeError.emptyName error from saveCoffee(_:). You additionally examine that the view mannequin’s showCoffeeErrorAlert is true. This implies the view mannequin is presently exhibiting an error alert, and the saveCoffeeError worth is .emptyName.
4. The check fails for some other errors moreover the emptyName error.

Open CoffeeUITests.swift and add this new UI check on the finish of CoffeeUITests:

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

Right here’s how the UI check works:

1. On the Coffees display screen, the check faucets the + button so as to add a brand new espresso.
2. On the Espresso Editor display screen, the check 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 check tries to shut the Save Espresso error alert.

Notice: CoffeesScreen and CoffeeScreen encapsulate the actions to carry out the UI check. Browse CoffeesScreen.swift and CoffeeScreen.swift for a have 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 mission folder. Run the next instructions to commit and push your adjustments:

git commit -am "Including a brand new unit and UI check"
git push -u origin essential

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

Xcode Cloud routinely ran the Check workflow after you modified code on the essential department. Now, you’ll be able to 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 inner testers in TestFlight any time you push adjustments to the principle department. Earlier than you begin, you’ll have to create a bunch of inner testers in App Retailer Join. Open a browser and navigate to your app in App Retailer Join. Choose the TestFlight tab.

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

Enter Inner Testers because the identify on your group. Go away Allow automated 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 bunch 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 inner 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, examine the Limit Enhancing examine field.

Apple requires restricted modifying for any workflows with exterior deployments.

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

By default, the Platform is ready to iOS, and the Scheme is ready to Espresso — which is exactly what you need. For this workflow, you’ll deploy an app to your inner testers. Change the Deployment Preparation to TestFlight (Inner 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 bunch of inner testers. Xcode Cloud runs the Publish-Actions steps after the iOS archive is full.

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

Click on the + within the Teams part, and choose your new Inner 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 Inner 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 out 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 essential department, and click on Begin Construct. Now, sit again and loosen up 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 electronic mail from TestFlight. Settle for the invite, and set up your new app!

The place to Go From Right here?

Obtain the finished mission recordsdata by clicking the Obtain Supplies button on the high or backside of the tutorial.

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

We hope you loved this tutorial. If in case you have any questions or feedback, please be part of the discussion board dialogue beneath!