Setup

For this article, I’ve setup a quick app which you can fork on GitHub. It is a simple app with a Hello, world! view and a manager with some tests. The project is located on GitHub and can be found here.

Prerequisites

In order to get going, you need to have the appropriate access in the Apple Developer Console, preferably admin or Team Agent. The latest agreement needs to be accepted by the team agent as well, which is done in the developer console.

You will also have to be able to grand Xcode Cloud access to your GitHub (or GitLab, or bitbucket cloud) repository. Being an admin for the repository does help here.

Setup bundle ID and app

In the example app mentioned above, I’ve setup the bundleId com.paulpeelen.setupxcodecloud. You will have to change this to something that suits you, and needs to be added to the developer console as well. Of course you can use automated signing in Xcode too, but I like to be explicit here.

When this is done, you can add the app to AppStore Connect too. Open AppStore Connect and go to your apps, select the (+) in the top left corner just next to “Apps” and add your app.

Now you should be ready to add your first workflow.

Adding your workflow

Workflows are sets of actions for Xcode Cloud to perform when running your app. An app can have multiple workflows. For instance, when a push is done towards a branch you might want the tests to be run but when a push is done towards the main branch, you want the tests to be run as well as the app to be uploaded to TestFlight

Lets create the first workflow for the project. There are two ways of doing this, either by going via the menu Product > Xcode Cloud > Create Workflow, or via the Report Navigator (CMD + 9) and select the cloud tab. If you don’t have any workflows yet, it’ll instruct you to create a workflow after analyzing your project. In the picture below you’ll see both options.

For this article, we’re going to focus on adding a workflow which will archive and upload to AppStore Connect so the app will be available in TestFlight. Select the Create workflow option of your choice and start adding a workflow. A modal view will popup which will let you select the team:

… after which it will show you a predefined selection of what to do. We’re going to edit the suggested workflow

So lets select that “Edit workflow” button and edit the workflow. The next view will show you the different steps that will be preformed.

In the left you’ll find a menu with the different steps for the workflow. The first one selected is the general flow. Here you can set some default settings for the workflow, like name and description. You can also restrict the workflow if you like.

Environment

In the next page, under Environment, you can select which environment you want Xcode cloud to build upon. For instance, do you want Xcode cloud to build on the beta version, as well as do you want to use caching (default) or would you like Xcode Cloud not to restore the derrived data. This can be useful for some project, but it will also increase the overall build time on Xcode. If you have a lot of developers on a large project, this might increase the build time per build with a few minutes… resulting in an overall increase per day of a possible few hours (depending on the amount of developers and the amount of builds). The last thing you can select here is whether you would like some environment variables to be set.

For this article, we’re just going to put it on the latest beta and be let the rest on this page be.

Start condition

This is the actual trigger for the workflow. This is by default set to the current branch you’re working on… in this case main. Any push to said branch will trigger this workflow to be started. We would like to keep it like that for this article, but there are other triggers available for it too: E.g. you can schedule a start of the workflow (good for nightly builds) or whenever a tag or Pull Request has changes.

For this article, we’re going to use the default setting, being whenever something is pushed to main.

Actions

For actions, by default it’ll just archive… but we want a test too. So. lets add it by selecting the (+) sign in the left menu, right of the “Actions” title, then select “Test”. We want the tests to be successfully passed before we start archiving, so lets make sure the option Required to pass is enabled. The default settings are fine here for this project, but for yours you might want to adapt it. For instance, you might want multiple test actions, one for each platform.

Post actions

Last but not least, the post notifications. Here you can make Xcode Cloud post a message to Slack or send you an email when the build has completed. For the slack connection, you’ll have to connect that via AppStore Connect settings, but there is a button that will take you there so you can configure it directly.

Here, I’m going to add my email address under “email”. For now, I’ll leave the slack integration for what it is. There will be a seperate article on that in the future if needed.

Now, lets select the Save button and close this view.

Review

Now, if you have done evertything correct… the review should look like this:

Grant access

Follow the granting access link and a website where you will grant Xcode Cloud access to the repository will show. For this article we’re using GitHub, and those pages will look like so at the time of writing this article:

Xcode Cloud

GitHub
Scroll down to the bottom to see the repository selection:

When you’re done… this is the message that should be presented on Apple’s website:

… and in Xcode:

Complete

Now you can select next and complete the setup of your first workflow. You are now able to add multiple others as well, maybe one for when pull requests are updated?

Xcode will ask you now if you want to start your first build… and of course we want that. Select “Start build” and… start your first build:

Now you are thinking… what now? How can I follow what is happening and not only just in my IDE? Well, in AppStore Connect you can open your app, and select the Xcode Cloud tab and see more details. You can also view this in the Report Navigator (CMD + 9), you can see all the builds that are ongoing or have completed.

When the first build is completed, it should look something like this:

Conclusion

When the setup is done, you can send the app in TestFlight directly for external testing. There is no need for another CI anymore; unless it is important for the company you work for the have the same CI for different platforms (e.g. iOS and Android).

Pros

Working with Xcode cloud is easy and fast. Everything is within the same IDE and access to the items are easilly controlled via AppStore Connect. The visualisation is great too, you can have access to the logs once builds are completed. There is no need for another CI nor Fastlane and everything exists within the same eco system that the developer is already used too.

Cons

I think the biggest drawback with Xcode Cloud is the dependency towards Apple and that the limitation that comes with it. The actions and post actions are decided by Apple, so if you want to do something custom you’ll have a harder time. There are no “run script” post actions or actions for that matter. That being said, there is a possibility to setup a custom webhook to a service of your choice to be informed about specified events happen. You can set this up in AppStore Connect > Your app > Xcode Cloud tab > Settings > Webhook, that said page looks like:

This also brings me to my second point… no Fastlane. Although Xcode Cloud takes away a lot that fastlane does, such as Scan, Deliver, Match ect… there is still a lot that Fastlane can do which Xcode Cloud doesn’t.

One thing I noticed while writing this article, there is no possibility for a Status Badge in your github repo with the branch status. If you would like to show in your public or private repo that the latest on your main branch has tested and build successfully, you can’t.

Next up

Now that you’ve setup your first project with Xcode Cloud, you can continue connecting Slack to your workspace. Learn more about how to do this here: