A step-by-step guide to connecting your project, choosing a scheme, and creating your first Xcode Cloud workflow that builds and tests your iOS app automatically on every commit.
You need a few things in place before Xcode Cloud will cooperate. Start with an active Apple Developer Program membership, since Xcode Cloud is tied to it.
Make sure you have a recent version of Xcode installed, because Xcode Cloud onboarding happens inside the Xcode app.
Your app should build cleanly and locally with a shared scheme. A shared scheme is essential, since Xcode Cloud reads it to know what to build and test.
Finally, your project should live in a supported source control host such as GitHub, GitLab, or Bitbucket, and you should have permission to authorize access to that repository.
Open your project in Xcode and look at the menu bar. Under the Product menu you will find an Xcode Cloud entry, or you can open the Report navigator and select the Cloud tab.
Choose Create Workflow to begin. Xcode presents a guided flow that walks you through the essentials rather than dropping you into raw configuration.
Select the app or product you want to build. If your project contains multiple apps, pick the primary target you intend to ship.
This onboarding step is where Apple sets up your app in App Store Connect if it is not already there, so keep your bundle identifier consistent.
Xcode Cloud asks which scheme it should use. The scheme defines the targets, build configuration, and tests that run, so choose the shared scheme you verified earlier.
If your scheme is not shared, cancel out, mark it as shared in the scheme editor, commit that change, and return. Xcode Cloud cannot see a local-only scheme.
Double-check that the scheme builds the configuration you expect, typically a Debug configuration for test workflows and a Release configuration for distribution.
Getting this right now saves confusion later, because an incorrect scheme is one of the most common reasons a first workflow behaves unexpectedly.
Xcode Cloud needs to read your repository to fetch commits and trigger builds. It will prompt you to connect your source control provider.
Authorize the connection and grant access to the specific repository. For hosted providers this usually means approving an app or integration on the provider's side.
If you use a private repository, make sure the account you authorize has access to it. Missing permissions here lead to builds that never start.
Once connected, Xcode Cloud can watch branches and pull requests according to the start conditions you configure in the next step.
Start conditions tell Xcode Cloud when to run. The default is often a branch change, meaning a build kicks off whenever you push to a chosen branch.
You can also trigger on pull request changes, which is ideal for validating contributions before they merge. Tag-based conditions are useful for release builds.
Pick conditions that match your team's workflow. Many teams start with a single condition on their main development branch and expand later.
Avoid triggering on every branch immediately if you are watching compute usage, since broad conditions can generate many builds and consume compute hours quickly.
A workflow is a set of actions. For a first workflow, a Build action plus a Test action is a strong, practical starting point.
The Test action lets you choose destinations, meaning the simulated devices and OS versions your tests run against. Start with one or two destinations to keep builds fast.
You can add an Analyze or Archive action later. Archive is what you will eventually use to produce a build for TestFlight or the App Store.
Review each action's settings, then confirm. Xcode Cloud validates your choices and highlights anything it cannot resolve, such as a missing test plan.
Save the workflow and Xcode Cloud will typically start an initial build so you can confirm everything works. Watch the progress in the Xcode Cloud tab.
Each action reports its status. If the build succeeds, you will see green checkmarks and can drill into logs, test results, and any produced artifacts.
If something fails, open the logs. The most common first-run issues are signing configuration, a non-shared scheme, or missing dependencies, all of which the logs identify.
After a green run, your pipeline is live. Every qualifying commit now builds and tests automatically without any manual steps from you.
Even a careful setup can stumble on the first run, and knowing the usual suspects saves time.
If the workflow never starts, revisit your start conditions and confirm you actually pushed to a branch the workflow watches. A mismatch there is the most frequent cause of silence.
If the build starts but fails immediately, a non-shared scheme or a signing configuration problem is likely. Both are called out clearly in the logs, so read from the first error downward.
If dependencies fail to resolve, remember the cloud uses a clean environment. Anything that lives only on your Mac, or is excluded from source control, will not be present unless you commit it or install it with a custom build script.
Work through these one at a time and re-run after each change. Fixing a single thing per run makes it obvious which change resolved the issue.
It helps to internalize the mental model behind Xcode Cloud before you start adding complexity to your setup.
A workflow is simply a named recipe. It combines start conditions, an environment such as a chosen Xcode version, and a sequence of actions like build, test, analyze, and archive.
You can have several workflows for one app, each with a different purpose. A common pattern is one workflow for pull request validation and another for release builds.
Separating concerns this way keeps each workflow easy to reason about. A busy test workflow does not accidentally produce release artifacts, and a release workflow does not fire on every routine commit.
Once this model clicks, extending your pipeline feels natural rather than confusing, because every new capability is just another action or another workflow with its own clear trigger.
Once your basic workflow is stable, extend it. Add distribution to TestFlight, more test destinations, or custom build scripts for tasks like code generation.
Keep an eye on compute usage in App Store Connect. Test matrices across many devices are powerful but consume compute faster than a single-destination build.
Remember what Xcode Cloud does and does not do. It automates building, testing, and shipping code you wrote. It is not a visual builder and does not generate a native Swift app for you.
And regardless of how you build, releasing to the App Store still requires Xcode configuration and an active Apple Developer Program membership. Xcode Cloud streamlines the pipeline around that reality rather than replacing it.
The scheme is almost certainly not shared. Open the scheme editor, enable Shared, commit the change, and Xcode Cloud will detect it.
No. A build-and-test workflow is a great starting point. You can add TestFlight or App Store distribution actions once the basics are stable.
It works with major hosted providers such as GitHub, GitLab, and Bitbucket. You authorize access to the specific repository during setup.
Only commits that match your start conditions. You control which branches, pull requests, or tags trigger runs to manage compute usage.
Yes. Xcode Cloud is integrated with App Store Connect, and onboarding registers your app there using your bundle identifier.