Rust and Cargo

A hub as a Cargo registry: setup, publishing crates, depending on them

Chapter 10 of 34Current for Gritpack 1.2.63Source: docs/guide/10-rust-and-cargo.md

You write Rust, your team has crates it does not want on crates.io, and you would like cargo add, cargo build and Cargo.lock to keep working exactly as they do today. This chapter makes your hub one more registry Cargo knows about, next to crates.io. Cargo keeps doing everything it already does; the hub becomes another place a crate can come from.

Maturity: Available. The hub serves a Cargo sparse registry: setup, diagnosis, publishing, resolution, download, yank and search work with ordinary Cargo. cargo owner is not supported; ownership is managed by the hub (see Names, scopes and owners).

What you will be able to do

  • add your hub to a Cargo project as a named registry, with one command;
  • check that Cargo, your login and the registry agree, with one command;
  • publish a crate to the hub, all or nothing, with a receipt;
  • depend on a private crate and a crates.io crate in the same Cargo.toml;
  • yank a bad version with cargo yank.

You need a login on the hub first. If gritpack auth status does not show your account yet, read Logging in and come back.

What does not change

Cargo is still the resolver, the builder, the test runner and the owner of Cargo.lock. cargo build, cargo test, rust-analyzer and your CI do not change. crates.io stays Cargo's default registry: only dependencies that name the hub's registry come from the hub.

The hub never runs cargo, rustc, build scripts or macros. It does not mirror crates.io, and it does not change how Cargo resolves. It gives crates a place to live, an owner, a search entry and signed evidence of who published them.

From Cargo. A Gritpack hub is an alternate registry in Cargo's own sense: a [registries.<name>] entry with a sparse index, and registry = "<name>" on each dependency that should come from it. Crate names stay ordinary Cargo names. Gritpack's @scope/name form is not used for crates.

1. Point Cargo at the hub

From the directory of a Cargo project, run:

$ gritpack setup
setup adapter=cargo profile=work status=changed registry=gritpack config=./.cargo/config.toml

Gritpack saw Cargo.toml, asked your hub where its Cargo index is, and wrote one registry entry into the project's own .cargo/config.toml:

[registries]

[registries.gritpack]
index = "sparse+https://packages.example.com:7446/cargo/index/"
credential-provider = ["/home/you/.frogfish/gritpack/bin/gritpack", "cargo-credential", "--profile", "work", "--config", "/home/you/.frogfish/gritpack/config.toml"]

Two things to notice:

  • The registry is called gritpack unless you choose another name with --cargo-registry, for example gritpack setup --cargo-registry company. That name is what your Cargo.toml files will say.
  • No token is stored. The credential-provider line tells Cargo to ask Gritpack whenever it needs to authenticate. Gritpack uses your login to get a short-lived token for that one operation, and Cargo never writes it to its credentials file.

Run it again and nothing changes:

$ gritpack setup
setup adapter=cargo profile=work status=unchanged registry=gritpack config=./.cargo/config.toml

setup uses your default login. To use another, pass --profile work. If the directory holds more than one kind of project, for example a Cargo.toml and a package.json, Gritpack does not guess: choose with --adapter cargo.

Commit .cargo/config.toml if everyone on the team uses the same hub and the same profile name, or keep it out of version control and let each person run gritpack setup once. The paths in it are absolute paths on your machine.

Cargo must trust the hub's certificate

When your hub uses a certificate from a public certificate authority, there is nothing to do. When your hub's administrator gave you a certificate authority file of your own, Cargo needs it too, because Cargo makes its own HTTPS connections. Either install it in your operating system's trust store, or tell Cargo where it is:

[http]
cainfo = "/home/you/.frogfish/gritpack/hub-ca.pem"

You can put that in the same .cargo/config.toml, or set the CARGO_HTTP_CAINFO environment variable.

Setting up a registry for every project at once

gritpack setup writes to one project. To add the hub to your user-wide Cargo configuration instead, use gritpack cargo setup and say which name and login to use:

$ gritpack cargo setup --registry company --profile work --index sparse+https://packages.example.com:7446/cargo/index/
configured Cargo registry company profile=work index=sparse+https://packages.example.com:7446/cargo/index/ config=/home/you/.cargo/config.toml

It changes only [registries.company] and leaves the rest of the file, comments included, alone. Running it again reports verified instead of configured. If an entry with that name already exists and differs, it stops and asks you to look, or to pass --force:

$ gritpack cargo setup --registry company --profile work --index sparse+https://other.example/cargo/index/
invalid Cargo registry configuration: registry "company" already differs; inspect /home/you/.cargo/config.toml or rerun with --force

Without --index, gritpack cargo setup assumes the index is on port 7446 of your login's hub. gritpack setup asks the hub instead, so prefer it, or pass the --index your administrator gave you. --cargo-config writes a different Cargo configuration file.

Careful. Cargo reads every .cargo/config.toml from the current directory up to your home directory, and the one nearest the project wins. If your home directory's Cargo configuration already defines a registry called gritpack, a command run outside the project (for example with --manifest-path) uses that one. Run Cargo from inside the project, or pick a distinct name with --cargo-registry.

2. Check it

One command checks the Cargo configuration entry, your login, the token, TLS and the sparse index:

$ gritpack cargo doctor --registry gritpack --cargo-config .cargo/config.toml
healthy Cargo registry gritpack profile=work index=sparse+https://packages.example.com:7446/cargo/index/ cargo=cargo 1.98.1 (797e8a9bc 2026-08-05) token_expires_at=1794900709

token_expires_at is when the token minted for the check stops working, in Unix seconds: five minutes later. Tokens are made fresh for each operation, so nothing long-lived sits on disk.

When something is wrong, the doctor says what and exits with a non-zero code. For example, an index address that does not answer:

$ gritpack cargo doctor --registry company
cannot reach the hub: error sending request for url (https://packages.example.com:7446/cargo/index/config.json): client error (Connect): tcp connect error: Connection refused (os error 111)

That one exits with code 8, "unavailable" (see Scripting with JSON for all exit codes). Add --json for a structured report:

{
  "cargo_version": "cargo 1.98.1 (797e8a9bc 2026-08-05)",
  "index": "sparse+https://packages.example.com:7446/cargo/index/",
  "profile": "work",
  "registry": "company",
  "token_expires_at": 1794900787,
  "warnings": []
}

gritpack doctor in the project directory runs the general checks too: your login, your account, the hub, and then the Cargo routing.

$ gritpack doctor
PASS project — detected cargo at ./
PASS profile — profile=work provider=file
PASS provider — credential material resolved
PASS identity — account=01a1e866-2c84-77b1-a23c-6ca9f59543bf email=ada@example.com status=Active
PASS hub — repository=550e8400-e29b-41d4-a716-446655440000 endpoint=https://packages.example.com:443
PASS ecosystem — cargo=cargo 1.98.1 (797e8a9bc 2026-08-05) index=sparse+https://packages.example.com:7446/cargo/index/

3. Publish a crate

Crates keep their ordinary Cargo names. In the crate's Cargo.toml, name the registry in publish, so a stray cargo publish can never send the crate to crates.io:

[package]
name = "ada-strings"
version = "0.1.0"
edition = "2021"
description = "Small string helpers"
license = "MIT"
readme = "README.md"
publish = ["gritpack"]

Every new version on a hub needs a README of at least 100 words and a licence declaration (license or license-file). README and licence explains the rule and how to go without one when you must.

Now ask Gritpack to check everything without publishing:

$ gritpack publish --dry-run
planning publication; Cargo members may run cargo metadata/package and rustc version checks
publication plan=sha256:677065b0... result=RequiresRemoteVerification nodes=1 edges=0 output=./.gritpack/publication-plan.json
cargo:ada-strings@0.1.0 adapter=Cargo status=Indeterminate artifact=.gritpack/publication/artifacts/cargo-ada-strings-0.1.0.crate
  check=CARGO_VERSION_RECORDED status=Passed — cargo 1.98.1 (797e8a9bc 2026-08-05)
  check=RUSTC_VERSION_RECORDED status=Passed — rustc 1.98.1 (48a229cea 2026-09-01)
  check=CARGO_PACKAGE_CONSTRUCTED status=Passed — Cargo produced a normalized archive containing 5 files
  check=CARGO_DESTINATION_PERMITTED status=Passed — Cargo package.publish permits registry gritpack
  check=PUBLICATION_METADATA_INCOMPLETE status=Warning — Cargo.toml does not declare repository; catalogue pages and search will show this version without it, and a published version cannot be amended
  check=CARGO_PACKAGE_VERIFIED status=Passed — Cargo completed native package verification
  check=PUBLICATION_DOCUMENTATION_POLICY status=Passed — README and licence meet the hub's documentation policy
  check=PUBLICATION_LICENSE_DECLARED status=Passed — MIT
publication verification plan=sha256:677065b0... repository=550e8400-e29b-41d4-a716-446655440000 result=Publishable generation=sha256:fe5bcb83...
  cargo:ada-strings@0.1.0: New
dry run complete; registry was not mutated

Read it from the top. Gritpack asked Cargo to package the crate (cargo package, so Cargo builds and verifies it exactly as cargo publish would), recorded the Cargo and Rust versions, checked that publish allows this registry, checked the README and licence, and then asked the hub whether the version may be published. New means the hub does not have this version yet and you own the name. The warning is advice: a repository field would make the crate's page more useful, and a published version can never be amended.

When the dry run is clean, publish:

$ gritpack publish
...
committed publication transaction=01a1e866-ed1f-7bd3-96c9-8a928750e562 plan=sha256:677065b0... nodes=1
  cargo:ada-strings@0.1.0: New storage_id=cargo-sha256:3e1a4d2d... digest=sha256:3e1a4d2d...

On a terminal, publish shows the plan and asks before it changes anything. In a script or CI job, pass --yes.

What happened: Gritpack normalised Cargo's .crate file so the same source always gives the same bytes, uploaded it, and the hub checked it again on its own side and made it visible in one step. Either the whole publication is visible or none of it is. The hub keeps a signed receipt you can fetch later (Evidence and receipts). Running the same command again for the same version does not publish twice; Gritpack finds the finished publication and reports it.

The crate is now on the hub:

$ gritpack info ada-strings
ada-strings 0.1.0 (cargo)
  Small string helpers
  dialect: rust/cargo
  versions: 0.1.0
  license: MIT
  owner: 01a1e866-2c84-77b1-a23c-6ca9f59543bf
  crate sha256: 3e1a4d2d54e0cfbd97659bdb81766f5b17c7b3f0f30e53d62719eec5d3580e6f
  use: cargo add ada-strings@0.1.0 --registry <registry>

The first account to publish a crate name owns it. Another account trying to publish ada-strings is stopped at the dry run with PUBLICATION_AUTHORITY_DENIED: publisher does not own the Cargo package name.

When the registry has another name

gritpack publish assumes the registry is called gritpack. If your Cargo.toml says publish = ["company"], tell it so; otherwise Cargo refuses to package the crate:

gritpack publish --cargo-registry company

In a Cargo workspace with several crates, gritpack publish plans them all together and publishes them all or none, in dependency order. --package NAME (repeatable) limits it to some of them. Uncommitted changes are refused, as Cargo refuses them; --allow-dirty lets them through. Publishing step by step covers plans and transactions in depth.

What about plain cargo publish?

cargo publish --registry gritpack talks to the same registry. Whether the hub accepts it depends on the hub. A hub that keeps signed evidence for every publication accepts new versions only through Gritpack's transactional publication, and answers plain cargo publish like this:

error: failed to publish ada-strings v0.1.1 to registry at https://packages.example.com:7446/cargo

Caused by:
  the remote server responded with an error (status 409 Conflict): repository evidence policy requires gritpack transactional publication

Then use gritpack publish. It runs Cargo's own packaging and verification for you, so you lose nothing.

4. Depend on a private crate

In a project that should use the crate, run gritpack setup once, then use Cargo as usual:

$ gritpack setup
setup adapter=cargo profile=work status=changed registry=gritpack config=./.cargo/config.toml
$ cargo add ada-strings --registry gritpack
    Updating `gritpack` index
      Adding ada-strings v0.1.1 to dependencies
$ cargo add itoa@1
      Adding itoa v1.0.19

Cargo.toml now holds one dependency from the hub and one from crates.io:

[dependencies]
ada-strings = { version = "0.1.1", registry = "gritpack" }
itoa = "1"
$ cargo run -q
HELLO!

Both crates resolved into one graph, and Cargo.lock records where the private one came from:

[[package]]
name = "ada-strings"
version = "0.1.1"
source = "sparse+https://packages.example.com:7446/cargo/index/"
checksum = "b1cd6213cb6cc9395de8d6a779dcc50ed3a963dfc0ce7c9b2a6965d3de4f57fa"

Commit Cargo.lock as you always would. A dependency without registry = ... never comes from the hub, and a private crate never silently comes from crates.io, so a crates.io crate with the same name cannot take its place.

For automation. In CI, the job needs a Gritpack login (see Continuous integration), the same .cargo/config.toml entry, and the hub's certificate authority if it has a private one. Then cargo build --locked works as usual.

5. Find, yank and look after crates

Search works from Cargo or from Gritpack:

$ cargo search ada --registry gritpack
ada-strings = "0.1.1"    # Small string helpers
$ gritpack search strings
ada-strings 0.1.0 ecosystem=cargo score=250 dialect=rust/cargo variants=1 — Small string helpers

gritpack search and gritpack info show native packages and crates in one list; --ecosystem cargo shows only crates. gritpack info ada-strings --ecosystem cargo --json gives the full record, README included.

A published version never changes. If 0.1.0 has a bug, publish 0.1.1. To stop new projects from choosing a bad version, yank it with Cargo:

$ cargo yank ada-strings@0.1.1 --registry gritpack
    Updating `gritpack` index
        Yank ada-strings@0.1.1
$ cargo yank --undo ada-strings@0.1.1 --registry gritpack
    Updating `gritpack` index
      Unyank ada-strings@0.1.1

A yanked version stays downloadable for projects whose Cargo.lock already names it; Cargo just stops choosing it for new resolutions. For crates, use cargo yank: gritpack package yank and gritpack package deprecate work on native packages, and answer "package not found" for a crate.

Things Cargo can ask that the hub does not answer yet:

  • cargo owner reports "requested operation not supported". Crate names are owned by the account that first published them; an administrator can see and change ownership.
  • There are no per-crate access lists. Everyone with a login on a private hub can read every crate on it; the hub itself is the privacy boundary.

When something looks wrong

You seeIt usually means
no matching package named ... found from Cargothe dependency lacks registry = "gritpack", or the registry name in Cargo.toml differs from the one in .cargo/config.toml
an SSL or certificate error from CargoCargo does not trust the hub's certificate authority; set http.cainfo
cannot be packaged during gritpack publishpublish = [...] names another registry; pass --cargo-registry
PUBLICATION_DOCUMENTATION_REQUIREDthe crate has no README of 100 words, or no licence; see README and licence
repository evidence policy requires gritpack transactional publicationpublish with gritpack publish instead of cargo publish

Troubleshooting by symptom has more.

What just happened

  • One command put your hub next to crates.io in the project's Cargo configuration, with no token stored anywhere.
  • gritpack publish had Cargo package and verify the crate, then published it to the hub in one step, with a signed receipt.
  • A second project depended on the private crate and a crates.io crate in one Cargo.toml, and Cargo.lock recorded where each came from.
  • Cargo stayed in charge of resolving, building and locking throughout.

You can stop here

A Rust team that wanted private crates without changing how it builds is done. Your CI needs a login too; Continuous integration shows how.

Next

  • The npm, Go and C/C++ chapters cover the same ground for those languages: npm, Go modules, C and C++.
  • Optional deep dive: Releasing a workspace for several crates (and packages in other languages) published together, all or none.