Connect your project to Xcode Cloud

Jesse Wesson: Hi, my name is Jesse, and I'm an engineer on the Xcode Cloud team. Today, we're going to talk about how to connect your Xcode project and source code to Xcode Cloud using cloud and self-hosted source code management tools.

We're going to start by doing a brief intro to source control management and how it can help you be more productive. Then we'll cover how Xcode Cloud accesses and uses your source code. We'll then focus on how to use Xcode Cloud with a self-hosted source code management tool like GitHub Enterprise. We'll finish up by going over some common project maintenance steps. Let's get started with a brief intro to source control and why you may want to adopt it. Continuous integration tools like Xcode Cloud and source control levels up your development practices, helping you to take on the complexity of feature development and accelerate your delivery of high-quality apps to the App Store. Let's go over a couple of ways source control can help your development work. One of the benefits is that it tracks your changes over time, so you can try something out, but always go back and restart from a previous change. Source control can also help you when you need to context switch. In this example, we're working on our next major release, but we just received a bug report that we want to address. Source control allows you to easily go back to your released version and create a new branch where you can make the needed bug fix. Git is one of the most commonly used source control systems and is fully integrated into Xcode and Xcode Cloud. Source control management providers, also known as SCM providers, have created great platforms to host your Git repositories and help you collaborate with others. Xcode Cloud works with the three main SCM providers: BitBucket, GitHub, and GitLab. You can integrate Xcode Cloud with these SCM providers to create workflows that respond to events, like when you push changes to a branch or you create and update a pull request. To learn more about this, check out "Meet Xcode Cloud" from WWDC21. Let's check out how Xcode Cloud accesses and uses your source code. Xcode Cloud was designed with privacy and security at its core. Your data is encrypted in transit and at rest, using industry-standard strong encryption protocols. This includes the encryption of all your build artifacts. The foundation of Xcode Cloud's privacy and security is our ephemeral build environments, which are protected by strong and secure isolation boundaries. For source access, Xcode Cloud is using secure HTTPS connections to communicate with your SCM providers, which we'll go through next. Let's dig into how the Xcode Cloud source code flow works. Every time a workflow runs and your build is started, Xcode Cloud creates one of these temporary environments. Before anything can be started, though, your source code is pulled down to this temporary environment. Xcode Cloud does this by performing a git clone operation using your remote repository on the configured SCM host. Once this completes, then the build action can be started and any custom CI scripts you've included in your repository will be run. For more information on custom CI scripts, check out "Create Practical Workflows in Xcode Cloud" from WWDC23. Now let's go through how we connect Xcode Cloud to GitHub Enterprise. Whether your project is hosted in the cloud or is self-hosted, Xcode Cloud will guide you through the onboarding steps to connect to your source repository. This includes granting Xcode Cloud access to your SCM provider, which takes just a couple of clicks through these web pages. Self-hosted projects need a bit more information, which we'll detail next. For this, we're using GitHub Enterprise to host the Backyard Birds app. You can get started with onboarding by clicking on "Get Started" in the Cloud tab. This will start the onboarding dialog, where you'll first be asked to choose the app or framework you want to connect. After we select the Backyard Birds app, we'll be given a chance to customize our first workflow. We're going to stick with the default one for this example. After choosing the workflow, we'll need to grant access to our project on the SCM provider. By clicking on Grant Access, Xcode will open up App Store Connect in our web browser. In App Store Connect, you'll be asked which SCM provider you're using. Since we're using GitHub Enterprise, let's choose that one. It'll then take you through the steps to grant access to your SCM provider. In order for Xcode Cloud to communicate with self-hosted SCM providers, some configuration is needed. The steps will vary with each SCM provider. As we're using GitHub Enterprise, we need to install the Xcode Cloud GitHub app on our server. Oh, it looks like we hit a connection issue. This can happen when your SCM instance -- in this case our GitHub Enterprise server -- is not accessible to Xcode Cloud. In order for Xcode Cloud to interact with your SCM provider, it needs to connect using Secure HTTPS over port 443. This means we need to update our server and network configuration to allow connections from the Apple-owned and managed IP address range. Inbound HTTPS traffic will be configurable in the cloud provider settings you're using to host your SCM instance. The IP address ranges are listed in our "Requirements for using Xcode Cloud documentation." Once we've updated those settings, we can pick up where we left off and authorize the Xcode Cloud GitHub app. We then need to pick which repositories Xcode Cloud will have access to. In this example, we're choosing all repositories, and now we click Install. Success! Xcode Cloud is connected to our self-hosted GitHub Enterprise instance. And this is now reflected in Xcode as well. We can now create any number of workflows to build, test, and deploy our app. As long as your SCM provider doesn't change, you won't have to go through these steps again. However, as your project grows and evolves, you may need to change where your source is hosted. There's a couple of steps needed to help keep Xcode Cloud connected. In the case where your whole project has moved to a new SCM provider, you can update the primary repository for your product. From the Settings page for your Xcode Cloud product, you can click on the More Options button and then click Change URL. When changed from here, this will update all of your Xcode Cloud workflows, so we'll ask you to confirm this. You can then enter the new URL for your source repository and click Next. Your primary repository is now set to this new source repository. Sometimes you may want to change the source repository for just one workflow. You can do this from the Workflow Editor, which can be found under the More button on the Manage Workflows page. From the Workflow Editor, under Primary Repository, you have the option to change it for this specific workflow. Here, you can enter the URL of your new repository. And that's it! With these couple of steps, you can keep Xcode Cloud connected to your project. Xcode Cloud and source control are great partners that help to accelerate your delivery of high-quality apps. We went over how it connects to GitHub Enterprise, but it also works great with cloud-based and self-hosted source repositories on BitBucket, GitHub, and GitLab. When these tools are combined, they can take work off of your plate and allow you to focus on the things that are most important to you and your customers. Thanks and happy coding!