AWS CodeArtifact is a managed repository for storing, publishing, and sharing software packages. It gives package managers such as npm, pip, Maven, and NuGet a repository endpoint for internal packages and, when configured, packages fetched from public registries. You do not operate the repository servers yourself.

CodeArtifact supports Cargo, generic, Maven, npm, NuGet, PyPI, Ruby, and Swift package formats. It does not support Docker images; use Amazon Elastic Container Registry (ECR) for Docker and OCI container images. AWS lists the supported package formats and publishing tools.

How AWS CodeArtifact works

Supported package formats and tools

A repository can contain more than one package format. The format is separate from the client you use: Maven and Gradle work with Maven packages, while pip installs Python packages and twine publishes them to PyPI repositories. NuGet and dotnet work with NuGet packages; npm and pnpm use npm repositories. Generic packages let you version files that do not belong to one of the language-specific ecosystems, using the AWS CLI or SDK.

The AWS CLI's aws codeartifact login helper supports dotnet, npm, nuget, pip, swift, and twine. This list is shorter than the supported format list. For package managers that the helper does not configure, request a token with get-authorization-token and configure the tool using its documented settings. See AWS's authentication guide and package-manager setup overview.

Domains and repositories have different jobs

A domain groups repositories and provides an organization-level policy and encryption scope. Package assets and metadata in a domain share one KMS key, and a package asset is stored once per domain even when it is available from several repositories. A repository is the endpoint clients use to fetch or publish packages, and its policies can control access to that endpoint. AWS recommends a shared production domain so teams can find and reuse published artifacts; repositories can separate team, stage, or access needs within it. A repository cannot be moved to another domain, so choose a separate domain when a different encryption or administrative boundary is required. See CodeArtifact domain concepts.

Upstreams and external connections

An upstream makes packages in another CodeArtifact repository available through a downstream repository's endpoint. When a package manager requests a version, CodeArtifact checks the downstream repository first, then searches its upstreams in their configured priority order. The first matching version is returned and retained in the downstream repository.

An external connection lets a repository fetch packages from a supported public source such as npmjs.com, Maven Central, PyPI, or NuGet Gallery. A repository can have an external connection or upstream repositories, but not both. A common layout gives one repository an external connection to a public registry, then makes that repository an upstream of team repositories. AWS describes this setup in its guides to external connections and upstream search and retention.

Configure a repository for npm

First create a domain and one or more repositories, or ask the platform owner for their names and the AWS Region. To install public npm packages through CodeArtifact, the team repository must have an upstream path to a repository connected to npmjs.com. Then configure a short-lived AWS role for your local session or CI job. The commands below assume a macOS or Linux shell, an AWS CLI profile that supplies temporary role credentials, npm, and an existing repository. If you use npm 10 or newer, AWS requires AWS CLI version 2.9.5 or newer for codeartifact login. Replace every placeholder with your account's values.

export AWS_PROFILE="YOUR_SSO_OR_ASSUMED_ROLE_PROFILE"
export AWS_REGION="us-east-1"
export CODEARTIFACT_DOMAIN="YOUR_DOMAIN"
export CODEARTIFACT_DOMAIN_OWNER="123456789012"
export CODEARTIFACT_REPOSITORY="YOUR_NPM_REPOSITORY"

# Confirm which AWS identity this profile uses.
aws sts get-caller-identity --profile "$AWS_PROFILE"

# Inspect the repository's upstream and external-connection configuration.
aws codeartifact describe-repository \
  --domain "$CODEARTIFACT_DOMAIN" \
  --domain-owner "$CODEARTIFACT_DOMAIN_OWNER" \
  --repository "$CODEARTIFACT_REPOSITORY" \
  --region "$AWS_REGION" \
  --profile "$AWS_PROFILE" \
  --query 'repository.{upstreams:upstreams,externalConnections:externalConnections}' \
  --output json

# Configure npm and request a token that expires with the assumed-role session.
aws codeartifact login \
  --tool npm \
  --domain "$CODEARTIFACT_DOMAIN" \
  --domain-owner "$CODEARTIFACT_DOMAIN_OWNER" \
  --repository "$CODEARTIFACT_REPOSITORY" \
  --region "$AWS_REGION" \
  --profile "$AWS_PROFILE" \
  --duration-seconds 0

# Check that npm can authenticate and read from the repository.
npm ping

# If the repository has an npmjs.com upstream, check public package resolution.
npm view lodash version

The npm ping command checks authentication and read permission without depending on a particular package. The final command assumes the repository can reach npmjs.com through an upstream. For an internal-only repository, use a package that is already present and that your role may read. These checks do not print the authorization token.

Security and publishing practices

Grant the role the required permissions

To request a CodeArtifact token and configure npm, the IAM user or role needs codeartifact:GetAuthorizationToken, sts:GetServiceBearerToken, and codeartifact:GetRepositoryEndpoint. The sts:GetServiceBearerToken permission must be granted in an identity policy; adding it only to a CodeArtifact domain resource policy has no effect. A consuming role needs codeartifact:ReadFromRepository on the repository. The example's configuration check also requires codeartifact:DescribeRepository. A publishing role needs the format-specific package publishing actions, such as codeartifact:PublishPackageVersion; Maven and NuGet have additional requirements. Keep read and publish roles separate where practical, and scope package and repository permissions to the resources they need. For cross-account access, include the relevant domain or repository resource policy as well as the caller's IAM permissions. Check AWS's token permission requirements, IAM action reference, and publishing permission table.

Treat authorization tokens as secrets

A CodeArtifact token is a bearer credential. The default lifetime is 12 hours; you can set it from 900 seconds to 43,200 seconds. When you call login or get-authorization-token using assumed-role credentials, --duration-seconds 0 makes the token expire with the remaining role session. Without zero, the token lifetime is independent of the role session and can outlast it. Use a short duration for automation.

For npm, login writes the endpoint and authorization token to ~/.npmrc. Do not commit or cache that file, include it in a container image, or print the token in build logs. In CI, use the job's temporary role credentials and run login in an ephemeral job environment; omit --profile so the AWS CLI uses the job identity. For tools that need a manually configured token, AWS recommends passing it through an environment variable instead of saving it in a file that could be read or checked in. The token lifetime and storage behavior are documented in AWS's authentication and token guide and npm setup guide. For a broader example of temporary identities and safer cloud CI checks, see our AWS end-to-end testing guide.

Control where package versions can come from

CodeArtifact package and package-group origin controls can allow or block direct publishing and versions ingested from upstream sources. Use them to keep private package names from being fetched from a public registry, a dependency-substitution risk. Review the controls for your own package names and repositories: defaults can depend on how the first version entered the repository. Origin controls govern permitted sources; they do not scan a package or prove that its code is safe. See AWS's guides to package origin controls and package-group controls.

Publish versions deliberately and clean them up carefully

Do not reuse a published package version as a general-purpose mutable release. CodeArtifact rejects replacing an existing asset with different content. Some formats, including Maven and PyPI, can add separately named assets to an existing version, which creates a new package-version revision; npm versions have a single asset. Publish a new version for a fix and retain the build inputs needed to reproduce it. The details vary by format, as AWS explains in its package publishing documentation.

Deleting a package version removes it from that repository and can break consumers that resolve it there. AWS recommends copying a version to a backup repository before deleting it. Also check downstream repositories: versions already retained from an upstream remain available there even if the upstream repository, relationship, or source version is later removed. Inventory repositories and consumers before cleanup, and verify each deletion. See AWS's package deletion guidance and upstream retention behavior.

How CodeArtifact pricing works

AWS bills CodeArtifact based on artifact storage over time, requests, and applicable data transfer out of an AWS Region. Requests used to fetch artifacts from public package sources also count. The service has a monthly Free Tier for storage and requests, but check current terms, rates, and your Region in the CodeArtifact pricing page and AWS Pricing Calculator; do not rely on old fixed request or storage allowances. Assets are deduplicated within a domain, which can reduce repeated storage for packages shared across repositories.

AWS CodeArtifact FAQs

What is a package in CodeArtifact?

A package is a named software bundle with one or more versions, assets such as archives or binaries, and package metadata. A version may contain multiple assets, depending on the package format.

Does CodeArtifact support Docker images?

No. CodeArtifact supports Cargo, generic, Maven, npm, NuGet, PyPI, Ruby, and Swift packages. Use Amazon ECR for Docker or OCI container images.

Is CodeArtifact inside my VPC?

CodeArtifact is a managed AWS service. You can access its public service endpoints or configure same-Region interface VPC endpoints using AWS PrivateLink so traffic between your VPC and CodeArtifact stays on the AWS network. A private path requires separate interface endpoints for the CodeArtifact API and repository endpoints. Package downloads also use Amazon S3: most formats need an S3 gateway endpoint for package assets, while Python and Swift do not. Plan all three endpoint paths where needed before removing internet egress. See AWS's VPC endpoint guide and S3 gateway endpoint guidance.

How much does CodeArtifact cost?

Cost depends on stored artifacts, requests, and applicable data transfer out of the Region. Check the current AWS pricing page and calculator for your Region and usage rather than using an old fixed Free Tier figure.

Conclusion

CodeArtifact is useful when teams need private package publishing, shared dependencies, or a controlled path to public registries. Start with a domain that fits your organization and encryption boundary, use repositories for client endpoints and access patterns, grant short-lived roles only the required actions, and decide explicitly which package origins are allowed. For container images, use ECR.