# Using CodeArtifact with Cargo
<a name="using-cargo"></a>

These topics describe how to use Cargo, the Rust package manager, with CodeArtifact.

**Note**  
CodeArtifact only supports Cargo 1.74.0 and higher. Cargo 1.74.0 is the earliest version that supports authentication on a CodeArtifact repository.

**Topics**
+ [Configure and use Cargo](configure-use-cargo.md)
+ [

# Cargo command support
](cargo-commands.md)

# Configure and use Cargo with CodeArtifact
<a name="configure-use-cargo"></a>

You can use Cargo to publish and download crates from CodeArtifact repositories or to fetch crates from [crates.io](https://crates.io/), the Rust community's crate registry. This topic describes how to configure Cargo to authenticate with and use a CodeArtifact repository.

## Configure Cargo with CodeArtifact
<a name="configure-cargo"></a>

To use Cargo to install and publish crates from AWS CodeArtifact, you'll first need to configure them with your CodeArtifact repository information. Follow the steps in one of the following procedure to configure Cargo with your CodeArtifact repository endpoint information and credentials.

### Configure Cargo using the console instructions
<a name="configure-cargo-console"></a>

You can use configuration instructions in the console to connect Cargo to your CodeArtifact repository. The console instructions provide a Cargo configuration customized for your CodeArtifact repository. You can use this custom configuration to set up Cargo without needing to find and fill in your CodeArtifact information.

1. Open the AWS CodeArtifact console at [https://console.aws.amazon.com/codesuite/codeartifact/home](https://console.aws.amazon.com/codesuite/codeartifact/home).

1. In the navigation pane, choose **Repositories**, and then choose a repository to connect to Cargo.

1. Choose **View connection instructions**.

1. Choose your operating system.

1. Choose **Cargo**.

1. Follow the generated instructions to connect Cargo to your CodeArtifact repository.

### Configure Cargo manually
<a name="configure-cargo-manual"></a>

If you cannot or do not want to use the configuration instructions from the console, you can use the following instructions to connect Cargo to your CodeArtifact repository manually. 

------
#### [ macOS and Linux ]

In order to configure Cargo with CodeArtifact, you need to define your CodeArtifact repository as a registry in the Cargo configuration and provide credentials.
+ Replace *my\$1registry* with your registry name.
+ Replace *my\$1domain* with your CodeArtifact domain name.
+ Replace *111122223333* with the AWS account ID of the owner of the domain. If you are accessing a repository in a domain that you own, you don't need to include `--domain-owner`. For more information, see [Cross-account domains](domain-overview.md#domain-overview-cross-account).
+ Replace *my\$1repo* with your CodeArtifact repository name.

Copy the configuration to publish and download Cargo packages to your repository and save it in the `~/.cargo/config.toml` file for a system-level configuration or `.cargo/config.toml` for a project-level configuration:

```
[registries.my_registry]
index = "sparse+https://my_domain-111122223333.d.codeartifact.us-west-2.amazonaws.com/cargo/my_repo/"
credential-provider = "cargo:token-from-stdout aws codeartifact get-authorization-token --domain my_domain --domain-owner 111122223333 --region us-west-2 --query authorizationToken --output text"

[registry]
default = "my_registry"

[source.crates-io]
replace-with = "my_registry"
```

------
#### [ Windows: Download packages only ]

In order to configure Cargo with CodeArtifact, you need to define your CodeArtifact repository as a registry in the Cargo configuration and provide credentials.
+ Replace *my\$1registry* with your registry name.
+ Replace *my\$1domain* with your CodeArtifact domain name.
+ Replace *111122223333* with the AWS account ID of the owner of the domain. If you are accessing a repository in a domain that you own, you don't need to include `--domain-owner`. For more information, see [Cross-account domains](domain-overview.md#domain-overview-cross-account).
+ Replace *my\$1repo* with your CodeArtifact repository name.

Copy the configuration to only download Cargo packages from your repository and save it in the `%USERPROFILE%\.cargo\config.toml` file for a system-level configuration or `.cargo\config.toml` for a project-level configuration:

```
[registries.my_registry]
index = "sparse+https://my_domain-111122223333.d.codeartifact.us-west-2.amazonaws.com/cargo/my_repo/"
credential-provider = "cargo:token-from-stdout aws codeartifact get-authorization-token --domain my_domain --domain-owner 111122223333 --region us-west-2 --query authorizationToken --output text"

[registry]
default = "my_registry"

[source.crates-io]
replace-with = "my_registry"
```

------
#### [ Windows: Publish and download packages ]

1. In order to configure Cargo with CodeArtifact, you need to define your CodeArtifact repository as a registry in the Cargo configuration and provide credentials.
   + Replace *my\$1registry* with your registry name.
   + Replace *my\$1domain* with your CodeArtifact domain name.
   + Replace *111122223333* with the AWS account ID of the owner of the domain. If you are accessing a repository in a domain that you own, you don't need to include `--domain-owner`. For more information, see [Cross-account domains](domain-overview.md#domain-overview-cross-account).
   + Replace *my\$1repo* with your CodeArtifact repository name.

   Copy the configuration to publish and download Cargo packages to your repository and save it in the `%USERPROFILE%\.cargo\config.toml` file for a system-level configuration or `.cargo\config.toml` for a project-level configuration.

   It is recommended that you use the credential provider `cargo:token`, which uses the credentials stored in your `~/.cargo/credentials.toml` file. You may run into an error during `cargo publish` if you use `cargo:token-from-stdout` because the Cargo client doesn't trim the authorization token properly during `cargo publish`.

   ```
   [registries.my_registry]
   index = "sparse+https://my_domain-111122223333.d.codeartifact.us-west-2.amazonaws.com/cargo/my_repo/"
   credential-provider = "cargo:token"
   
   [registry]
   default = "my_registry"
   
   [source.crates-io]
   replace-with = "my_registry"
   ```

1. To publish Cargo packages to your repository with Windows, you must use the CodeArtifact `get-authorization-token` command and Cargo `login` command to fetch an authorization token and your credentials.
   + Replace *my\$1registry* with your registry name as defined in `[registries.my_registry]`.
   + Replace *my\$1domain* with your CodeArtifact domain name.
   + Replace *111122223333* with the AWS account ID of the owner of the domain. If you are accessing a repository in a domain that you own, you don't need to include `--domain-owner`. For more information, see [Cross-account domains](domain-overview.md#domain-overview-cross-account).

   ```
   aws codeartifact get-authorization-token --domain my_domain --domain-owner 111122223333 --region us-west-2 --query authorizationToken --output text | cargo login --registry my_registry
   ```
**Note**  
The authorization token generated is valid for 12 hours. You will need to create a new one if 12 hours have passed since a token was created.

------

The `[registries.my_registry]` section in the preceding example defines a registry with `my_registry` and provides `index` and `credential-provider` information.
+ `index` specifies the URL of the index for your registry, which is the CodeArtifact repository endpoint that ends with a `/`. The `sparse+` prefix is required for registries that are not Git repositories.
**Note**  
To use a dualstack endpoint, use the `codeartifact.region.on.aws` endpoint.
+ `credential-provider` specifies the credential provider for the given registry. If `credential-provider` isn't set, the providers in `registry.global-credential-providers` will be used. By setting `credential-provider` to `cargo:token-from-stdout`, the Cargo client will fetch new authorization token automatically when publishing or downloading from your CodeArtifact repository, therefore you don't need to manually refresh the authorization token every 12 hours.

The `[registry]` section defines the default registry used.
+ `default` specifies the name of the registry defined in `[registries.my_registry]`, to use by default when publishing or downloading from your CodeArtifact repository.

The `[source.crates-io]` section defines the default registry used when one isn't specified.
+ `replace-with = "my_registry"` replaces the public registry, crates.io with your CodeArtifact repository defined in `[registries.my_registry]`. This configuration is recommended if you need to request packages from the external connection such as crates.io.

  To get all of the benefits of CodeArtifact, such as the package origin control that prevents dependency confusion attacks, it is recommended that you use source replacement. With the source replacement, CodeArtifact proxies all requests to the external connection and copies the package from the external connection to your repository. Without the source replacement, the Cargo client will directly retrieve the package based on the configuration in your `Cargo.toml` file in your project. If a dependency is not marked with `registry=my_registry`, the Cargo client will retrieve it directly from crates.io without communicating with your CodeArtifact repository.
**Note**  
If you start using source replacement and then update your configuration file to not use source replacement, you may encounter errors. The opposite scenario may also lead to errors. Therefore, it is recommended that you avoid changing the configuration for your project.

## Installing Cargo crates
<a name="install-cargo-crates"></a>

Use the following procedures to install Cargo crates from a CodeArtifact repository or from [crates.io](https://crates.io/).

### Install Cargo crates from CodeArtifact
<a name="install-cargo-crates-aca"></a>

You can use the Cargo (`cargo`) CLI to quickly install a specific version of a Cargo crate from your CodeArtifact repository.

**To install Cargo crates from a CodeArtifact repository with `cargo`**

1. If you haven't, follow the steps in [Configure and use Cargo with CodeArtifact](#configure-use-cargo) to configure the `cargo` CLI to use your CodeArtifact repository with proper credentials.

1. Use the following command to install Cargo crates from CodeArtifact:

   ```
   cargo add my_cargo_package@1.0.0
   ```

   For more information, see [cargo add](https://doc.rust-lang.org/cargo/commands/cargo-add.html) in *The Cargo Book*.

## Publishing Cargo crates to CodeArtifact
<a name="publish-cargo-crates"></a>

Use the following procedure to publish Cargo crates to a CodeArtifact repository using the `cargo` CLI.

1. If you haven't, follow the steps in [Configure and use Cargo with CodeArtifact](#configure-use-cargo) to configure the `cargo` CLI to use your CodeArtifact repository with proper credentials.

1. Use the following command to publish Cargo crates to a CodeArtifact repository:

   ```
   cargo publish
   ```

   For more information, see [cargo publish](https://doc.rust-lang.org/cargo/commands/cargo-publish.html) in *The Cargo Book*.

# Cargo command support
<a name="cargo-commands"></a>

The following sections summarize the Cargo commands that are supported by CodeArtifact repositories, in addition to specific commands that are not supported.

**Contents**
+ [

## Supported commands that require accessing the registry
](#supported-commands-access-the-registry)
+ [

## Unsupported commands
](#unsupported-commands)

## Supported commands that require accessing the registry
<a name="supported-commands-access-the-registry"></a>

This section lists Cargo commands where the Cargo client requires access to the registry it's been configured with. These commands have been verified to function correctly when invoked against a CodeArtifact repository.


****  

| Command | Description | 
| --- | --- | 
|   [build](https://doc.rust-lang.org/cargo/commands/cargo-build.html)   |  Builds local packages and their dependencies.  | 
|   [check](https://doc.rust-lang.org/cargo/commands/cargo-check.html)   |  Checks local packages and their dependencies for errors.  | 
|   [fetch](https://doc.rust-lang.org/cargo/commands/cargo-fetch.html)   |  Fetches the dependencies of a package.  | 
|   [publish](https://doc.rust-lang.org/cargo/commands/cargo-publish.html)   |  Publishes a package to the registry.  | 

## Unsupported commands
<a name="unsupported-commands"></a>

These Cargo commands are not supported by CodeArtifact repositories.


****  

| Command | Description | 
| --- | --- | 
|   [owner](https://doc.rust-lang.org/cargo/commands/cargo-owner.html)   |  Manages the owners of the crate on the registry.  | 
|   [search](https://doc.rust-lang.org/cargo/commands/cargo-search.html)   |  Searches for packages in the registry.  |