About caching

The caching will tar all the cached directories and dependencies, and store them securely in Amazon S3.

When does the Build Cache gets auto-deleted?

The Build Cache, related to a specific branch, expires/is auto-deleted after 7 days, if there’s no new build on that branch in the meantime. This means that if you do builds on a specific branch every day (more frequently than a week), it’ll never expire/won’t get deleted automatically. If you don’t start a build on that specific branch for more than 7 days, then the related cache will be removed, and your next build will run like the first time, when there was no cache for that branch yet.


Bitrise steps for caching

All you need to get started is adding two steps to your Workflow:

You should add the Cache:Pull (download) step right before you’d use 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 (for example, the Run CocoaPods install or Carthage steps). You should not put the Cache:Push step BEFORE the Git Clone Repository step.

The Cache:Push step should be the very last step in the workflow.

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

Ignore files/dependencies

You can set the path to the items you want the cache to ignore in the Ignore Paths from change check field.

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

Download and delete caches

You can download and delete caches for every branch which generated a cache in the Manage Build Caches section of your app’s Settings tab.

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! For more details, see the If a build runs on a branch which doesn’t have a cache yet, it’ll get the main/default Branch’s cache section.

You can see the size of the caches and the last time a given cache was used in the popup window.

Technical notes

Build Cache feature

The Build Cache feature is split into two parts, the Build Cache API and the Steps.

The Build Cache API is a simple API, with only one responsibility: you can request a download or an upload URL from the API. It also makes sure that you have the required access rights to the resource (Build Cache Archive), but other than that its only responsibility is providing the secure - time-limited and expiring - download and upload URLs. It does not process the files.

The Steps are the place where the “magic” happens. The whole logic of comparing caches (to see if there was any relevant change) and creating the cache archives is done by the Steps. This also means that you can write your own Steps and implement your own comparison and compression logic. The Step just 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.

A couple more handy tips:

The cache might or might not be available

You should write your code in a way that it won’t fail if the cache can’t be accessed.

The cache is downloaded over the internet

This means that if you store files which are downloaded from a CDN/cloud storage, you might not see any speed improvement, as downloading it from the Bitrise Build Cache storage will probably take about the same time as downloading it from its canonical CDN/cloud storage location.

When to store a dependency in Bitrise Build Cache?

Storing a dependency in Bitrise Build Cache might help if you have reliability issues with the resource’s/dependency’s canonical download location. Popular tools/dependencies might get rate limited (for example, PhantomJS). CDN servers might have availability issues, like jCenter/Bintray. Here are a few examples: #1, #2, and #3. If that’s the case, storing the dependency in Bitrise Build Cache might help you. It might not improve the build time but it definitely can improve the reliability.

The cache is stored as one archive file

So if you have multiple paths you want to cache and any of the paths gets updated, it’ll update the whole cache archive, including all the paths you cache.

If a build runs on a branch which doesn’t have a cache yet, it’ll get the cache of the main/default branch

The build on a non-default branch, to speed things up, can access (read-only) the cache of the primary branch, until a successful build is found on the new branch. Once a build on the new branch pushes a cache, new builds on that branch will get the cache of the branch. Caches are stored and available for every branch separately.

You can see which is your default branch if you click the Settings tab of your app.

If a build was started with a code push, the cache will be available on the push branch and will be pulled from the same push branch. If you start a Pull Request (PR), the cache of the PR source branch will be pulled and pushed to the same source branch. In the case of a tag event, there is no code change so there is nothing to cache.