メインコンテンツまでスキップ

Configuring the Build Cache for Xcode in non-Bitrise CI environments

The Bitrise Build Cache does not require using the Bitrise CI. You can use other CI/CD services and still take advantage of the cache to improve your Xcode build times.

To do so, you need to configure your CI environment to download the Bitrise Build Cache CLI during the build and then run the CLI to enable the Bitrise Build Cache.

You can also set this up with an AI coding agent instead of following the steps manually. See Getting started with AI.

Using GitHub Actions

There is a dedicated guide with GitHub Actions workflow examples: Configuring the Build Cache for Xcode in GitHub Actions.

On Bitrise Build Hub runners you don't need a token at all: the machine is already connected to your Bitrise Workspace, so the CLI authenticates itself. The steps below cover every other environment.

Selecting a tokenClick to copy link​

For a CI integration, use a workspace API token. It belongs to the workspace instead of to a person, so your builds keep working when someone changes roles or leaves the company.

A Personal Access Token also works, but it carries the roles of the user who created it and stops working when that user leaves the workspace.

On your own machine you need neither: the CLI signs you in through the browser and stores the credentials in the OS keychain. See Setting up in a local dev environment for the local guide of your build tool.

Configuring the cacheClick to copy link​

  1. Create a workspace API token and copy its value.

    Give the token at least the viewer workspace role: that is the lowest role that can access the Build Cache.

  2. Find your Workspace ID: open the Workspace settings page and select General settings on the left navigation menu. You can find and copy the slug from there.

  3. Set the following Environment Variables in your CI configuration:

    • BITRISE_BUILD_CACHE_AUTH_TOKEN: the workspace API token.
    • BITRISE_BUILD_CACHE_WORKSPACE_ID: the Bitrise workspace slug.

  4. Add the following script to your CI configuration before the step you want to speed up:

    Environment

    Make sure to run the script in the same environment as the Xcode command(s) you want to speed up.

    If you already have a workflow set up for other build tools (for example, Gradle), you need to make sure to install the latest CLI version that supports Xcode, i.e. at least v1.0.0.

    The Xcode Compilation Cache requires Xcode 26 or later version.

    #!/usr/bin/env bash
    set -euxo pipefail

    # download Bitrise Build Cache CLI
    curl --retry 5 -sSfL 'https://raw.githubusercontent.com/bitrise-io/bitrise-build-cache-cli/main/install/installer.sh' | sh -s -- -b /tmp/bin -d

    # run the CLI to enable Bitrise build cache for Xcode
    /tmp/bin/bitrise-build-cache activate xcode --cache --cache-push

See also