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 Bitrise.io Cache: Push, stores your content in the build cache; the other, called Bitrise.io 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.
Getting started with caching ⚓
To get started, add two Steps to your Workflow:
- Bitrise.io Cache:Pull Step to download the previous cache.
- Bitrise.io Cache:Push Step to check the state of the cache and upload it if required.
Add the Bitrise.io Cache:Pull Step right before you need the cache. For example, in the case of an iOS app, you can insert the Bitrise.io 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 Bitrise.io Cache:Pull Step BEFORE the Git Clone Repository Step.
The Bitrise.io 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 Bitrise.io 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:
*replaces a path element, for example,
**replaces a part of the path, for example,
/excludes a full directory if
/is placed AFTER a directory, for example,
/my/full/pathwill look like this
Downloading and deleting caches ⚓
You can download and delete caches for every branch which generated a cache.
- Open your app on Bitrise.
- Go to the Settings tab.
- Scroll down to the Manage Build Caches section.
- 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.
Technical notes ⚓
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.