Getting Setup With Xcode Cloud
Xcode Cloud is a Continuous Integration and Continuous Delivery (CI / CD) platform provided by Apple. It automates away the hard work of building your apps, testing them, signing them, and pushing them to a destination.
Why use Xcode Cloud I hear you say? If you’ve been through the process of manually archiving your app, then submitting it to iTunes Connect, you’ll know these steps take time.
With Xcode Cloud, Apple makes it easy to automate this with a few button clicks through Xcode. Let’s take a look at how to do this.
Setting Up Xcode Cloud
In order to use Xcode Cloud, you need to have a few things setup. The main requirements are:
- Enrollment in the Apple Developer Program
- An app record on App Store Connect
- Your Developer Apple ID added to Xcode
Your project also needs to be stored in a git repository. Xcode Cloud makes heavy use of git as a trigger to know when to start running.
A complete list of requirements is available if you find yourself needing more.
Once you’re setup, it’s time to setup a workflow. Along the top of Xcode, click the git branch so a popup appears. You’ll see an option called Create Workflow.
Click the option and Xcode will show a new window, asking which product to create a workflow for.
Select an app and click Next. You’ll be taken to the next screen to customise your workflow.
Creating a Workflow
The workflow screen contains a few different sections. First, it shows the General section where you can provide infomation about your workflow.
Here, you can give your workflow a name and a description on what it does. This is useful for yourself as a solo developer, or as a team where you have multiple engineers who need to use the same workflow.
You can also restrict the workflow from being edited in this section, ensuring workflows aren’t tampered with by other team members without the right permissions.
The next section is the Environment section. Here, you can select what version of Xcode and macOS your workflow will use.
Xcode Cloud provides a variety of Xcode versions, including beta versions. This is handy if you want to create multiple workflows building and testing different configurations.
The environment section also provides the option to clean the workflow before each build. With the option unchecked, each workflow stores the derived data and other infomation from each build to speed up subsequent builds.
Whilst this can be a good thing, you may want to avoid this depending on your needs. For example, delivering a build to TestFlight for external testing requires a clean build.
Finally, you can provide environment variables to the workflow. These can be picked up by custom build scripts used by your app to extend workflows. If a variable value needs to be kept secret, you can check the secret tickbox and the value will be hidden.
With the infomation for the workflow setup and the environment configured, the next step is to create triggers that cause the workflow to run.
Start Conditions
The next section is called Start Conditions. Here, you can tell the workflow what conditions should trigger it to run. By default, Xcode sets the start condition to be any change to any file on any branch.
It’s recommended to tweak this as your workflow will run for every commit. One option is to constrain the start condition to run for a certain branch. First, select the Custom Branches radio button, then begin to type the name of the branch. Xcode will search your git branches and suggest branches that match your search.
You can also choose to trigger workflows based on changes occurring to a specific file or folder, including specific types of files. Multiple files triggers can be added, giving you the ability to build complex trigger rules for file changes.
If you need a different trigger, you can create different start triggers by clicking the + next to the start condition. Xcode provides different triggers for a number of situations.
These range from changes to git tags, pull request changes, a scheduler for a specific branch, and finally a manually started workflow.
One common option across most of the triggers is the ability to Auto Cancel Builds. This is useful if your trigger is likely to start the workflow multiple times. Instead of waiting for each build to finish, Xcode Cloud cancels the older builds and prioritises the latest build.
This is so useful, it’s enabled by default!
When you’re happy with your workflow start triggers, you’re ready to move on and set up actions for the workflow to perform.
Workflow Actions
As part of any good CI / CD platform, performing actions regularly and repetitively is good practice to ensure your app is builds successfully and you can catch issues quickly.
Xcode Cloud is no exception, and allows you to choose from a selction of Actions. By default, your workflow includes a Build action to build your chosen app scheme.
If there are issues with the scheme, Xcode Cloud provides a helpful warning so you can address it.
Similar to start triggers, you can add more build actions that are run as part of the workflow. These include running tests, running the analyzer, and archiving your app before distributing it to TestFlight or the App Store.
The test and analyse build actions contain a Requirement setting. This setting decides whether the build action must pass for the workflow to continue. For example, if you want to workflow to fail if one of your tests fail then you can enforce this requirement.
Interestingly, the test build action doesn’t seem to support visionOS at present.
You can configure as many build actions as needed for your workflow. You could for example, run the tests for each scheme in your project, then build, archive, and distribute each app in one workflow.
Once you are happy with your build action setup, you can move to the final part of the workflow. Setting up post actions.
Post Actions
Post Actions allow you to perform a couple of actions before the workflow is complete. These include distributing new builds to TestFlight users, notarizing macOS apps, and notifying others of the workflow result through Slack or email.
The Notify post action gives you a degree of control over what messages are sent. You can choose to recieve all Build Success messages, to be notified when the workflow is fixed from a previous failure, or not to be notified at all!
Similar options for Build Failure messages are available. You can choose to recieve all failure messages, breaking workflow messages only, or no failure messages at all.
Saving Your Workflow
Once you are happy with your Workflow. Click the Save button at the bottom right of the window.
Xcode Cloud will check the workflow and let you know if there are issues that must be addressed. If all is well, the workflow window disappears and takes you back to Xcode.
Click on the git branch along the top of Xcode again, and this time click Manage Workflows. A new window will appear, showing the workflow you created for the app.
If you want to edit the workflow, select the workflow and click the gear button in the bottom left corner. You can also click the - button whilst the workflow is selected to delete it.
Running Shell Scripts In Xcode Cloud
Xcode Cloud provides support for running shell scripts at specific parts of the workflow. This is useful if you need to perform more advanced configuration for your workflow, and allows your workflow to be customised even further.
Exploring this topic is beyond the scope of this post, however you can find out more in the Developer Documentation.
Viewing Your Workflow In Xcode And App Store Connect
You can view the results of your workflow in Xcode by clicking the Report Navigator and clicking the Cloud tab. Each workflow will be shown, including the results from each build.
You can also view and interact with your workflows in App Store Connect by navigating to your App Store listing and selecting the Xcode Cloud tab along the top of the listing.
Costs
Xcode Cloud comes included in every Apple Developer Program Membership. Each membership comes with 25 hours of compute time per month. If you go over then you can choose from a variety of subscription options to recieve more time.
Further Reading
Xcode Cloud on the surface is a simple to use CI / CD platform for your Apple Apps. Don’t be decieved however, in a few button clicks you can begin to create highly performant workflows that cover the majority of your use cases.
If you want to learn more, I recommend starting here:
-
Xcode Cloud Developer Documentation The offical documentation covering general usage and in depth topics on how to get the most out of Xcode Cloud.
-
Developing a workflow strategy for Xcode Cloud Best practice suggestions on how to refine your CI / CD practices using Xcode Cloud
-
Configuring Webhooks with Xcode Cloud Advice on how to expose Xcode Cloud events into your own tools and services using Webhooks.
Finally
If you enjoyed this blog post, consider dropping me a couple of $$$ over on Kofi.
You can also follow me on Social Media to hear more about software engineering by clicking the links below.