A one-stop-shop GitHub action for setting up Rust and Cargo. Will automatically setup the Rust
toolchain with rustup, cache the ~/.cargo/registry and /target/debug directories, and install
Cargo binaries (when applicable).
jobs:
ci:
name: CI
runs-on: ubuntu-latest
steps:
# ...
- uses: moonrepo/setup-rust@v1
- run: cargo testThe following inputs are available for the action, and can be passed via with. All inputs are
optional.
bins- Comma-separated list of global binaries to install into Cargo.cache- Toggle caching of directories. Defaults totrue.cache-base- Base branch/ref to save a warmup cache on. Other branches/refs will restore from this base.cache-target- Name of the target profile to cache. Defaults todebug.cache-extra-identifier- Additional identifier to include in cache key for matrix jobs or custom cache separation.channel- Toolchain specification/channel to explicitly install.components- Comma-separated list of additional components to install.inherit-toolchain- Inherit all toolchain settings from therust-toolchain.tomlfile. Defaults tofalse.targets- Comma-separated list of additional targets to install.target-dirs- Comma-separated list of target folder paths, relative from the repository root. Defaults totarget.profile- Profile to install. Defaults tominimal.
This action will automatically install the appropriate toolchain with rustup by inspecting the
RUSTUP_TOOLCHAIN environment variable or the rust-toolchain.toml (preferred) or rust-toolchain
configuration files. If no toolchain found, will default to stable.
# rust-toolchain.toml
[toolchain]
channel = "1.68.0"When loading a configuration file, only the
channelfield is used, while the other fields are ignored. We chose this approach, as those other fields are typically for develop/release workflows, but not for CI, which requires a minimal/granular setup. However, this can be overwritten with theinherit-toolchaininput.
The toolchain/channel can also be explicitly configured with the channel input, which takes
highest precedence.
- uses: moonrepo/setup-rust@v1
with:
channel: '1.65.0'Furthermore, this action supports rustup profiles, components, and targets, which can be configured
with the profile, components, and targets inputs respectively. When not defined, profile
defaults to minimal.
- uses: moonrepo/setup-rust@v1
with:
profile: completeWhen using components, the input requires a comma separated list of component names.
- uses: moonrepo/setup-rust@v1
with:
components: clippy
- run: cargo clippy --workspaceWhen using targets, the input requires a comma separated list of target triples.
- uses: moonrepo/setup-rust@v1
with:
targets: 'x86_64-pc-windows-msvc,x86_64-pc-windows-gnu'If you require cargo-make, cargo-nextest, or other global binaries, this action supports
installing Cargo binaries through the bins input, which requires a comma-separated list of crate
names.
- uses: moonrepo/setup-rust@v1
with:
bins: cargo-nextest, cargo-insta@1.28.0
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}Binaries are installed with
cargo-binstallunder the hood. We suggest settingGITHUB_TOKENto avoid rate limiting.
By default this action will cache the ~/.cargo/registry and /target/debug directories to improve
CI times. To disable caching, set the cache input to false. Furthermore, the target profile can
be changed with the cache-target input, which defaults to debug.
- uses: moonrepo/setup-rust@v1
with:
cache: false
cache-target: releaseFor matrix jobs where the cache key would otherwise be identical, you can use cache-extra-identifier to ensure unique cache keys:
strategy:
matrix:
os: [ubuntu-latest, windows-latest, macos-latest]
rust: [stable, beta]
steps:
- uses: moonrepo/setup-rust@v1
with:
cache-extra-identifier: ${{ matrix.os }}-${{ matrix.rust }}The following optimizations and considerations are taken into account when caching:
~/.cargo- The
/bindirectory is not cached as we manage binary installation in this action via thebinsinput. - The
/gitdirectory is not cached as it's not necessary for CI. When required by Cargo or a crate, a checkout will be performed on-demand. - The
/registrydirectory is cleaned before saving the cache. This includes removingsrc,.cache, and any other unnecessary files.
- The
/target- Only the
/debugprofile is cached, as this profile is typically used for formatting, linting, and testing. This can be changed with thecache-targetinput. - The
/examplesand/incrementalsub-directories are not cached as they are not necessary for CI. - All dep-info (
*.d) files are removed, as they're meant for build systems and signaling re-executions.
- Only the
The following sources are hashed for the generated cache key:
$GITHUB_JOB,Cargo.lock, Rust version, Rust commit hash, and OS.
Another strategy that we support is called a warmup cache, where a base branch/ref is used to generate and save the cache (like master), and all other branches/refs will only restore this cache (and not save).
This can be enabled with the cache-base input, which requires a branch/ref name. This input also
supports regex.
- uses: moonrepo/setup-rust@v1
with:
cache-base: master
# With regex
cache-base: (master|main|develop)The "official" actions have served their purpose, but after 3 years of no updates, severe lack of maintenance, and being full of deprecation warnings, it was time to create something new.
Outside of being evergreen, this action also supports the following features:
- Automatically caches.
- Installs Cargo bins.
- Assumes
rustup,cargo, and other commands are available globally. This allows you to use them directly in aruncommand, without having to useactions-rs/cargo.
Our action is very similar to theirs, which was a great implementation reference, but our action also supports the following features:
- Extracts the toolchain/channel from
rust-toolchain.tomlandrust-toolchainconfiguration files. - Automatically caches.
- Installs Cargo bins.
Their action only caches for Rust/Cargo, it doesn't actually setup Rust/Cargo. Our action is meant to do everything, but it's not as configurable as the alternatives.
Here are the key differences between the two:
- Theirs caches the entire
~/.cargodirectory, while our action only caches~/.cargo/registry. View the reasoning above.- Our action also avoids an array of
~/.cargo/binissues that theirs currently has.
- Our action also avoids an array of
- Theirs includes compiler specific environment variables in the cache key, while our action currently does not.
- Theirs supports a handful of inputs for controlling the cache key, while ours does not.
- Theirs is a bit more smart in what it caches, while ours is a bit more brute force. We simply cache specific directories as-is after cleaning.
Their action is versatile for installing a wide range of development tools, including Rust binaries, primarily from GitHub Releases. While our action focuses on a comprehensive Rust environment setup (toolchain, caching, and binaries), their action is specialized in tool installation.
Here are some key differences:
- Our action is an all-in-one solution for Rust CI (toolchain, caching, binaries via
binsinput); theirs focuses on general tool installation and does not handle Rust toolchain setup or caching. - Both actions install Rust binaries: ours uses
cargo-binstalldirectly for thebinsinput, while theirs usescargo-binstallas a fallback for tools not in its manifests. - Theirs offers fine-grained version control for a wide array of tools; our action supports versioning for binaries installed via the
binsinput (e.g.,cargo-insta@1.28.0).