Get started with AWS CodeArtifact via AWS CLI

Photo by Sigmund on Unsplash

Get started with AWS CodeArtifact via AWS CLI

In this getting started tutorial, you will use CodeArtifact to create the following:

  • A domain called my-domain.

  • A repository called my-repo that is contained in my-domain.

  • A repository called npm-store that is contained in my-domain. The npm-store has an external connection to the npm public repository. This connection is used to ingest an npm package into the my-repo repository.


External connections

In AWS CodeArtifact, an external connection refers to the ability to access and utilize package repositories hosted outside of AWS CodeArtifact. CodeArtifact is a fully managed artifact repository service provided by Amazon Web Services (AWS) that helps organizations store, publish, and manage software packages.

By setting up an external connection in AWS CodeArtifact, you can configure CodeArtifact to proxy and manage access to external package repositories. This feature allows you to leverage CodeArtifact's capabilities, such as access control, authentication, and authorization, even for packages hosted outside of CodeArtifact.

When you create an external connection, you provide the necessary configuration details, such as the external repository's endpoint URL, authentication method, and other connection-specific settings. CodeArtifact supports various external package repository formats, including npm (Node Package Manager), Maven, PyPI (Python Package Index), and NuGet.

Once the external connection is established, you can configure CodeArtifact repositories to proxy the external repositories. This means that requests made to the CodeArtifact repositories for packages will be forwarded and retrieved from the external repository, while still benefiting from CodeArtifact's features and controls.

Benefits of using external connections in AWS CodeArtifact include:

  1. Centralized management: You can consolidate access control, auditing, and artifact management for both external and internal packages in a single location, simplifying administration.

  2. Enhanced security: CodeArtifact provides features like fine-grained access control, and encryption. By leveraging external connections, you can extend these security measures to external packages as well.

  3. Improved performance: CodeArtifact can cache external packages locally, reducing network latency and improving build times for your applications.

  4. Versioning and release management: CodeArtifact allows you to control and manage versions of packages, including external packages. You can define version policies, access restrictions, and lifecycle rules for both internal and external packages.

Overall, external connections in AWS CodeArtifact enable you to integrate and manage external package repositories seamlessly within your CodeArtifact ecosystem, providing a unified experience for package management and enhancing security and performance.

Upstream repository

In AWS CodeArtifact, an upstream repository refers to a repository that acts as the source of packages for another repository. It allows you to create a hierarchical relationship between repositories, where the downstream repository depends on the packages available in the upstream repository.

When you configure an upstream repository in CodeArtifact, the downstream repository can retrieve packages from the upstream repository when they are not available locally. This capability enables you to establish a centralized location for managing and distributing packages while providing efficient package retrieval and version control.

Here are some key points to understand about upstream repositories in AWS CodeArtifact:

  1. Package retrieval: When a package is requested from a downstream repository, CodeArtifact first checks if the package is available locally. If not, it automatically fetches the package from the upstream repository and stores it in the downstream repository's cache for future use. This mechanism ensures that packages are readily available and can be retrieved efficiently.

  2. Dependency resolution: Upstream repositories are particularly useful for managing dependencies in software projects. When a downstream repository has dependencies on packages that are not present locally, CodeArtifact automatically resolves those dependencies by retrieving the required packages from the configured upstream repositories.

  3. Hierarchical structure: CodeArtifact allows you to configure multiple levels of upstream repositories, creating a hierarchical structure. This enables you to have a primary upstream repository that acts as the main source of packages, and additional upstream repositories that provide fallback options or specialized package sets. The downstream repository can retrieve packages from any level of the hierarchy based on availability and priority.

  4. Version control: Upstream repositories help enforce version control and enable consistent package distribution across repositories. The upstream repository can define version policies and access controls, ensuring that only approved and desired versions of packages are available for retrieval.

  5. Cross-account and cross-region support: CodeArtifact supports cross-account and cross-region access for upstream repositories. This allows you to centralize package management in one AWS account or region and share those packages with other accounts or regions, ensuring consistency and reducing duplication.

By utilizing upstream repositories in AWS CodeArtifact, you can streamline the management of packages and dependencies, ensure efficient package retrieval, enforce version control, and establish a centralized distribution point for your software artifacts.


In AWS CodeArtifact, a domain is a logical container for repositories. It provides a way to organize and manage multiple repositories together under a single entity. A domain in CodeArtifact represents a collection of repositories that share common settings and permissions.

Here are some key points to understand about domains in AWS CodeArtifact:

  1. Repository grouping: Domains allow you to group related repositories together. For example, you can create a domain for a specific project, team, or organization. Within a domain, you can have multiple repositories that store different types or versions of packages.

  2. Permissions and access control: Domains enable you to set permissions and access controls at a higher level. You can define fine-grained access policies for the entire domain, and those policies will apply to all repositories within the domain. This helps in managing access to multiple repositories consistently.

  3. Cross-repository actions: CodeArtifact provides cross-repository actions that can be performed within a domain. For example, you can publish a package to multiple repositories within a domain simultaneously, ensuring that the package is available across different repositories within the domain.

  4. Package sharing: Repositories within a domain can share packages with each other. This means that packages published to one repository within a domain can be consumed by other repositories within the same domain, facilitating code reuse and sharing across projects.

  5. Simplified management: By grouping repositories within a domain, you can manage common settings and configurations at the domain level. This reduces the effort of configuring each repository individually and ensures consistency across repositories within the same domain.

  6. Domain-level policies: CodeArtifact allows you to define domain-level policies to enforce governance and compliance requirements. These policies can include rules for package versions, access controls, and other domain-specific configurations.

  7. Cross-account sharing: Domains in CodeArtifact support cross-account sharing, which means you can share repositories within a domain with other AWS accounts. This enables collaboration and code sharing between teams or organizations.

Overall, domains in AWS CodeArtifact provide a way to organize and manage repositories, simplify access control and permissions, enable cross-repository actions, and facilitate package sharing. They help in structuring and governing your package management workflow, making it easier to manage and distribute software artifacts within your organization.

Configure AWS CLI:

  1. CodeArtifact commands are available in the following AWS CLI versions:

    1. AWS CLI 1: 1.18.77 and newer

    2. AWS CLI 2: 2.0.21 and newer

To check the version, use the aws --version command.

  1. Install AWS CLI

Provision an IAM user:

  1. Create an IAM user, or use one that is associated with your AWS account.

  2. Grant the IAM user access to CodeArtifact. Use the AWSCodeArtifactAdminAccess AWS managed policy.

Install your package manager or build tool:

In this tutorial, we are using npm and Node environments. To install the build tool use the following reference: Downloading and installing Node.js and npm

Getting started using the AWS CLI:

  1. Use the AWS CLI to run the create-domain command.

     aws codeartifact create-domain --domain my-domain

  2. Use the create-repository command to create a repository in your domain.

     aws codeartifact create-repository --domain my-domain --domain-owner 326213389784 --repository my-repo

  1. Use the create-repository command to create an upstream repository for your my-repo repository.

     aws codeartifact create-repository --domain my-domain --domain-owner 326213389784 --repository npm-store

  1. Use the associate-external-connection command to add an external connection to the npm public repository to your npm-store repository.

     aws codeartifact associate-external-connection --domain my-domain --domain-owner 326213389784 --repository npm-store --external-connection "public:npmjs"

For more information, see Connect a CodeArtifact repository to a public repository.

  1. Use the update-repository command to associate the npm-store repository as an upstream repository to the my-repo repository.

     aws codeartifact update-repository --repository my-repo --domain my-domain --domain-owner 326213389784 --upstreams repositoryName=npm-store

For more information, see Add or remove upstream repositories (AWS CLI).

  1. Use the login command to configure your npm package manager with your my-repo repository.

     aws codeartifact login --tool npm --repository my-repo --domain my-domain --domain-owner 326213389784

For more information, see Configure and use npm with CodeArtifact.

  1. Use the npm CLI to install an npm package. For example, to install the popular npm package lodash, use the following command.

     npm install --save-dev lodash
  2. Use the list-packages command to view the package you just installed in your my-repo repository.

     aws codeartifact list-packages --domain my-domain --repository my-repo


There may be a delay between when the npm install command completes and when the package is visible in your repository. For details on typical latency when fetching packages from public repositories, see External connection latency.

At the same time, some versions of AWS CLI has bug related to authentication with AWS CodeArtifact. More info at: As a workaround manual login configuration of the npm authentication is possible. More info at Manually setting npm registry

Clean up

To delete the resources after completing the tutorial, please refer to Getting started using the AWS CLI


  1. AWS CodeArtifact concepts