cargo supports alternative registries but does not support authenticated downloads. cargo-sideload lets your specify a registry, then reads your Cargo.lock file to determine which dependencies use the specified registry. It then downloads the .crate files for those dependencies using a user-specified authentication method, and stores them in your local cargo cache as if they were downloaded directly with cargo.

The next time you run a cargo command, it will find the cached .crate files and use those instead of attempting to download them.

cargo-sideload is a workaround until cargo supports authenticated downloads natively.

Installation

cargo install cargo-sideload

First run

1. Add your alternate registry to ~/.cargo/config.toml.
2. Add registry = "[registry-name]" to any dependencies that use the registry.
3. Run cargo update to populate your Cargo.lock file.
4. Run cargo sideload --registry=[registry-name] in your crate's root.
   • Set CARGO_SIDELOAD_AUTH_HEADER in your shell or use the --auth-header flag if your download endpoint requires authentication. Format: [Header-Name]: [Header Value].
5. Your crates are now in the local cargo cache. cargo will use the local copies rather than attempt to download them.

Subsequent runs

1. If alternate registry dependencies have changed
   1. Run cargo update -p [crate-names] to update your Cargo.lock file.
   2. Run cargo sideload --registry=[registry-name] to download updated dependencies.
2. If alternate registry dependences have not changed, you don't have to do anything.

Current restrictions

1. Authentication is currently hardcoded for GitLab's PRIVATE-TOKEN header.

Remaining Work

1. Write tests
2. Automatically run cargo update for registry dependencies that are in Cargo.toml but not Cargo.lock.
3. Deal with corrupt .crate files.
4. Improve console output.