Every single Bitrise build runs on a clean virtual machine. This means that normally, without caching, everything must be done from scratch on the virtual machine, including, for example, installing your dependencies.

With caching, you can preserve the contents of selected files and directories, including, for example, installed dependencies or files generated during the build. And it’s very easy: you just need to use two Steps in your Workflow:

  • The Cache: Push Step stores your content in the build cache.

  • The Cache: Pull Step pulls the cache the next time you run a build.

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 cache is stored as a single archive file: if the content of the cached paths changes in any way, the entire file gets updated. Every branch of your repository on which you run a build will have its own cache archive. Please note that the cache does not get used if you try to use it on another stack then the one it was generated on.

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. Cache is not available for PR builds of public Bitrise apps.

Every folder and file specified in the Cache:Push Step’s Cache paths input 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 caching in your builds

Technical notes on caching

The 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.

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.