# CodeArtifact

Source: /aws/services/codeartifact/

## Introduction

CodeArtifact is a fully managed artifact repository service that makes it easy to securely store, publish, and share software packages used in your development process.

On AWS, CodeArtifact supports popular package formats such as Maven, npm, Python (pip), NuGet, etc.
You can configure it to work with public repositories or use it to store your private packages.

LocalStack provides mocking support for several CodeArtifact API operations.
You can find supported operations on the [API coverage page](#api-coverage).
It also has full support to create and use NPM repositories.

## Getting Started

This guide will help you create a domain, repository, and manage package publishing workflows using the `lstk aws` command.

Basic knowledge of the AWS CLI and the [`lstk aws`](/aws/developer-tools/running-localstack/lstk/cloud-and-iac-commands/#aws) command is expected.

Start LocalStack using your preferred method.

### Domains

Domains are the top-level containers for repositories in CodeArtifact.

Create a domain with the [`CreateDomain`](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_CreateDomain.html) API.

```bash
lstk aws codeartifact create-domain --domain demo-domain
```

```json title="Output"
{
    "domain": {
        "name": "demo-domain",
        "owner": "000000000000",
        "arn": "arn:aws:codeartifact:eu-central-1:000000000000:domain/demo-domain",
        "status": "Active",
        "createdTime": "2025-05-20T11:30:52.073202+02:00",
        "repositoryCount": 0,
        "assetSizeBytes": 0
    }
}
```

You can use the [`DescribeDomain`](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_DescribeDomain.html), [`UpdateDomain`](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_UpdateDomain.html), and [`DeleteDomain`](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_DeleteDomain.html) APIs for domain management.

```bash
lstk aws codeartifact describe-domain --domain demo-domain
```

```json title="Output"
{
    "domain": {
        "name": "demo-domain",
        "owner": "000000000000",
        "arn": "arn:aws:codeartifact:eu-central-1:000000000000:domain/demo-domain",
        "status": "Active",
        "createdTime": "2025-05-20T11:30:52.073202+02:00",
        "repositoryCount": 0,
        "assetSizeBytes": 0
    }
}
```

You can list all domains using the [`ListDomains`](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_ListDomains.html) API.

```bash
lstk aws codeartifact list-domains
```

```json title="Output"
{
    "domains": [
        {
            "name": "demo-domain",
            "owner": "000000000000",
            "arn": "arn:aws:codeartifact:eu-central-1:000000000000:domain/demo-domain",
            "status": "Active",
            "createdTime": "2025-05-20T11:30:52.073202+02:00"
        }
    ]
}
```

### Repositories

Repositories store packages and are associated with a domain.

Create a repository using the [`CreateRepository`](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_CreateRepository.html) API.

```bash
lstk aws codeartifact create-repository --domain demo-domain \
    --repository demo-repo
```

```json title="Output"
{
    "repository": {
        "name": "demo-repo",
        "administratorAccount": "000000000000",
        "domainName": "demo-domain",
        "domainOwner": "000000000000",
        "arn": "arn:aws:codeartifact:eu-central-1:000000000000:repository/demo-domain/demo-repo",
        "upstreams": [],
        "externalConnections": [],
        "createdTime": "2025-05-20T11:34:27.712367+02:00"
    }
}
```

You can use the [`DescribeRepository`](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_DescribeRepository.html), [`UpdateRepository`](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_UpdateRepository.html), and [`DeleteRepository`](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_DeleteRepository.html) APIs to manage repositories.

```bash
lstk aws codeartifact describe-repository --domain demo-domain \
    --repository demo-repo
```

```json title="Output"
{
    "repository": {
        "name": "demo-repo",
        "administratorAccount": "000000000000",
        "domainName": "demo-domain",
        "domainOwner": "000000000000",
        "arn": "arn:aws:codeartifact:eu-central-1:000000000000:repository/demo-domain/demo-repo",
        "upstreams": [],
        "externalConnections": [],
        "createdTime": "2025-05-20T11:34:27.712367+02:00"
    }
}
```

Use the [`ListRepositories`](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_ListRepositories.html) API to view all of the repositories.

```bash
lstk aws codeartifact list-repositories
```

```json title="Output"
{
    "repositories": [
        {
            "name": "demo-repo",
            "administratorAccount": "000000000000",
            "domainName": "demo-domain",
            "domainOwner": "000000000000",
            "arn": "arn:aws:codeartifact:eu-central-1:000000000000:repository/demo-domain/demo-repo",
            "createdTime": "2025-05-20T11:34:27.712367+02:00"
        }
    ]
}
```

Otherwise, list repositories in a specific domain using the [`ListRepositoriesInDomain`](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_ListRepositoriesInDomain.html) API.

```bash
lstk aws codeartifact list-repositories-in-domain --domain demo-domain
```

```json title="Output"
{
    "repositories": [
        {
            "name": "demo-repo",
            "administratorAccount": "000000000000",
            "domainName": "demo-domain",
            "domainOwner": "000000000000",
            "arn": "arn:aws:codeartifact:eu-central-1:000000000000:repository/demo-domain/demo-repo",
            "createdTime": "2025-05-20T11:34:27.712367+02:00"
        }
    ]
}
```

### Upstream Repositories and External Connections

A repository can have other CodeArtifact repositories as upstream repositories.
This enables a package manager client to access the packages that are contained in more than one repository using a single repository endpoint.

Furthermore, you can add a external connection between a CodeArtifact repository and an external, public repository such as [https://npmjs.com](https://npmjs.com).
Then, when you request a package from the CodeArtifact repository that's not already present in the repository, the package can be fetched from the external connection.
This makes it possible to consume open-source dependencies used by your application.

Repositories can be associated with external connections using [AssociateExternalConnection](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_AssociateExternalConnection.html) and [DisassociateExternalConnection](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_DisassociateExternalConnection.html) APIs.

```bash
lstk aws codeartifact associate-external-connection --domain demo-domain \
    --repository demo-repo \
    --external-connection "public:npmjs"
```

```json title="Output"
{
    "repository": {
        "name": "demo-repo",
        "administratorAccount": "000000000000",
        "domainName": "demo-domain",
        "domainOwner": "000000000000",
        "arn": "arn:aws:codeartifact:eu-central-1:000000000000:repository/demo-domain/demo-repo",
        "upstreams": [],
        "externalConnections": [
            {
                "externalConnectionName": "public:npmjs",
                "packageFormat": "npm",
                "status": "AVAILABLE"
            }
        ],
        "createdTime": "2025-05-20T14:03:27.539994+02:00"
    }
}
```

Alternatively, repositories can be configured with upstream repositories using the `upstreams` property of [CreateRepository](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_CreateRepository.html) and [UpdateRepository](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_UpdateRepository.html).

```bash
lstk aws codeartifact create-repository --domain demo-domain \
    --repository demo-repo2 \
    --upstreams repositoryName=demo-repo
```

```bash title="Output"
{
    "repository": {
        "name": "demo-repo2",
        "administratorAccount": "000000000000",
        "domainName": "demo-domain",
        "domainOwner": "000000000000",
        "arn": "arn:aws:codeartifact:eu-central-1:000000000000:repository/demo-domain/demo-repo2",
        "upstreams": [
            {
                "repositoryName": "demo-repo"
            }
        ],
        "externalConnections": [],
        "createdTime": "2025-05-20T14:07:56.741333+02:00"
    }
}
```

:::note
Please note, a repository can have one or more upstream repositories, or an external connection.
:::

## Using CodeArtifact with npm

### Configuring npm with the login command

Use the `lstk aws codeartifact login` command to fetch credentials for use with npm.

```bash
lstk aws codeartifact login --tool npm --domain demo-domain --repository demo-repo
```

This command makes the following changes to your `~/.npmrc` file:

- Adds an authorization token after fetching it from CodeArtifact using your AWS credentials.
- Sets the npm registry to the repository specified by the `--repository` option.
- **For npm 6 and lower:** Adds `"always-auth=true"` so the authorization token is sent for every npm command.

The default authorization period after calling login is 12 hours, and login must be called to periodically refresh the token.
For more information about the authorization token created with the login command, see [Tokens created with the login command](https://docs.aws.amazon.com/codeartifact/latest/ug/tokens-authentication.html#auth-token-login).

### Configuring npm manually

You can configure npm with your CodeArtifact repository without the `lstk aws codeartifact login` command by manually updating the npm configuration.

1. In a command line, fetch a CodeArtifact authorization token and store it in an environment variable.
  npm will use this token to authenticate with your CodeArtifact repository.

    ```bash
    export CODEARTIFACT_AUTH_TOKEN=$(lstk aws codeartifact get-authorization-token --domain demo-domain --query authorizationToken --output text)
    ```

2. Get your CodeArtifact repository's endpoint by running the following command.
  Your repository endpoint is used to point npm to your repository to install or publish packages.

    ```bash
    lstk aws codeartifact get-repository-endpoint --domain demo-domain --repository demo-repo --format npm --output text
    ```

    The following URL is an example repository endpoint.

    ```text
    http://demo-domain-000000000000.d.codeartifact.eu-central-1.localhost.localstack.cloud:4566/npm/demo-repo/
    ```

3. Use the `npm config set` command to set the registry to your CodeArtifact repository.
  Replace the URL with the repository endpoint URL from the previous step.

    ```bash
    npm config set registry http://demo-domain-000000000000.d.codeartifact.eu-central-1.localhost.localstack.cloud:4566/npm/demo-repo/
    ```

4. Use the `npm config set` command to add your authorization token to your npm configuration.

    ```bash
    npm config set //demo-domain-000000000000.d.codeartifact.eu-central-1.localhost.localstack.cloud:4566/:_authToken=${CODEARTIFACT_AUTH_TOKEN}
    ```

:::note
**For npm 6 or lower:** To make npm always pass the auth token to CodeArtifact, even for GET requests, set the always-auth configuration variable with npm config set.

```bash
npm config set //demo-domain-000000000000.d.codeartifact.eu-central-1.localhost.localstack.cloud:4566/:always-auth=true
```
:::

### Example npm configuration file

The following is an example `.npmrc` file after following the preceding instructions to set the CodeArtifact registry endpoint, add an authentication token, and configure `always-auth`.

```text
registry=http://demo-domain-000000000000.d.codeartifact.eu-central-1.localhost.localstack.cloud:4566/npm/demo-repo/
//demo-domain-000000000000.d.codeartifact.eu-central-1.localhost.localstack.cloud:4566/:_authToken=eyJ2ZX...
//demo-domain-000000000000.d.codeartifact.eu-central-1.localhost.localstack.cloud:4566/:always-auth=true
```

## Current Limitations

LocalStack does not support the following features yet:

- Domain owners are ignored
- Copying package versions is not supported yet
- Domain and repository permission policies are not supported yet
- Package groups are not supported yet
- Only supports the `npm` format

## API Coverage


### codeartifact API coverage

Source service: `codeartifact`. 21 of 48 tracked operations are implemented.

Service documentation: /aws/services/codeartifact/
License availability: available starting with the Base plan. See /aws/licensing/ for current plan details.

| Operation | Status |
| --- | --- |
| AssociateExternalConnection | Implemented |
| CopyPackageVersions | Not implemented |
| CreateDomain | Implemented |
| CreatePackageGroup | Not implemented |
| CreateRepository | Implemented |
| DeleteDomain | Implemented |
| DeleteDomainPermissionsPolicy | Not implemented |
| DeletePackage | Not implemented |
| DeletePackageGroup | Not implemented |
| DeletePackageVersions | Not implemented |
| DeleteRepository | Implemented |
| DeleteRepositoryPermissionsPolicy | Not implemented |
| DescribeDomain | Implemented |
| DescribePackage | Not implemented |
| DescribePackageGroup | Not implemented |
| DescribePackageVersion | Not implemented |
| DescribeRepository | Implemented |
| DisassociateExternalConnection | Implemented |
| DisposePackageVersions | Not implemented |
| GetAssociatedPackageGroup | Not implemented |
| GetAuthorizationToken | Implemented |
| GetDomainPermissionsPolicy | Not implemented |
| GetPackageVersionAsset | Not implemented |
| GetPackageVersionReadme | Not implemented |
| GetRepositoryEndpoint | Implemented |
| GetRepositoryPermissionsPolicy | Not implemented |
| ListAllowedRepositoriesForGroup | Not implemented |
| ListAssociatedPackages | Not implemented |
| ListDomains | Implemented |
| ListPackageGroups | Not implemented |
| ListPackageVersionAssets | Implemented |
| ListPackageVersionDependencies | Not implemented |
| ListPackageVersions | Implemented |
| ListPackages | Implemented |
| ListRepositories | Implemented |
| ListRepositoriesInDomain | Implemented |
| ListSubPackageGroups | Not implemented |
| ListTagsForResource | Implemented |
| PublishPackageVersion | Not implemented |
| PutDomainPermissionsPolicy | Not implemented |
| PutPackageOriginConfiguration | Implemented |
| PutRepositoryPermissionsPolicy | Not implemented |
| TagResource | Implemented |
| UntagResource | Implemented |
| UpdatePackageGroup | Not implemented |
| UpdatePackageGroupOriginConfiguration | Not implemented |
| UpdatePackageVersionsStatus | Not implemented |
| UpdateRepository | Implemented |