Xcode Cloud workflow reference
Configure metadata, start conditions, actions, post-actions, and more to create custom Xcode Cloud workflows.
Overview
By configuring a first workflow in Xcode, you started a continuous integration and delivery (CI/CD) practice with Xcode Cloud. After you’ve reviewed how you can best refine your CI/CD practice as described in Developing a workflow strategy for Xcode Cloud, create custom workflows that fit the unique needs for ensuring your app’s or framework’s quality. For example, add metadata to describe the purpose of a workflow, configure conditions that start a new build, add actions and post-actions, and more.
You need to use Xcode to initially configure your project or workspace to use Xcode Cloud. However, after you’ve started your first build, you can edit and create workflows in either Xcode or App Store Connect.
For additional information about Xcode Cloud workflows, see Explore Xcode Cloud workflows and Customize your advanced Xcode Cloud workflows.
Metadata
Even if you’re a solo developer, you might create several workflows. To help distinguish workflows from each other and make each workflow’s purpose easy to understand, open the workflow and provide metadata in the General section.
- Name
Choose a name that’s easy to recognize. For example, name a workflow “Nightly Builds” if it distributes a new version of your app to your team every night.
- Description
Provide additional context that explains the workflow’s purpose. For example, enter “A workflow that automatically archives both the iOS and the macOS app every night”.
[Image]
Environment
When you develop and maintain your app or framework over time, you need to make sure that current and upcoming Xcode versions can successfully build it. If your product is a framework, you might need to ensure your framework supports previous Xcode versions.
To reduce the work needed to perform these verifications, configure a workflow’s temporary build environment. For example, create a workflow that builds your project and runs your tests using the latest publicly released Xcode and macOS versions. Then, create another workflow that performs the same verifications with the latest beta versions of macOS and Xcode.
To configure a workflow’s temporary build environment, navigate to the workflow’s Environment section, and choose from available Xcode and macOS versions.
Perform a clean build
To reduce the amount of time it takes to perform a build, Xcode Cloud stores each build’s derived data and other cached information for reuse in a secure and private way. However, you might need to perform a clean build that doesn’t cache data. For example, you need to configure a workflow to perform a clean build if you add a post-action that distributes a new version to external testers with TestFlight.
To configure a workflow that starts a new build without cached data:
Open the workflow in Xcode or App Store Connect and navigate to the Environment section.
Select Clean and save the workflow.
Custom environment variables
In addition to Xcode and macOS versions, you can set custom environment variables for a workflow in its Environment section. These variables are available to custom build scripts you use to extend workflows. For example, set a secret environment variable to contain an API key you use in a custom build script that uploads a workflow’s artifacts to your server.
Start conditions
When you create a new workflow, Xcode suggests the Branch Changes condition that starts a new build for every change to your Git repository’s default branch. This condition is useful when you get started with CI. However, starting a build for every change to your default branch might not be the appropriate setting for you. For example, a workflow that runs UI tests on many simulated devices can take a significant amount of time to complete, and starting a build for every branch change isn’t practical. In this case, make changes to the workflow’s start condition or add start conditions to tell Xcode Cloud to perform a workflow less often.
For more information about configuring start conditions, see Configuring start conditions.
Auto-cancel builds
By default, workflows have the Auto-cancel Builds setting enabled for each start condition. As a result, Xcode Cloud automatically cancels an in-progress build if a workflow queues a new build for the same workflow. This reduces the time to verify your latest code change — a useful setting in case you push updates to a branch in quick succession.
For example, say you push five changes to a branch within five minutes. Xcode Cloud detects each change and starts a build because it meets the Branch Changes start condition, resulting in five builds. To know whether your fifth change passed the configured verifications, you’d have to wait for each build to complete, even though the fifth change supersedes the others. With Auto-cancel Builds enabled, Xcode Cloud cancels the first four builds and immediately starts the build for the latest change.
Actions
Automatically and frequently building your project and verifying changes is key to a CI/CD practice. As a result, configuring a workflow’s actions is a fundamental task you perform in its Actions section. A workflow can perform the following actions:
Build
Test
Analyze
Archive
Note how these actions match your project’s or workspace’s scheme actions. To create a workflow that fits your requirements, add as many actions to a workflow as needed. For example, create a workflow that performs the test and archive actions for your app.
For detailed information on actions you configure for an Xcode Cloud workflow, see Configuring your Xcode Cloud workflow’s actions. For additional information on using Xcode Cloud to run your tests, see Author fast and reliable tests for Xcode Cloud.
Post-actions
Performing actions is at the core of a workflow. However, similar to how you configure post-actions in a scheme, you can configure post-actions for a workflow that happen after Xcode Cloud performs the workflow’s actions.
By adding post-actions, you can:
Configure custom notification settings. For example, limit email notifications to a certain build status, let Xcode Cloud email additional coworkers, or configure Xcode Cloud to send notifications to Slack.
Distribute a new version of your app to testers using TestFlight.
Upload a version of your app to App Store Connect that you can subsequently submit for app review.
For additional information on sending notifications to Slack, see Connecting Xcode Cloud to Slack
Custom build scripts
Xcode Cloud uses your project’s configured schemes and offers a wide variety of workflow settings. However, you might want to perform additional custom tasks you can’t configure using a scheme or workflow. For example, you might need to install an additional tool to build your project, to upload an app archive to storage, to use a different app icon for nightly builds, and so on.
To address these use cases, you can create shell scripts, referred to as custom build scripts, that Xcode Cloud runs at a specific moment during a build. For more information, see Writing custom build scripts.
Automate workflow management
Using either Xcode or App Store Connect, you can create custom workflows to verify the quality of your apps or frameworks. However, you may need to further automate Xcode Cloud usage and create and manage numerous workflows for multiple apps — especially in a corporate context. If this applies to you, use the App Store Connect API to manage workflows, start builds, and access Xcode Cloud data. For more information, see Xcode Cloud Workflows and Builds.