Making dependencies available to Xcode Cloud

Review dependencies and make them available to Xcode Cloud before you configure your project to use Xcode Cloud.

Overview

Xcode Cloud combines the tools you use to create apps and frameworks: Xcode, TestFlight, and App Store Connect. However, your Xcode project or workspace may require additional dependencies or third-party tools to compile your code. For example, you may use a library created by the open source community or Swift package dependencies to reuse and share code between apps.

If Xcode Cloud can’t access a private dependency or a third-party tool, it won’t be able to successfully build your project. To avoid a failing build and save time when you start using Xcode Cloud, review your dependencies and make sure that Xcode Cloud can access them before configuring your project to use Xcode Cloud.

Use Swift package dependencies and Git submodules

Xcode Cloud supports Swift packages and dependencies that you manage using Git submodules without any separate configuration if their repositories are publicly accessible. If you use private dependencies, Xcode Cloud helps you access them. For more information on using them, see Grant Xcode Cloud access to private dependencies below.

Following the best practice for using Swift package dependencies in a CI/CD environment, Xcode Cloud doesn’t use automatic package resolution and instead relies on the Package.resolved file to resolve your dependencies. If you use Swift package dependencies in your project, make sure to include the Package.resolved file in your Git repository and commit any changes to it. Don’t include the file in your .gitignore file. Additionally, make sure the Package.resolved file resides at $filename.xcodeproj/project.workspace/xcshareddata/swiftpm/Package.resolved.

For general information on building Swift packages in a continuous integration and delivery environment, see Building Swift packages or apps that use them in continuous integration workflows.

Grant Xcode Cloud access to private dependencies

When you configure your project or workspace to use Xcode Cloud, Xcode detects the source code management (SCM) provider you use to host your code. It also detects the SCM provider for each private Git submodule, Swift package dependency, or Git repository you access in a custom script and helps you grant Xcode Cloud access to it. For example, if you host your code with Bitbucket Server and use a private dependency you host with GitLab, Xcode helps you connect both your Bitbucket Server and your GitLab account to Xcode Cloud.

If you add a new private package dependency that Xcode Cloud can’t access, the next build fails. To resolve the issue, navigate to the failed build’s build report, and let Xcode or App Store Connect help you connect Xcode Cloud to the dependency’s SCM provider.

Building your project may require access to more than one instance of your self-hosted SCM provider — a common case for large teams. For example, you may use two different GitHub Enterprise instances where one hosts your app’s code and the other hosts your dependencies. If this scenario applies to you, finish the initial onboarding workflow for the project in Xcode and connect the instance that hosts your app’s code, then let the first build fail. After the build failure, Xcode suggests a fix to connect the other instance.

Review third-party dependencies

If you use a third-party dependency manager like CocoaPods or Carthage, or require an additional tool to successfully build your project, you’ll need to make changes to your project or workspace before you can use Xcode Cloud.

Because third-party tools and dependencies require additional work, review and simplify your third-party dependencies before you configure your project or workspace to use Xcode Cloud. For example, you may be able to replace a dependency with a framework that Apple provides. Alternatively, see if its creator offers the dependency as a Swift package. If so, you can use the package and take advantage of the support for the Swift Package Manager without configuring Xcode Cloud to use a third-party tool.

If switching to a Swift package dependency or removing a dependency isn’t practical, follow the instructions below to ensure Xcode Cloud can access dependencies and required tooling.

Use a custom build script to install a third-party dependency or tool

The temporary build environment Xcode Cloud uses to perform a build doesn’t include third-party tools or dependencies. However, it includes Homebrew, an open source package manager you can use to install additional software. For example, you can use Homebrew to install dependency managers like CocoaPods or Carthage.

To install a tool with Homebrew:

Create a directory next to your Xcode project or workspace and name it ci_scripts.
Create an executable shell script, name it ci_post_clone.sh, and save it in the ci_scripts directory. For example, use the Shell Script template in Xcode to create the file, and then make it an executable by running chmod +x ci_post_clone.sh in Terminal.
Open the custom script in Xcode and add the necessary commands to install a tool with Homebrew.

For more information about custom build scripts, see Writing custom build scripts.

Make CocoaPods dependencies available to Xcode Cloud

CocoaPods is an open source dependency manager for Apple platforms. The temporary build environment that Xcode Cloud uses to perform a build comes with the tool pre-installed. If you use CocoaPods, first make sure you commit both your Podfile and the Podfile.lock file. Then, decide between one of the following options:

Add the Pods directory to your Git repository by committing it.
Exclude the Pods directory from source control by adding it to your .gitignore file.

If you commit the Pods directory and its contents, you won’t need to install dependencies managed by CocoaPods to enable Xcode Cloud to build your project or workspace. It’s worth noting, however, that your source code repository takes up more space when adding the Pods directory. Additionally, remember that committing binary dependencies can affect the performance of your Git repository. It’s a general issue when using Git and not specific to Xcode Cloud.

If you choose to exclude the Pods directory from source control, you’ll need to install dependencies managed by CocoaPods using a custom build script. The benefit, however, is that the source code repository takes up less disk space and doesn’t slow down your Git repository. To install CocoaPods dependencies using a custom build script:

Create a post-clone script as described in Use a custom build script to install a third-party dependency or tool.
Add the command to the script that installs CocoaPods dependencies. The following code snippet shows a basic script to achieve this:
```
#!/bin/sh

# Install dependencies you manage with CocoaPods.
pod install
```

Make Carthage dependencies available to Xcode Cloud

Carthage is an open source dependency manager for Apple platforms. However, the temporary build environment that Xcode Cloud uses to build your project doesn’t come with the tool pre-installed. To facilitate projects that rely on the carthage copy-frameworks command — most projects do — , install Carthage using a custom build script:

Create a post-clone script as described in Use a custom build script to install a third-party dependency or tool.
Add the necessary commands to the script to install Carthage using Homebrew and build your Carthage dependencies.