Skip to main content

Branch-based caching

In branch-based (legacy) caching, every branch of your repository on which you run a build will have its own cache archive. You can only use a cache archive on the same stack it was generated on. The cache is stored as a single archive file: if the content of the cached paths changes in any way, the entire file gets updated.

Build cache expiry

The build cache, related to a specific branch, expires after seven days which means it is automatically deleted - but only if there’s no new build on that branch in the meantime. This means that if you do builds on a specific branch more frequently than a week, the cache won’t get deleted. If you don’t start a build on that specific branch for more than seven days, then the related cache will be deleted, and and your next build will run like the first.

The default branch cache is used as fallback

If a branch does not yet have a cache saved, the default branch’s cache will be used. Caching is not available for pull request builds of public Bitrise apps.

Every folder and file specified in the Cache paths input of the Cache:Push Step gets cached, unless the Step is configured to ignore certain folders and files. In most cases, you don’t have to change the value of this input: you only need to add anything here if you want to cache files generated by a Step that doesn’t have its own caching function. A few examples of Steps with their own caching function:

  • Xcode Archive & Export for iOS

  • Android Build

  • Gradle Runner

  • Run Cocoapods install

  • Brew install

To find out how access the cache during builds, check out Using branch-based caching in your builds.

Technical notes on branch-based caching

The legacy, branch-based build cache feature is split into two parts:

  • The Build Cache API.

  • The Steps.

The Build Cache API is a simple API. It makes sure that you have the required access rights to the resource (the build cache archive), and provides secure - time-limited and expiring - download and upload URLs. It does not process the files.

The Steps are responsible for executing the logic of comparing caches and creating the cache archives. This means that you can write your own Steps and implement your own comparison and compression logic. The only requirement is that the Step has to use the Build Cache API to get download and upload URLs. There’s no restriction on the cache file format or on its content.

Archive size limit

The size of a single cache archive cannot exceed 15 GB.

Read more about developing your own Step in our dedicated guide: Developing a new Step.

The cache might not be available

It’s always a good idea to write your code in a way that your builds won’t fail if the cache can’t be accessed. Also keep in mind that the cache is downloaded over the internet. Storing a resource or dependency in Bitrise build cache might help if you have reliability issues with the usual download location but it doesn't necessarily save you time.