Rust Cache Action

A GitHub Action that implements smart caching for rust/cargo projects with sensible defaults.

Example usage

# selecting a toolchain either by action or manual `rustup` calls should happen
# before the plugin, as it uses the current rustc version as its cache key
- uses: actions-rs/toolchain@v1
  with:
    profile: minimal
    toolchain: stable

- uses: Swatinem/rust-cache@v1

Inputs

: key An optional key that is added to the automatic cache key.

: sharedKey An additional key that is stable over multiple jobs.

: working-directory The working directory the action operates in, is case the cargo project is not located in the repo root.

: target-dir The target directory that should be cleaned and persisted, defaults to ./target.

: cache-on-failure Cache even if the build fails, defaults to false

Outputs

: cache-hit

This is a boolean flag that will be set to true when there was an exact cache hit.

Cache Effectiveness

This action only caches the dependencies of a crate, so is more effective if the dependency / own code ratio is higher.

It is also most effective for repositories with a Cargo.lock file. Library repositories with only a Cargo.toml file have limited benefits, as cargo will always use the most up-to-date dependency versions, which may not be cached.

Usage with Stable Rust is most effective, as a cache is tied to the Rust version. Using it with Nightly Rust is less effective as it will throw away the cache every day.

Versioning

I use the v1 branch similar to master development, so if you want to have a more stable experience, please use a fixed revision or tag.

Cache Details

The cache currently caches the following directories:

• ~/.cargo/registry/index
• ~/.cargo/registry/cache
• ~/.cargo/git
• ./target

This cache is automatically keyed by:

• the github job,
• the rustc release / host / hash, and
• a hash of the Cargo.lock / Cargo.toml files (if present).
• a hash of the rust-toolchain / rust-toolchain.toml files (if present).

An additional input key can be provided if the builtin keys are not sufficient.

Before persisting, the cache is cleaned of intermediate artifacts and anything that is not a workspace dependency. In particular, no caching of workspace crates will be done. For this reason, this action will automatically set CARGO_INCREMENTAL=0 to disable incremental compilation.

The action will try to restore from a previous Cargo.lock version as well, so lockfile updates should only re-build changed dependencies.

Additionally, the action automatically works around cargo#8603 / actions/cache#403 which would otherwise corrupt the cache on macOS builds.