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 test
The 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 to true
.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 to debug
.channel
- Toolchain specification/channel to explicitly install.components
- Comma-separated list of additional components to install.inherit-toolchain
- Inherit all toolchain settings from the rust-toolchain.toml
file. Defaults
to false
.targets
- Comma-separated list of additional targets to install.target-dirs
- Comma-separated list of target folder paths, relative from the repository root.
Defaults to target
.profile
- Profile to install. Defaults to minimal
.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
channel
field 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-toolchain
input.
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: complete
When using components, the input requires a comma separated list of component names.
- uses: moonrepo/setup-rust@v1
with:
components: clippy
- run: cargo clippy --workspace
When 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-binstall
under the hood. We suggest settingGITHUB_TOKEN
to 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: release
The following optimizations and considerations are taken into account when caching:
~/.cargo
/bin
directory is not cached as we manage binary installation in this action via the
bins
input./git
directory is not cached as it's not necessary for CI. When required by Cargo or a
crate, a checkout will be performed on-demand./registry
directory is cleaned before saving the cache. This includes removing src
,
.cache
, and any other unnecessary files./target
/debug
profile is cached, as this profile is typically used for formatting, linting,
and testing. This can be changed with the cache-target
input./examples
and /incremental
sub-directories are not cached as they are not necessary for
CI.*.d
) files are removed, as they're meant for build systems and signaling
re-executions.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)
actions-rs/*
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:
rustup
, cargo
, and other commands are available globally. This allows you to use them
directly in a run
command, without having to use actions-rs/cargo
.dtolnay/rust-toolchain
Our action is very similar to theirs, which was a great implementation reference, but our action also supports the following features:
rust-toolchain.toml
and rust-toolchain
configuration
files.Swatinem/rust-cache
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:
~/.cargo
directory, while our action only caches ~/.cargo/registry
.
View the reasoning above.
~/.cargo/bin
issues that theirs currently has.