Migrating from branch-based caching to key-based caching

Abstract

As of May 2025, Bitrise is starting to deprecate its branch-based caching in favor of the more efficient and flexible key-based caching system.

A 15 GB maximum cache archive size limit is going to be introduced to branch-based caching (matching key-based caching) during the deprecation process. Saving cache archives larger than 15 GB is going to fail and the cache Step will be skipped (the build itself won’t fail).

Please migrate to key-value caching which uses better compression and make sure you are caching only the relevant files.

If your builds are using smaller cache archives then the branch-based caching Steps will keep working but we still recommend migrating the key-based caching as it results in better caching performance in almost all cases.

This guide will help you transition your projects to the key-based caching infrastructure.

Differences between caching systems

Key-based caching is generally more efficient and far more powerful than branch-based caching. In the table, we compare the two caching methods based on their feature set.

Table 1. Differences Between Caching Systems

Features	Branch-based caching	Key-based caching
Cache scope	One cache per branch	Multiple caches identified by keys
Cache sharing across builds	Limited to same branch and stack	Can be shared across Workflows, branches, and stacks
Steps used	Cache:Pull and Cache:Push	The generic Restore Cache and Save Cache Steps Dedicated caching steps for six dependency managers
Expiration	Seven days without new build on branch	Seven days since last use
Fallback mechanism	Default branch cache used as fallback	Multiple fallback keys can be configured
Maximum cache archive size	No limit (until migration stated)	15 GB
Adding files/paths to the cache archive	Configured manually or by other Bitrise steps supporting caching	Configured manually or via the dedicated caching Steps
Ignoring files	`Ignore paths` parameter	No separate ignore list
Performance/speed	Slower (larger gzip archives and slower storage backend)	Faster (state-of-the art zstd compression and faster storage backend)
Dedicated caching Steps for dependency managers	Not available	Available for most dependency managers

Replacing branch-based caching Steps

There are two ways to use key-based caching: either via the generic Restore Cache and Save Cache Steps or via the dedicated caching Steps for specific dependency managers. We strongly recommend using the dedicated Steps, unless your dependency manager is not supported or you need some special configuration. For the detailed list of Steps, see: Dedicated caching Steps for dependency managers.

Using the dedicated caching Steps

For example, if you run Gradle in your build, you can cache Gradle dependencies with the dedicated Steps. The dedicated Steps usually don't need any further configuration: you just add them to your Workflow:

Replace the Cache:Pull Step with the Restore Gradle Cache Step in your Workflow. This Step will download your Gradle cache.
Replace the Cache:Push Step with the Save Gradle Cache Step. This Step updates the Gradle cache.

All key-based caching Steps follow a similar naming convention: the Restore Steps download the cache while the Save Steps update it. After you ran at least two builds with a key-based setup, you can find and download the cache archive from the Project settings page: Accessing key-based cache archives on the website.

Using the generic key-based caching Steps

If the dedicated caching Steps don't produce the desired results, consider using the generic Restore Cache and Save Cache Steps. You can configure these Steps to perfectly fit your needs. You can:

Cache recipes with the generic Steps

Check out our key-based cache recipes utilising the generic Steps: Advanced key-based cache recipes.

In this section: