Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.
ArtifactsRegistry TypesCi Cd

Cargo

Create a Cargo registry, generate an identity token, then publish and install Rust crates with the Cargo CLI through your Harness Artifacts registry.

Use a Cargo registry to host private Rust crates for the Cargo CLI.

What you will learn from this topic

By the end of this quickstart guide, you will be able to:

  • Create a registry in Harness Artifacts.

  • Publish a package to the registry.

  • Install the package from the registry, and confirm that it works.

Before you begin

  • Install the Cargo CLI (cargo), which ships with the Rust toolchain, on your local machine.

  • Make sure you have access to a Harness account with permission to create registries and connectors.

Create a Cargo Registry

To create a Cargo registry, perform the following steps:

  1. In Artifact Registry, select Registries.

  2. Select + Create Registry.

  3. Specify the Registry name.

Registry name criteria

The registry name must start with a letter, can only contain lowercase alphanumerics, _, ., and -, and must be unique to your Harness account.

  1. Optionally, add a Description.

  2. Choose visibility between Public and Private. The default is Private.

Private registry

A private Cargo registry restricts access to users with permissions on your Harness account. Select Public to allow unauthenticated access instead.

  1. Select Cargo as the Registry type.

  2. Select Save.

  3. Select Create to finalize.

Configure an upstream proxy (optional)

An upstream proxy allows your registry to fetch Cargo crates from crates.io when they are not available locally. The default upstream is crates.io.

Create upstream proxy

To create an upstream proxy, perform the following steps:

  1. In Artifact Registry, select Registries.

  2. Select the drop-down next to + Create Registry and select Upstream Proxy.

  3. Specify the Registry name.

  4. Optionally, add a Description.

  5. Choose visibility between Public and Private. The default is Private.

  6. Select Cargo as the Registry type.

  7. Select the Source: Crates.io or Custom.

    • If you select Custom, specify the Remote registry URL.

  8. Select the Authentication method.

    • Username and password: Specify the username and password. Use an existing secret, or create a new secret by specifying the Name and entering the Secret text.

    • Anonymous: No credentials required. This works for the public crates.io registry.

  9. Optionally, configure the Metadata configuration:

    • Metadata cache TTL (seconds): How long Harness caches crate metadata from the upstream before it checks for updates.

    • Negative cache TTL (seconds): How long Harness caches a failed lookup before it retries the upstream.

    To decide the right cache duration for your registry, go to Metadata configuration.

  10. Select Create to finalize.

Configure the upstream proxy in your registry

To configure the upstream proxy in your registry, perform the following steps:

  1. In Artifact Registry, select an existing Cargo registry.

  2. Navigate to the Configuration tab.

  3. Select Edit in the Upstream proxy section.

  4. Select + Add upstream proxy.

  5. Select the required proxy from the list.

  6. Select Apply.

  7. Select Update to finalize.

Upstream proxy caching

If a crate is not found in your Harness registry, the upstream proxy fetches it from crates.io and caches it.

Cargo client setup

In your Cargo Artifact, select the registry, then select Set Up Client.

Generate an identity token

An identity token serves as the password for authenticating with the registry.

  1. In your Cargo registry, select Set Up Client.

  2. Select Generate Token.

  3. Select an Expiration for the token:

    • 30 Days

    • 90 Days

    • 180 Days

    • Custom

  4. Copy the token. You use it in the following steps in place of <IDENTITY_TOKEN>.

Token expiration

The identity token stops working after the expiration you select. Generate a new token and update your client configuration before the current token expires.

Configure the client

In the code samples, replace the values in angle brackets with your own values.

1. Configure the client

Add the following to ~/.cargo/config.toml:

Add the following to ~/.cargo/credentials.toml:

2. Publish the crate

Publish your crate to the registry:

3. Use the crate

Add the crate to your project:

Setup verification

Confirm that your registry serves the crate you published. To verify your setup, perform the following steps:

  1. In a new directory with no cached registry index, Cargo.lock file, or vendored dependencies, use the Cargo CLI to add the crate you published.

  2. Confirm that Cargo downloaded the crate from your Harness registry address, which is shown in Set Up Client.

  3. In Harness, open your registry and confirm that the crate and version appear in the package list.

If a step fails, go to Troubleshooting to resolve common authentication and resolution issues before you retry.

Pipeline automation (optional)

Publishing from a pipeline gives you a repeatable release process. Run the publish step when you create a version tag, so each release maps to one version in the registry.

The following Run step bumps the crate version from the pipeline's tag before publishing. Store the identity token as a Harness secret, and do not write it into the pipeline YAML.

Troubleshooting

`cargo publish` fails with `401 Unauthorized` or `403 Forbidden`

Check that ~/.cargo/credentials.toml holds the identity token from Set Up Client, prefixed with Bearer , under the correct [registries.<REGISTRY_NAME>] section. If the token expired or was revoked, generate a new one and update the file.

`cargo publish` returns an error that the crate version already exists

Crate versions are immutable after publish. Bump the version field in Cargo.toml to a new SemVer value, or delete the existing version only if your registry retention and lifecycle policies allow it.

`cargo add` cannot resolve the crate or an older version

Check that the crate name and version match the values you used when you published, and that ~/.cargo/config.toml points index at the correct account ID and registry name.

Set Up Client omits publish instructions

An upstream proxy registry is pull-only, so Set Up Client only shows install instructions, not publish instructions. Publish your crate to a standard registry instead, or configure the upstream proxy on a registry that allows publishing.

`cargo add` keeps resolving an old version after a new publish

Cargo caches the sparse index locally. Run cargo update or clear the cached index in ~/.cargo/registry/index/ to pick up the new version.

Next steps

Last updated

Was this helpful?