Using key-based caching in your builds

Your cache entries are retained for seven days since the last use. If they're not used in your workflows for a continuous period of seven days, they will be automatically removed.

If you run out of your cache storage allowance, the Least Recently Used (LRU) cache entries on your app will be replaced with any new ones produced. LRU is a cache replacement algorithm that removes the least recently used data in order to make room for new data. This might mean that your cache hit rate could reduce if the replaced cache entries are needed by any Workflows. We recommend upgrading to a higher plan to get more storage so that you don't lose any cache entries that might be needed by your Workflows.

Once a cache archive has been created, you can access it on the App Settings page: Accessing key-based cache archives on the website.

Both key-based caching Steps support using template elements in their Step inputs. The Steps evaluate the key template at runtime and the final cache key to be used can change depending on the build environment or on certain files in the repository.

- save-cache@1:
    inputs:
    - key: npm-cache-{{ checksum "package-lock.json" }}
    - paths: node_modules

- save-cache@1:
    inputs:
    - key: gradle-cache-{{ checksum "**/*.gradle*" "gradle.properties" }}
    - paths: AndroidApp

- save-cache@1:
    inputs:
    - key: npm-cache-{{ getenv "BITRISE_BUILD_NUMBER" }}
    - paths: node_modules

It's possible to define more than one key in the Cache keys input of the key-based caching Steps. You can specify additional keys by listing one key per line. The list is in priority order, so the Step will first try to find a match for the first key you provided, and if there is no cache stored for the key, it will move on to find a match for the second key (and so on).

inputs:
  key: |
    key-1
    key-2
    key-3

In addition to listing multiple keys, each key can be a prefix of a saved cache key and still get a matching cache archive. For example, the key my-cache- can match an existing archive saved with the key my-cache-a6a102ff. We recommend configuring the keys in a way that the first key is an exact match to a checksum key, and to use a more generic prefix key as a fallback:

inputs:
  key: |
    npm-cache-{{ checksum "package-lock.json" }}
    npm-cache-

You might not want to update a cache archive every time you run a build. By skipping caching, you can:

If the cached content did not change during your build at all, the Save cache Step can automatically skip compressing and uploading the cache. To make this work, you need to make sure your cache archive has a unique cache key that changes whenever the contents of the cache change: in practice, this requires a dynamic key with a checksum and a file that describes the cached content. The checksum will be calculated based on the contents of the file; if the file remains unchanged, so does the checksum.

We strongly recommend configuring the Step in a way to take advantage of this feature. Follow the steps below, or skip ahead to our YAML example.

If everything is configured correctly, if the keys in the two caching Steps match, the cache archive will not be updated.

workflows:    
  caching:      
    steps:      
    - restore-cache@1:          
        inputs:          
        - key: gradle-cache-{{ checksum "**/*.gradle*" "gradle.properties" }}      
    - save-cache@1:          
        inputs:          
        - key: gradle-cache-{{ checksum "**/*.gradle*" "gradle.properties" }}          
        - is_key_unique: 'true'