Explore Xcode Cloud workflows

Hello, and welcome to this session on Xcode Cloud workflows. My name is Justin, and I'm an engineer with the TestFlight team, and along with my colleagues, Wesley and Kevin, we're here to introduce the ins and outs of creating your workflows in Xcode Cloud. Workflows are at the heart of Xcode Cloud and drive the continuous integration that enables you and your team to automate building, analyzing, testing, archiving, and distributing your apps and frameworks. They are flexible and extensible, so you can customize workflows around your team's existing development and distribution processes. And with Xcode Cloud, workflow management is integrated into the Apple developer tools you already use: Xcode and App Store Connect. In this session, let's break workflows down into their specific components. First, we'll walk through how to configure the conditions that automatically run your workflow. Then, we'll talk about the options for setting up your environment. We'll also show you how to create multiple actions for the tasks you want to automate, along with actions to run afterward, like sending notifications about your builds, or automatically deploying those builds to TestFlight. Finally, we have some strategies for different workflows you may find useful and super convenient to boost your team's collaboration and productivity. We have a lot to cover, so let's get started. Let me hand it off to Wesley.

Thanks, Justin! I'm collaborating on an app called Fruta with members of my developer team. It is already up and running on Xcode Cloud. If you haven't yet seen the session "Meet Xcode Cloud," be sure to check it out to learn about setting up your first workflow. Right here, integrated in Xcode's Report Navigator, is a new Cloud tab, where I see the workflows and builds from my team. When I onboarded the Fruta app, it created a default workflow for me that builds the main branch. This workflow has been working great for us, but because we're a team that also uses pull requests, I'd like to create a pull-request-specific workflow that my team can leverage. I'd like it to run every time a pull request is created by anyone on my team, analyze, test, and archive my app, notify my team when a pull-request build finishes, and deliver a version of my app to members of my team so they can test out the features before they're merged into our main integration branch. Creating a workflow is easy to do. Under the Product menu, I can go to Manage Workflows, click Plus, and select my app.

This will bring track a new workflow editor. A workflow is made up of several configurable components. Here's the general section, where I can name my workflow. I'm gonna name this "Pull Requests." If I were on a team where only a small number of individuals are responsible for making changes to our workflows, I can choose to restrict editing to prevent unintended updates that might impact our team. By default, Xcode Cloud sets the primary repository and project information with the knowledge of my local settings, but if I ever decide to move my primary repository or migrate from an Xcode project to a workspace, I can change those settings here. Next, let's take a look at the Start Condition section. This is where I can define when I want my workflow to run.

Xcode Cloud has a number of condition types. For this workflow, I want to set its start condition to run for all pull requests that intend to merge into the main branch. To do that, I can select from the Type menu and choose Every Change to a Pull Request. This condition type allows me to specify the source and target branch.

I'll set the source branch to Any Branch and the target branch to Main.

Now every time a team member creates a pull request against Main and makes changes to it, Xcode Cloud will automatically run this workflow. When building pull requests, Xcode Cloud will now build and test the merge of the source and target branch together, so my team members can be confident and know the real impact of their changes with the rest of the team. I can also narrow those conditions to specific files or folders and choose to set whether or not I want to auto-cancel any previously running builds when the workflow runs. This is useful if I push one commit on top of another in quick succession. Every Change to a Pull Request is just one of the start conditions that you can set for a workflow, and depending on the needs of your team, we have other condition types that you can configure to meet those needs. Every Change to a Branch will always build the source branch and will ignore any pull-request states. Every Change to a Tag will build whenever new tags are created. On a Schedule will build a branch of your choosing on a recurring schedule that you can choose. This is great if you have long-running tests that you want to run on occasion. Now that I have configured the start condition, which dictates when this workflow will run, let's configure the Environment section, which dictates how the workflow will run. Xcode Cloud runs on Apple's Cloud Infrastructure and makes available various macOS and Xcode versions.

To choose your Xcode and macOS version, you just need to select it from a menu. You can also set your workflow to point to the Latest Release or Beta version, so you could always build or test on the latest software. As developers, we all care deeply about our productivity, and a large part of that is the performance of the tools we use. Many of you will be working on large projects with many files and deal with potentially long build times. Just as locally within Xcode, you have the option to build your changes incrementally by just building the files that have changed. You also have this option in Xcode Cloud. This typically leads to faster builds. However, there are times when you might wanna perform a clean build instead. This is important to make sure everything is functioning in your final build, and is also required to produce builds that could be deployed to External Beta Testers with TestFlight or to submit to the App Store. In the environment section, I have the option to select Clean. Since this is a pull-request workflow, I'll leave it unchecked so I can take advantage of the performance benefits. Every team works in its own unique way, and teams need their tools to have the flexibility to be able to work the way they want to work. Xcode Cloud provides options to do what we believe are the most common development tasks out of the box. However, it also provides a range of options for extensibility. This extensibility allows you to connect Xcode Cloud with the other tools and systems your teams use to get your work done. Xcode Cloud offers a comprehensive API to access your data, configure workflows, and kick off builds. In addition to the existing scripting options that Xcode provides, Xcode adds the ability to create custom scripts that run on the devices which are performing your builds and tests. In the Environment section, I can specify environment variables that Xcode Cloud makes available to custom scripts. This is useful for configuration and secrets that I don't want to check into the source code repository.

I also have the ability to mark an environment variable as secret to provide an extra level of protection. You can find further information on this in the "Customize your Advanced Xcode Cloud Workflows" session or in our documentation. So far, we've shown you how to configure when your workflows run and when they run. What environment should they run in? Next, let's talk about actions. Actions define the work that you want the workflow to do for you and your team every time the workflow runs. The key actions you could ask Xcode to perform locally are now all available to you within Xcode Cloud: building, running static analysis, testing, and archiving. The actions I want to set up are the Archive, Test, and Analyze actions. Let's start by adding the Archive action by clicking the plus icon by Actions and selecting Archive.

I need to select the platform and the scheme I want to create an archive for. It already pre-selected the iOS platform and the iOS scheme, which is exactly what I wanted. I also have the option to register for TestFlight or make it ready for App Store distribution, but more on this later. You may notice that I didn't have to manage provisioning profiles or code-signing identities. Xcode Cloud handles this automatically for you. To learn more about this, check out the session "Distribute Apps in Xcode with Cloud Signing." Now that the Archive action is set up, let's focus our attention on the Test action. Testing your apps is an incredibly important part of the development process. Not only does it help ensure your users experience fewer bugs, but it can speed up your development process by giving you confidence in the changes you are making. However, sometimes it can be cumbersome and slow to run your tests locally, and sometimes, you might just forget. By setting up a workflow with testing in Xcode Cloud, tests run in a stable, reliable, and reproducible environment. They run in the background while you are doing other work, freeing up your local environment, and they run automatically, freeing you up of having to remember to manually run them. To add a Test action, I just need to click on the Plus button and select Test.

For Test actions, I can choose to make them required to pass or not. Marking the action as required means that the overall build will fail if this Test action fails. If I were building up my test suite, I may choose to set this as Not Required to Pass so it doesn't affect the overall build state. When it comes to choosing which tests to run, I have a couple of options. I can choose Use Scheme Settings to reference the settings in my Fruta iOS scheme, or I can select a particular test plan if I want to hone in on a certain set of tests. Once I have that set, all that is left to do is to choose the simulators I want to run my tests on. Xcode Cloud provides a recommended option, which is a collection of simulators with different screen sizes. The recommended option always tests against the Xcode selected in the Environment section, but if I choose specific simulators, I can also select from a list of older OS versions.

The last action I want to run is the Analyze action. The compiler is capable of automatically finding many classes of bugs and warning us about them. Heeding and fixing these can save us a great deal of development time compared with tracking down these issues at run time and will give our users a much more stable and bug-free experience with our app. However, because running static analysis is not part of our typical local iterative development workflow, many of us forget to run it, only to see the issues mount up across the team over time. With Xcode Cloud, you could make sure that static analysis runs every time you make a code change. To add an Analyze action, I'll click on the Plus button, and select Analyze.

Like tests, I have the option to mark static analysis issues as Required to Pass or not. Right now, I only want to monitor the results of static analysis, so I won't mark it as Required to Pass.

The last action is the Build action. On occasion, you might need to run a simple Xcode Build action. This might be useful to make sure a particular secondary build configuration or scheme still compiles, or perhaps to ensure that a framework that is part of your app can be built on its own. Now that I've set up the Archive, Test, and Analyze actions for my pull-request workflow, I'll hand it off to Kevin to add post-actions to this workflow. Thanks, Wesley. With Xcode Cloud workflows, you have the ability to configure post-actions. Post-actions run after all Build, Analyze, Test, and Archive actions have completed. The post-actions you can configure with Xcode Cloud are sending notifications and deploying with TestFlight. Let's first talk about notifications. There are two types of notification events you can send. The first is when a build succeeds. You have the option to send notifications for all build successes; only fixes, which is when a branch or pull-request build transitions from failing to passing; or don't notify. The other notification event is for when a build fails. You can send a notification for all build failures; only breaks, which is when a branch or pull-request build transitions from passing to failing; or don't notify. For this workflow, I want to notify my team when pull-request builds finish. Below the Actions section is post-actions. To add a Notification action, I'll click the Plus button and select Notify.

I'll leave All for Build Success and Build Failure. Below the Notification Events, I have a couple of options for where to send notifications. Xcode Cloud integrates with the popular collaboration tool Slack. Once a Slack account has been authorized, I can click the Plus button to bring up a list of channels.

I'll select the "ci-builds" channel and click OK.

I also have the option to add email addresses. By default, all users automatically receive notifications for the builds they kick off, so you don't have to add them to this list. However, if you have a group email or if you have users who want to receive builds they did not kick off, you can add their email here. Finally, I'd like to share with you one of my favorite features of Xcode Cloud Workflows: the ability to automatically deploy with TestFlight. And now, with TestFlight on Mac, you can deploy to every platform Apple has to offer. There are two TestFlight deployment options with Xcode Cloud. Deploying to internal testers has been enhanced to quickly send builds to members of your development team. Because they're members of your team, they can receive builds that were produced from pull requests and builds without Clean selected. If you use TestFlight today, External Testing and App Store is equivalent to what you already know. It's recommended for candidate and release branches and can be distributed to external testers and the App Store, subject to beta app review. TestFlight is a great way to get builds of your app onto devices of your teammates and beta testers outside of your organization. You can configure a workflow to automatically deploy a build to any TestFlight group you have. You manage your TestFlight groups the same way you do today, in App Store Connect under the TestFlight tab. Here, I have multiple internal and external groups, and each one of them is available to me in my workflow. To automatically deploy with an internal TestFlight group, you'll need to do three things. First, you'll need to add an Archive action. Next, you'll need to set the Deployment option on the archive to Internal Testing. Finally, you'll need to add a TestFlight Internal Testing post-action. Let's configure our workflow to do just that. I want this workflow to automatically deploy to my QA team. To do that, first, I'll click on the Archive iOS action, and select TestFlight Internal Testing Only.

Doing this means my builds will be available in TestFlight. This is great if I don't want to automatically send builds to anyone, but keep the option to do it later from the TestFlight section on App Store Connect. For this app, I also want to deploy to my colleagues automatically whenever a build is produced. To do that, I need to add a TestFlight post-action. I'll click the Plus button beside Post-Actions, and add TestFlight Internal Testing.

The Archive iOS artifact is pre-selected, which is what I want. I'll hit the Plus button to add an internal group.

Finally, I'll select the QA team.

Now members of my QA team can verify and test all features before they're merged onto the Main branch. Sending a build to testers outside of your organization with TestFlight External Testing is a great way to get feedback on your app and its features before submitting to the App Store. This way, you can gain confidence in your changes from a wider set of users and potentially make changes and fix issues before it's released to the App Store. To deploy with TestFlight External Testing, a few more conditions need to be set. Select a single branch in the start condition. This ensures consistency in the builds you intend to send to your external beta testers. Next, select Clean in the Environment section. This guarantees your code will be built from scratch, without using derived data. Lastly, set the Deployment setting in your Archive action to TestFlight and App Store. After all that is set, configuring the TestFlight External Testing post-action is similar to configuring TestFlight Internal Testing. You simply add external groups that have been created in TestFlight. TestFlight External Testing also has the added ability to deploy to individual testers. We've just created a pull-request workflow in Xcode, but you can also create, edit, and manage workflows in App Store Connect. It's a great option if you're away from Xcode and need to make changes to your workflows. Now back over to Justin to make a few recommendations on the types of workflows you can create for your team. Justin? Thanks, Kevin. I think the Fruta QA team will love accessing builds faster with our pull-request workflow. So as you've seen, workflows have a lot of power and flexibility to model the way your teams work. You can create as many workflows as you need to get your work done. I know our team will create several. Kevin just showed you a workflow for pull requests, but here are a couple of ideas for more workflows you and your team can try out. To show your app to users outside of your development team, you might distribute to an external TestFlight group or submit your app to the App Store. The idea here is that I want to enforce high quality so my app's users have a great experience. I need to run a workflow on the branches designated for releases. It should execute a comprehensive battery of tests, archive the build, and, finally, deploy to an external TestFlight group and into the hands of users. To better illustrate, let me show you my Release Workflow. To make sure my workflow will build all of our future releases as well, I set the start condition to Every Change to a Branch on my Release branch. To be thorough, I want every build from this workflow to be generated from scratch, so I checked Clean in the Environment section. Doing so typically increases build times since everything is compiled again, but it gives us confidence that there are no issues caused by caching. Notice that I also selected specific versions of Xcode and macOS for this workflow. Pinning the tools down is an important part of converging and finalizing a release. To ensure that our app will work across the range of users' iPhones and iPads, I run our tests on a variety of simulators in the Test section. To distribute the build of our app via TestFlight, I included an Archive action and set the deployment preparation to TestFlight and App Store. To ensure our beta testers always get the most up-to-date build, I set up a post-action to deploy to our external TestFlight group. When new code is merged into our release branch, it gets automatically built, tested, and deployed to our beta testers. Now we can get feedback quickly on our changes while maintaining confidence that the quality remains high. Here's another workflow you might want to create that performs a deeper set of testing every night. My Overnight Testing workflow runs periodically, testing against multiple simulators to cover as many platforms as I need. Any test failures get reported to the QA team, and since the focus is entirely on testing, there's no need to deploy a build anywhere. I set my start condition to run this workflow every weeknight by choosing On a Schedule for a Branch as my start condition type with weekly frequency. Then, I selected my days as Monday through Friday at 1:00 a.m. In the Environment section, I selected the latest Xcode version to make sure our app builds successfully as new tools are released. I want to thoroughly test our app, so I selected a few test plans and simulators that are required to pass. I also want to run static analysis, so I added an Analyze action and also require that to pass. Should any of the previous tests fail, the QA team will find out with a Notify post-action. I set Build Success to Don't Notify, and Build Failure to All. My QA team has their own Slack channel, but I could also specify an email address. Either way, the QA team will find out about any build failures by the following morning. Running a workflow like this is a great way to save time since you and your team can keep developing during the day and leave Xcode Cloud to thoroughly test your app at night. And lastly, under the Product menu in Xcode is Manage Workflows, where I can take a look at all the workflows our team uses. I see the Overnight Testing workflow that I just created along with the workflows that Wesley and Kevin created earlier. As our project grows, I can add more, edit, or remove workflows to suit the team's needs. And that's it for our team's workflows. We've shown you how to create workflows for pull requests, how to configure actions for different platforms, how to distribute releases to TestFlight users, and how to set up overnight testing. But there are so many more things you could do with workflows. On top of that, you can even create and manage those workflows from App Store Connect. To learn even more about workflows, check out "Customize Your Advanced Xcode Cloud Workflows." If you haven't had a chance yet, watch "Meet Xcode Cloud" to learn how to onboard your project. There are also other great sessions that dive deeper into cloud signing and Xcode's new support for pull requests. Xcode Cloud gives your team the ability to create flexible, extensible workflows that can adapt to the way you work and help make sure the team consistently follows their development practices. I hope this session helps you create workflows to leverage as you and your team iterate development and deliver a high-quality app. Thank you for watching, and enjoy the rest of WWDC. [music]