Tool Caches

Tool caches enable tasks to utilize incremental caching. With a tool cache configured, the file contents of the previous execution of a task will be present on disk when the task runs.

For example, package manager tasks like npm 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. Using tool caches is 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. It's recommended to configure a cron job to keep the cache warm & up to date. See the recommendations section below for more info.

Configuring a tool cache vault

For security reasons, tool caches need to be configured to use a vault. This prevents runs on feature branches from populating cache data that would be used on protected branches, such as main.

In general, you should configure the tool cache vault to use the vault corresponding to the protected branch, such as main, of the repository.

You need to add the tool-cache section to the top level of your Mint run definition.

tool-cache:
  vault: your_repo_main

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. This enables feature branches to utilize the cache that was generated on main, but prevents features branches from pushing incremental changes to it.

Configuring a task to use a tool cache

Once the vault is configured, add a tool-cache key to the task definition to enable the tool cache for that task. Ensure that the tool cache name is unique for the vault. As a best practice, if your vault is named after your repository, incorporate the Mint run and task key into the tool-cache value. For example, if you have an npm-install task in your .mint/ci.yml file in your awesome_project repo that has an awesome_project_main vault, you should configure the tool cache like this:

tool-cache:
  vault: awesome_project_main

tasks:
  - key: npm-install
    run: npm install
    tool-cache: ci-npm-install

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 npm and 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 your_repo_main is unlocked only by the main branch. The run-level tool cache configuration

tool-cache:
  vault: your_repo_main

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

This hardening technique prevents feature branches from possibly writing to tool caches in a way that could affect a run on main.

Reset the tool cache nightly

The tool cache will only store 8 incremental executions of a task. After 8 executions, the tool cache will reset to the first execution, discarding the subsequent 7 executions. Over time, the drift between the first execution and the most recent execution could result in the incremental cache becoming less effective. To maintain performance, Mint will automatically evict the first execution in the tool cache after 48 hours.

When this happens, the next execution of the task could be considerably slower than normal since it will execute from a cold cache. To prevent the cold cache problem, you can configure a cron run to rebuild the tool cache on a daily basis, before the 48 hour expiration is hit.

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: [npm-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 npm-install configured with a tool cache is run with a different set of npm packages 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 npm-install.

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