Last updated at 2021-03-25

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 first, called Cache: Push, stores your content in the build cache; the other, called Cache: Pull, pulls the cache the next time you run a build.

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.

When does the build cache gets auto-deleted?

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.

Getting started with caching

To get started, add two Steps to your Workflow:

These two Steps are required to access the cache in your builds. However, some other Steps have their own built-in caching function which is usually enabled by default. Always check whether a Step that handles dependencies or generates any files during a build has an input related to caching. A few examples of Steps with their own caching function:

What gets cached?

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.

The Step is not submitting a new cache archive every time, only if the files to be cached have changed compared to the previously cached state.

Pull request builds

By default, if you run a build that is triggered by a pull request, the Cache:Push Step won’t work: in this case, a pull request build can only read the build cache but can’t update it!

We strongly recommend that you do not change this! From a security perspective, the best practice is to never allow pull request builds to alter anything that can affect other Bitrise builds.

If you absolutely must change it, you need to use a run_if expression in the app’s bitrise.yml file. Read more about run_if expressions in our Enabling or disabling a Step conditionally guide.

Using caching in your builds

The basics of using the cache in your builds are simple and it can work out of the box, depending on your Workflows: you just have to use the two dedicated Steps.

  1. Add the Cache:Pull Step right before you need the cache. For example, in the case of an iOS app, you can insert the Cache:Pull Step between the Git Clone Repository and the dependency installer Steps (such as the Run CocoaPods install or the Carthage Steps). You should not put the Cache:Pull Step BEFORE the Git Clone Repository Step.
  2. Add the Cache:Push Step as the last Step of the Workflow.

For simple use cases, that’s it, that’s all you have to do. These Steps work out of the box alongside Steps with their own caching function. But if you wish to learn more and create your own caching configuration, read on!

You can find example build cache configurations/guides at our build-cache discuss page.

Including files and folders in the build cache

As mentioned before, every file and folder 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 this input. If you use Steps that have their own in-built caching function, you don’t have to worry about specifying files and folders unless you have a specific use case.

To check whether a Step has a caching function, take a look at their inputs. If there’s no input to turn caching on and off, the Step in question doesn’t have its own caching function.

To include files from Steps that do not have their own caching function:

  1. In your Workflow, open the Cache:Push Step.
  2. Find the Cache paths input.
  3. Add the path or paths for files and folders that you want to include in the cache. You can use either an absolute path, or a path relative to the root of your repository.

Ignoring files and dependencies 

You can also tell the Cache:Push Step to specifically ignore certain content. Ignoring means one of two things:

You can choose either option for any of your files or folders.

To ignore certain files or folders:

  1. In your Workflow, open the Cache:Push Step.
  2. Find the Ignore Paths from change check input.
  3. Add the path or paths for files and folders that you want to ignore. You can use either an absolute path, or a path relative to the root of your repository.
    • If you want to completely exclude a given path from the cache archive, prefix the path with !. For example, !my/path/.
    • If you want to exclude a given path from change checking, just add the path without any prefix. If a path is located inside an ignored cache path item and the path is NOT prefixed with an !, the path will be included in the cache archive, but it will not be checked for changes. For example, if you add my/path/ to the input, the path directory will be included in the archive but it will not be checked for changes.

You can, of course, specify certain patterns in the paths, too. For example:

Tips on ignoring paths

You can’t ignore a path which results in an invalid cache item. For example, if you specify a/path/to/cache path to be cached, you can’t ignore a/path/to, as that would ignore every file and wouldn’t check for changes, hence no fingerprint could be generated for a/path/to/cache. This won’t fail the Step: you’ll simply receive the following warning: No path to cache, skip caching...

You can, however, ignore paths inside a cache path. For example, if your path is a/path/to/cache, you can ignore a/path/to/cache/.ignore-me, unless that’s the only file inside a/path/to/cache.

Downloading and deleting caches

You can download and delete caches for every branch which generated a cache.

  1. Open your app on Bitrise.
  2. Go to the Settings tab.
  3. Scroll down to the Manage Build Caches section.
  4. Click the Manage button.

You can see the size of the caches and the last time a given cache was used in the popup window. You can download or delete any of the cache archives, or all of them.

Delete a single branch’s cache

If you only want to delete the cache which is related to a single branch, you should also delete the default branch’s cache too! This is because if a build runs on a branch which doesn’t have a cache, the Cache:Pull Step will get the cache of the default branch.

Technical notes

The Build Cache feature is split into two parts:

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 files that are normally downloaded from a CDN or cloud storage might not save you any time as downloading them from the Bitrise build cache storage could take as much or more time as simply downloading the files from their usual location.

Storing a resource or dependency in Bitrise Build Cache might help if you have reliability issues with the usual download location.