Tool Caches

Tool caches are used to run a task with the file contents of a previous execution of that task.

Dependency installation tasks like bundle install will cache miss if any dependency changes. By configuring a tool cache, a cache miss will be run with the contents of a previous execution of that task. Tool caches are the best way to reduce the runtime of tasks amenable to incremental updates.

Tool caches do not change Mint's caching semantics. Tasks are always checked for a cache hit before executing.

The contents of a tool cache will be evicted 48 hours after first use. We therefore recommend configuring a cron job to keep the cache warm & up-to-date. See the recommendations section below for more info.

Configuring a tool cache

All tool caches belong to a vault. A run is configured with the vault to read tool caches from via the tool-cache key. For example, the following tool-cache definition on a run configures tool caches to be read from the release vault.

tool-cache:
  vault: release

If the vault is unlocked for the run, tool caches will be read from and written to the vault. If the vault is locked, tool caches will only be read from the vault.

A tool cache is enabled for a task via the tool-cache key, which configures the name of the tool cache used for the task. A value of true uses the task key as the tool cache name, but any string literal can be used.

For example, the following run definition configures tool caches to be read from the release vault, and the bundle-install task to use the tool cache bundle-install.

tool-cache:
  vault: release

tasks:
  - key: bundle-install
    run: bundle install
    tool-cache: true
    env:
      BUNDLE_FROZEN: true

It is an error to configure a tool cache for a task without configuring tool-cache on a run.

Managing tool caches

Tool caches can be viewed and evicted under Vaults in the Mint UI.

Recommendations

Use a frozen lockfile

Package managers such as bundle may touch a lockfile when performing an install. This can cause a tool cache to persist a version of a lockfile that overwrites the lockfile from an earlier task. It's recommended to configure package managers to install dependencies without writing to the lockfile.

bundle: consider setting BUNDLE_FROZEN=true
npm: consider using npm ci

Protect write access

It's recommended to configure tool caches to use a vault unlocked only by your repository's protected branch(es). For example, suppose the vault release is unlocked only by the release branch. The run-level tool cache configuration

tool-cache:
  vault: release

ensures that Mint runs on any other branch can use tool caches populated by the release branch, but not write to any tool cache used by the release branch.

This hardening technique prevents feature branches from possibly writing to tool caches with malicious file contents.

Reset the tool cache nightly

To prevent tool caches from continuously growing in size, each tool cache is being evicted 48 hours after its first use. In order to maximize cache utilization during normal runs, we recommend rebuilding the tool cache on a daily basis.

Mint's cron jobs allow setting a reset-tool-cache option to instruct the system to rebuild the tool caches of a run. After successful completion, the cache will have a new expiry.

on:
  cron:
    - key: rebuild-tool-cache
      schedule: '0 0 * * *' # every day at midnight UTC
      target: [bundle-install]
      reset-tool-cache: true

Limitations

At this time, Mint does not support configuring multiple vaults as sources of tool caches.

At this time, tool cache names are always interpreted as string literals. Mint template expressions in a tool cache name are not evaluated.

Tool caches have a limit of 7 incremental layers. If a tool cache contains 8 or more layers, only the bottom layer of the tool cache will be used in the execution of a task. For example, if a task bundle-install configured with a tool cache is run with a different set of Ruby gems 9 times, the eighth execution will start with the filesystem contents of all previous executions, but the ninth execution will start only with the filesystem contents of the first execution of bundle-install.

Please let us know if you'd like to request changes to these limitations.