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. 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 awslocal CLI.

Basic knowledge of the AWS CLI and the awslocal wrapper 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 API.

awslocal codeartifact create-domain --domain demo-domain

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, UpdateDomain, and DeleteDomain APIs for domain management.

awslocal codeartifact describe-domain --domain demo-domain

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 API.

awslocal codeartifact list-domains

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 API.

awslocal codeartifact create-repository --domain demo-domain \
    --repository demo-repo

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, UpdateRepository, and DeleteRepository APIs to manage repositories.

awslocal codeartifact describe-repository --domain demo-domain \
    --repository demo-repo

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 API to view all of the repositories.

awslocal codeartifact list-repositories

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 API.

awslocal codeartifact list-repositories-in-domain --domain demo-domain

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. 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 and DisassociateExternalConnection APIs.

awslocal codeartifact associate-external-connection --domain demo-domain \
    --repository demo-repo \
    --external-connection "public:npmjs"

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 and UpdateRepository.

awslocal codeartifact create-repository --domain demo-domain \
    --repository demo-repo2 \
    --upstreams repositoryName=demo-repo

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 awslocal codeartifact login command to fetch credentials for use with npm.

awslocal 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.

Configuring npm manually

You can configure npm with your CodeArtifact repository without the awslocal 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.

   export CODEARTIFACT_AUTH_TOKEN=$(awslocal 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.

   awslocal codeartifact get-repository-endpoint --domain demo-domain --repository demo-repo --format npm --output text

   The following URL is an example repository endpoint.

   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.

   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.

   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.

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.

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

Operation ▲	Implemented	Image

PreviousPage 1 of 0Next