> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/artifact-registry/3.0/setup/cargo.md).

# Cargo

Cargo - publish Rust crates to Harness Artifacts

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 guide, you will know how 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:

1. In Artifact Registry, select **Registries**.
2. Select **+ Create Registry**.
3. Specify the **Registry name**.

{% hint style="info" %}
**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.
{% endhint %}

4. Optionally, add a **Description**.
5. Choose visibility between **Public** and **Private**. The default is *Private*.

{% hint style="info" %}
**Private registry**

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

6. Select **Cargo** as the **Registry type**.
7. Select **Save**.
8. 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:

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 [Configure metadata cache TTL](https://developer.harness.io/artifact-registry/3.0/registries/create-an-upstream-proxy.md#configure-metadata-cache-ttl).
10. Select **Create** to finalize.

### Configure the upstream proxy in your registry

To configure the upstream proxy in your registry:

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.

{% hint style="info" %}
**Upstream proxy caching**

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

## Cargo client setup

In your Cargo Artifact, select the registry, then select **Setup Client**.

### Generate an identity token

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

1. In your Cargo registry, select **Setup 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>`.

{% hint style="info" %}
**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.
{% endhint %}

### 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`:

```toml
[registry]
global-credential-providers = ["cargo:token", "cargo:libsecret", "cargo:macos-keychain", "cargo:wincred"]

[registries.<REGISTRY_NAME>]
index = "sparse+https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/cargo/index/"
```

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

```toml
[registries.<REGISTRY_NAME>]
token = "Bearer <IDENTITY_TOKEN>"
```

**2. Publish the crate**

Publish your crate to the registry:

```bash
cargo publish --registry <REGISTRY_NAME>
```

**3. Use the crate**

Add the crate to your project:

```bash
cargo add <ARTIFACT_NAME>@<VERSION> --registry <REGISTRY_NAME>
```

## Setup verification

Confirm that your registry serves the crate you published. To verify your setup:

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 **Setup 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](#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.

```yaml
- step:
    type: Run
    name: Publish package
    identifier: publish_package
    spec:
      shell: Sh
      envVariables:
        PACKAGE_VERSION: <+codebase.tag>
      command: |
        sed -i "s/^version = .*/version = \"$PACKAGE_VERSION\"/" Cargo.toml
        cargo publish --registry <REGISTRY_NAME>
```

## Troubleshooting

<details>

<summary>`cargo publish` fails with `401 Unauthorized` or `403 Forbidden`</summary>

Check that `~/.cargo/credentials.toml` holds the identity token from **Setup 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.

</details>

<details>

<summary>`cargo publish` returns an error that the crate version already exists</summary>

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.

</details>

<details>

<summary>`cargo add` cannot resolve the crate or an older version</summary>

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.

</details>

<details>

<summary>Setup Client omits publish instructions</summary>

An upstream proxy registry is pull-only, so **Setup 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.

</details>

<details>

<summary>`cargo add` keeps resolving an old version after a new publish</summary>

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

</details>

## Next steps

* To add a pipeline that publishes a new version for every release tag, go to [Harness CI](https://developer.harness.io/artifact-registry/3.0/platform-integrations/harness-ci.md).
* To control who can publish and consume packages in your registry, go to [RBAC and permissions](https://developer.harness.io/artifact-registry/3.0/reference/rbac-and-permissions.md).
* To set retention and lifecycle rules for old versions, go to [Lifecycle Management overview](https://developer.harness.io/artifact-registry/3.0/lifecycle-management/overview.md).

{% @harness-feedback/feedback %}
