basetenlabs/rust-cache

basetenlabs/rust-cache

Description: A GitHub Action that implements smart caching for rust/cargo projects

License: LGPL-3.0

Stars: 0

Forks: 0

Open issues: 8

Created: 2026-03-10T19:43:03Z

Pushed: 2026-06-05T13:40:42Z

Default branch: master

Fork: yes

Parent repository: Swatinem/rust-cache

Archived: no

README:

Rust Cache Action

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

Example usage

- uses: actions/checkout@v5

# selecting a toolchain either by action or manual `rustup` calls should happen
# before the plugin, as the cache uses the current rustc version as its cache key
- run: rustup toolchain install stable --profile minimal

- uses: Swatinem/rust-cache@v2
with:
# The prefix cache key, this can be changed to start a new cache manually.
# default: "v0-rust"
prefix-key: ""

# A cache key that is used instead of the automatic `job`-based key,
# and is stable over multiple jobs.
# default: empty
shared-key: ""

# An additional cache key that is added alongside the automatic `job`-based
# cache key and can be used to further differentiate jobs.
# default: empty
key: ""

# If the automatic `job`-based cache key should include the job id.
# default: "true"
add-job-id-key: ""

# Weather the a hash of the rust environment should be included in the cache key.
# This includes a hash of all Cargo.toml/Cargo.lock files, rust-toolchain files,
# and .cargo/config.toml files (if present), as well as the specified 'env-vars'.
# default: "true"
add-rust-environment-hash-key: ""

# A whitespace separated list of env-var *prefixes* who's value contributes
# to the environment cache key.
# The env-vars are matched by *prefix*, so the default `RUST` var will
# match all of `RUSTC`, `RUSTUP_*`, `RUSTFLAGS`, `RUSTDOC_*`, etc.
# default: "CARGO CC CFLAGS CXX CMAKE RUST"
env-vars: ""

# The cargo workspaces and target directory configuration.
# These entries are separated by newlines and have the form
# `$workspace -> $target`. The `$target` part is treated as a directory
# relative to the `$workspace` and defaults to "target" if not explicitly given.
# default: ". -> target"
workspaces: ""

# Additional non workspace directories to be cached, separated by newlines.
cache-directories: ""

# Determines whether workspace `target` directories are cached.
# If `false`, only the cargo registry will be cached.
# default: "true"
cache-targets: ""

# Determines if the cache should be saved even when the workflow has failed.
# default: "false"
cache-on-failure: ""

# Determines which crates are cached.
# If `true` all crates will be cached, otherwise only dependent crates will be cached.
# Useful if additional crates are used for CI tooling.
# default: "false"
cache-all-crates: ""

# Similar to cache-all-crates.
# If `true` the workspace crates will be cached.
# Useful if the workspace contains libraries that are only updated sporadically.
# default: "false"
cache-workspace-crates: ""

# Determines whether the cache should be saved.
# If `false`, the cache is only restored.
# Useful for jobs where the matrix is additive e.g. additional Cargo features,
# or when only runs from `master` should be saved to the cache.
# default: "true"
save-if: ""
# To only cache runs from `master`:
save-if: ${{ github.ref == 'refs/heads/master' }}

# Determines whether the cache should be restored.
# If `true` the cache key will be checked and the `cache-hit` output will be set
# but the cache itself won't be restored
# default: "false"
lookup-only: ""

# Specifies what to use as the backend providing cache
# Can be set to "github", "buildjet", or "warpbuild"
# default: "github"
cache-provider: ""

# Determines whether to cache the ~/.cargo/bin directory.
# default: "true"
cache-bin: ""

# A format string used to format commands to be run, i.e. `rustc` and `cargo`.
# Must contain exactly one occurance of `{0}`, which is the formatting fragment
# that will be replaced with the `rustc` or `cargo` command. This is necessary
# when using Nix or other setup that requires running these commands within a
# specific shell, otherwise the system `rustc` and `cargo` will be run.
# default: "{0}"
cmd-format: ""
# To run within a Nix shell (using the default dev shell of a flake in the repo root):
cmd-format: nix develop -c {0}

Further examples are available in the [.github/workflows](./.github/workflows/) directory.

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 it is more effective if the dependency / own code ratio is higher.

It is also more 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 the 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, unless a specific nightly build is being pinned.

Cache Details

This action currently caches the following files/directories:

• ~/.cargo (installed binaries, the cargo registry, cache, and git dependencies)
• ./target (build artifacts of dependencies)

This cache is automatically keyed by:

• the github `job_id`

(if add-job-id-key is "true"),

• the rustc release / host / hash (for all installed toolchains when

available),

• the following values, if add-rust-environment-hash-key is "true":
• the value of some compiler-specific environment variables (eg. RUSTFLAGS, etc), and
• a hash of all Cargo.lock / Cargo.toml files found anywhere in the repository (if present).
• a hash of all rust-toolchain / rust-toolchain.toml files in the root of the repository (if present).
• a hash of all .cargo/config.toml files in the root of the repository (if present).

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

Before being persisted, the cache is cleaned of:

• Any files in ~/.cargo/bin that were present before the action ran (for example rustc).
• Dependencies that are no longer used.
• Anything that is not a dependency.
• Incremental build artifacts.
• Any build artifacts with an mtime older than one week.

In particular, the…