Skip to content

CodeArtifact

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.

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 are the top-level containers for repositories in CodeArtifact.

Create a domain with the CreateDomain API.

Terminal window
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.

Terminal window
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.

Terminal window
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 store packages and are associated with a domain.

Create a repository using the CreateRepository API.

Terminal window
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.

Terminal window
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.

Terminal window
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.

Terminal window
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

Section titled “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.

Terminal window
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.

Terminal window
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"
}
}

Use the awslocal codeartifact login command to fetch credentials for use with npm.

Terminal window
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.

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

To configure npm without using the login command

Section titled “To configure npm without using the login command”
  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.

    Terminal window
    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.

    Terminal window
    awslocal codeartifact get-repository-endpoint --domain demo-domain --repository demo-repo --format npm

    The following URL is an example repository endpoint.

    http://demo-domain-000000000000.d.codeartifact.eu-central-1.localhost.localstack.cloud/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.

    Terminal window
    npm config set registry http://demo-domain-000000000000.d.codeartifact.eu-central-1.localhost.localstack.cloud/npm/demo-repo/
  4. Use the npm config set command to add your authorization token to your npm configuration.

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

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/npm/demo-repo/
//demo-domain-000000000000.d.codeartifact.eu-central-1.localhost.localstack.cloud/:_authToken=eyJ2ZX...
//demo-domain-000000000000.d.codeartifact.eu-central-1.localhost.localstack.cloud/:always-auth=true

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
OperationImplementedImage
Page 1 of 0