Getting Began with Xcode Cloud

Xcode Cloud is Apple’s newest steady integration and supply service. With Xcode Cloud, you may 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 without spending a dime till December 2023.

On this Xcode Cloud tutorial, you’ll learn to automate steps in your construct course of. You’ll run unit checks and create TestFlight builds any time code modifications 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 called CI/CD. Steady Integration is a software program improvement 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 checks. Alternatively, Steady Supply is a software program improvement 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 together with your Git repository on GitHub, GitLab or Bitbucket.

For instance, you could possibly create a workflow that builds your app and deploys to TestFlight when anybody in your crew merges code to a particular Git department.

You received’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 venture by clicking the Obtain Supplies button on the prime or backside of the tutorial.

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

Open the starter venture. 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 stipulations earlier than configuring your workflows.

Setting Up Conditions

Xcode Cloud requires two setup steps outdoors 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 crew within the Apple Developer program, so long as you may 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 online browser and navigate to GitHub. Create an account on GitHub in case you 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 screen to enter repository particulars.

Enter Espresso because the repository title. Or, if you wish to enter one thing else, go for it! The precise title isn’t related to Xcode Cloud. Depart 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 venture to the brand new GitHub repository. Comply with the steps GitHub offers after creating your new repository. Begin by opening Terminal and navigating to the starter venture folder. Substitute path_to_coffee_starter_project together with your precise path!

cd path_to_coffee_starter_project

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

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

//2
git distant add origin [email protected]:your-username/Espresso.git

// 3
git push -u origin essential

Right here’s what’s taking place 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 together with your GitHub username.
3. Push the code to the distant repository.

You’re virtually achieved organising stipulations. Solely a pair extra steps earlier than you may 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 to 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 venture once more. Navigate to the Espresso venture 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 venture 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 once you merge code to the primary department. Xcode Cloud notifies you through electronic mail if the construct fails.

Earlier than you start, you’ll have to alter the app’s Product Identify to a novel title. The title “Espresso” is sadly already taken. You may provide you with one thing enjoyable, although. Open the starter venture in Xcode and navigate to Venture ▸ Construct Settings. Choose Filter on the highest proper, and enter Product Identify.

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

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

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

Xcode reads the Take a look at Host path when operating automated checks. You’ll must replace the trail to make use of your new product title. Double-click the Debug take a look at host worth. Then, change the 2 references to Espresso to your new product title. Your new worth will seem like this, however together with your title:

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

@testable import CoffeeJoshBerlin5745

Now that you’ve a novel product title, you may create your first workflow. Navigate to the Report Navigator.

The Report Navigator accommodates two tabs: Native and Cloud. Native shows all builds your pc runs regionally. Cloud accommodates 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 overview the workflow earlier than persevering with. For now, go away 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 online browser and prompts you to Join Xcode Cloud with GitHub. Connecting is a two-step course of:

1. Hyperlink your Apple ID together 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 linked 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 out there, 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, nevertheless it seems such as you’ve hit a brand new roadblock!

Xcode Cloud requires an app on App Retailer Join together 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 may 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 checks.

Making a Workflow to Run Checks

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

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

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

The Espresso app has a set of unit and UI checks. Open the Espresso starter venture and navigate to CoffeeViewModelTests.swift. The CoffeeViewModel saves new coffees and updates current coffees. The checks be sure your espresso is at all times saved correctly. Run the take a look at case utilizing the diamond to the left of the take a look at case title.

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

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

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

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

Within the earlier part, you arrange a default workflow that constructed the venture. Now you can edit it to run checks as an alternative. 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 accommodates a wide range of configuration choices:

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

As you may see, Edit Workflow accommodates a variety of configuration choices. In your unit and UI take a look at workflow, you’ll give attention to Common and Actions. Navigate to Common, and alter the Identify to Take a look at.

The workflow at present has an archive motion within the Actions part. The take a look at workflow solely runs checks, so you may 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 Take a look at 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 checks run on. You may 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 checks.
• Requirement configures whether or not the checks must cross or not. You need this workflow to fail if any checks fail, so Required To Go is the best choice.

The final part configures which gadgets the checks 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 alter code on the primary department. Now nobody can neglect to run the checks, since Xcode Cloud will at all times run them for you :]

Testing the Take a look at 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 routinely.

Navigate to the Report Navigator and choose the Cloud tab. Proper-click essential, and choose Begin Construct to begin the Take a look at workflow on the primary department.

Choose Begin if Xcode asks you to verify.

Notice: Examine the Don’t ask once more checkbox in case 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 checks on varied iPhone and iPad gadgets. This would possibly take a couple of minutes. Seize a espresso or tea whilst you await the construct to complete. :]

After Xcode Cloud finishes your take a look at construct, Xcode updates to point out a inexperienced examine mark as a result of all of the checks handed! Subsequent, you’ll add a unit and UI take a look at to verify saving a espresso with an empty title 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.title = ""

  do {
    // 2
    attempt await mannequin.saveCoffee(coffeeToSave)
    XCTFail("Espresso with no title ought to throw empty title error")
  } catch CoffeeViewModel.CoffeeError.emptyName {
    // 3
    XCTAssert(mannequin.showCoffeeErrorAlert)
    XCTAssertEqual(mannequin.saveCoffeeError, .emptyName)
  } catch {
    // 4
    XCTFail("Espresso with no title ought to throw empty title 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 alter the title to an empty string.
2. You attempt to save the espresso with the empty title. The saveCoffee(_:) methodology is async and throws errors. So, you must add attempt await earlier than saving.
3. You catch the particular CoffeeViewModel.CoffeeError.emptyName error from saveCoffee(_:). You additionally examine that the view mannequin’s showCoffeeErrorAlert is true. This implies the view mannequin is at present exhibiting an error alert, and the saveCoffeeError worth is .emptyName.
4. The take a look at fails for every other errors apart from 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 screen, the take a look at faucets the + button so as to add a brand new espresso.
2. On the Espresso Editor display screen, the take a look at faucets the Save button to save lots of the espresso. The default title is empty, so the espresso is saved with out a title. Subsequent, the take a look at tries to shut the Save Espresso error alert.

Notice: 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 primary department and watch Xcode Cloud run the checks. Open Terminal and navigate to the Espresso starter venture 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 essential

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

Xcode Cloud routinely ran the Take a look at workflow after you modified code on the essential department. Now, you may transfer on to the subsequent part whereas Xcode Cloud runs your checks. :]

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 primary department. Earlier than you begin, you’ll must create a bunch of inside 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 title to your group. Depart Allow computerized distribution chosen so the builds distribute to your testers with none further 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 to 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 to 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 Identify 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 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 (Inner Testing Solely).

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

Click on the + subsequent to Submit-Actions and choose TestFlight Inner Testing. Xcode Cloud provides the post-action, however shows a pink 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 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 an alternative 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 essential 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 electronic mail from TestFlight. Settle for the invite, and set up your new app!

The place to Go From Right here?

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

Apple’s Xcode Cloud documentation is an efficient place to go in case you’d wish to study extra. You’ll discover an article about organising Xcode Cloud to 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!