CodeArtifact
Introduction
Section titled “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
Section titled “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
Section titled “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
{ "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
{ "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
{ "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
Section titled “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
{ "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
{ "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
{ "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
{ "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.
awslocal codeartifact associate-external-connection --domain demo-domain \ --repository demo-repo \ --external-connection "public:npmjs"
{ "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
{ "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" }}
Using CodeArtifact with npm
Section titled “Using CodeArtifact with npm”Configuring npm with the login command
Section titled “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
Section titled “Configuring npm manually”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”-
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) -
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 npmThe following URL is an example repository endpoint.
http://demo-domain-000000000000.d.codeartifact.eu-central-1.localhost.localstack.cloud/npm/demo-repo/ -
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/ -
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}
Example npm configuration file (.npmrc
)
Section titled “Example npm configuration file (.npmrc)”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
Current Limitations
Section titled “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
Section titled “API Coverage”Operation ▲ | Implemented | Image |
---|