Last updated at 2020-09-02

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 installed dependencies. 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 7 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:

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 /steps-and-workflows/disable-a-step-by-condition/ guide.

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 Run CocoaPods install or Carthage Steps). You should not put the Cache:Pull Step BEFORE the Git Clone Repository Step.

The Cache:Push Step should be the very last Step in the Workflow. In the Cache paths input, you can set the paths to the content you want to add to the cache archive. The default value is an Environment Variable that collects content that the different Steps cached - for example, the aforementioned Run CocoaPods install Step does have a caching function, too.

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

Ignoring files and dependencies

You can tell the Cache:Push Step to ignore certain content: set the path or paths to the items in the Ignore Paths from change check input of the Step. Change checking means that the Step checks the cache paths against the cache archive, if it exists, and if their content is changed, the cache is updated. Ignoring from change checking means that the cache archive won’t be updated even if the content changes: the selected path will still be included in the cache archive but its content won’t change.

If you want to completely exclude a path or several paths from the cache archive, you must prefix the paths in question with !. If you don’t prefix the path with an !, the path will NOT get ignored from the cache archive.

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.

To ignore a path element, part of a path or exclude a full directory, check out these elements:

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

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.