How Cargo caching works
Source replacement tells Cargo that another registry holds exactly the same crates as crates.io. Cargo keeps writing crates.io as the source in Cargo.lock and keeps verifying every crate against its checksum, while all downloads go to Cacheport.
Cacheport uses the sparse index protocol, so Cargo only downloads index files for the crates you actually depend on.
- Sparse index files
- Refreshed every 5 minutes, last good copy on failure.
- .crate files
- Cached forever, served byte-identical.
- Git dependencies
- Fetched directly by Cargo, not through the registry.
Set it up
.cargo/config.toml
[registries.cacheport]
index = "sparse+https://acme.cacheport.cc/cargo/index/"
[source.crates-io]
replace-with = "cacheport"Token
export CARGO_REGISTRIES_CACHEPORT_TOKEN="Bearer $CACHEPORT_TOKEN"
cargo build --lockedCargo reads registry tokens from CARGO_REGISTRIES_<NAME>_TOKEN. Commit the config file; keep the token in CI secrets.
Use it in CI
Store the token as a secret named CACHEPORT_TOKEN, then pick your provider.
GitHub Actions
jobs:
test:
runs-on: ubuntu-latest
env:
CARGO_REGISTRIES_CACHEPORT_TOKEN: Bearer ${{ secrets.CACHEPORT_TOKEN }}
steps:
- uses: actions/checkout@v4
- uses: dtolnay/rust-toolchain@stable
- run: cargo test --lockedMore for GitHub Actions: GitHub Actions setup guide.
GitLab CI
test:
image: rust:1
script:
- export CARGO_REGISTRIES_CACHEPORT_TOKEN="Bearer $CACHEPORT_TOKEN"
- cargo test --lockedMore for GitLab CI: GitLab CI setup guide.
Pair it with sccache
Downloading crates is only part of a cold Rust build; compiling them is the rest. The Build Cache service speaks the protocol sccache uses for remote storage, so compiled dependencies can be shared between runners too.
Troubleshooting
Errors that usually mean the public registry is the bottleneck, and what Cacheport changes about them.