CodeArtifact User Guide CodeArtifact

(1)

CodeArtifact

CodeArtifact User Guide

CodeArtifact: CodeArtifact User Guide

(2)

Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may not be aﬃliated with, connected to, or sponsored by Amazon.

(3)

What is AWS CodeArtifact?

CodeArtifact is a fully managed artifact repository service that makes it easy for organizations to securely store and share software packages used for application development. You can use CodeArtifact with popular build tools and package managers such as NuGet, Maven, Gradle, npm, yarn, pip, and twine.

CodeArtifact automatically scales when you ingest or publish new packages to your repositories. Because it's a fully managed service, the setup and operation of its infrastructure is done for you. Integration with AWS Key Management Service (AWS KMS) secures all assets in a domain with one AWS KMS key (KMS key) that either you manage or AWS manages for you.

For more information, see AWS CodeArtifact.

How does CodeArtifact work?

CodeArtifact stores software packages in repositories. Repositories are polyglot—a single repository can contain packages of any supported type. Every CodeArtifact repository is a member of a single CodeArtifact domain. We recommend that you use one production domain for your organization with one or more repositories. For example, each repository might be used for a diﬀerent development team.

Packages in your repositories can then be discovered and shared across your development teams.

To add packages to a repository, conﬁgure a package manager such as npm or maven to use the

repository endpoint (URL). You can then use the package manager to publish packages to repository. You can also import open-source packages into a repository by conﬁguring it with an external connection to a public repository such as npmjs, NuGet Gallery, Maven Central, or PyPI. For more information, see Add an external connection (p. 26).

You can make packages in one repository available to another repository in the same domain. To do this, conﬁgure one repository as an upstream of the other. All package versions available to the upstream repository are also available to the downstream repository. In addition, all packages that are available to the upstream repository through an external connection to a public repository are available to the downstream repository. For more information, see Working with upstream repositories in CodeArtifact (p. 38).

AWS CodeArtifact Concepts

Here are some concepts and terms to know when you use CodeArtifact.

Topics

• Domain (p. 2)

• Repository (p. 2)

• Package (p. 2)

• Package version (p. 2)

• Package version revision (p. 2)

• Upstream repository (p. 2)

• Asset (p. 3)

• Package namespace (p. 3)

(9)

Domain

Repositories are aggregated into a higher-level entity known as a domain. All package assets and metadata are stored in the domain, but they are consumed through repositories. A given package asset, such as a Maven JAR ﬁle, is stored once per domain, no matter how many repositories it's present in. All of the assets and metadata in a domain are encrypted with the same AWS KMS key (KMS key) stored in AWS Key Management Service (AWS KMS).

Each repository is a member of a single domain and can't be moved to a diﬀerent domain.

The domain allows organizational policy to be applied across multiple repositories, such as which accounts can access repositories in the domain, and which public repositories can be used as sources of packages.

Although an organization can have multiple domains, we recommend a single production domain that contains all published artifacts so that teams can ﬁnd and share packages across their organization.

Repository

A CodeArtifact repository contains a set of package versions (p. 2), each of which maps to a set of assets (p. 3). Repositories are polyglot—a single repository can contain packages of any supported type. Each repository exposes endpoints for fetching and publishing packages using tools like the nuget CLI, the npm CLI, the Maven CLI (mvn), and pip. You can create up to 1000 repositories per domain.

Package

A package is a bundle of software and the metadata that is required to resolve dependencies and install the software. In CodeArtifact, a package consists of a package name, an optional namespace (p. 3) such as @types in @types/node, a set of package versions, and package-level metadata such as npm tags.

AWS CodeArtifact supports npm (p. 85), PyPI (p. 97), Maven (p. 102), and NuGet (p. 115) package formats.

Package version

A package version identifies the specific version of a package, such as @types/node 12.6.9. The version number format and semantics vary for different package formats. For example, npm package versions must conform to the Semantic Versioning specification. In CodeArtifact, a package version consists of the version identifier, package version level metadata, and a set of assets.

Package version revision

A package version revision is a string that identiﬁes a speciﬁc set of assets and metadata for a package version. Each time a package version is updated, a new package version revision is created. For example, you might publish a source distribution archive (sdist) for a Python package version, and later add a Python wheel that contains compiled code to the same version. When you publish the wheel, a new package version revision is created.

Upstream repository

One repository is upstream of another when the package versions in it can be accessed from the repository endpoint of the downstream repository, eﬀectively merging the contents of the two repositories from the point of view of a client. CodeArtifact allows creating an upstream relationship between two repositories.

(10)

Asset

An asset is an individual file stored in CodeArtifact that is associated with a package version, such as an npm .tgz file or Maven POM and JAR files.

Package namespace

Some package formats support hierarchical package names to organize packages into logical groups and help avoid name collisions. For example, npm supports scopes, see the npm scopes documentation for more information. The npm package @types/node has a scope of @types and a name of node. There are many other package names in the @types scope. In CodeArtifact, the scope (“types”) is referred to as the package namespace and the name (“node”) is referred to as the package name. For Maven packages, the package namespace corresponds to the Maven groupID.

The Maven package org.apache.logging.log4j:log4j has a groupID (package namespace) of org.apache.logging.log4j and the artifactID (package name) log4j. Some package formats such as PyPI don't support hierarchical names with a concept similar to npm scope or Maven groupID. Without a way to group package names, it can be more diﬃcult to avoid name collisions.

How do I get started with CodeArtifact?

We recommend that you complete the following steps:

1. Learn more about CodeArtifact by reading the information in AWS CodeArtifact Concepts (p. 1).

2. Set up your AWS account, the AWS CLI, and an IAM user by following the steps in Setting up with AWS CodeArtifact (p. 4).

3. Use CodeArtifact by following the instructions in Getting started with CodeArtifact (p. 7).

(11)

Sign up for AWS

Setting up with AWS CodeArtifact

If you've already signed up for Amazon Web Services (AWS), you can start using CodeArtifact immediately. You can open the CodeArtifact console, choose Create a domain and repository, and follow the steps in the launch wizard to create your ﬁrst domain and repository.

If you haven't signed up for AWS yet, or need assistance creating your ﬁrst domain and repository, complete the following tasks to get set up to use CodeArtifact:

Topics

• Sign up for AWS (p. 4)

• Install or upgrade and then conﬁgure the AWS CLI (p. 4)

• Provision an IAM User (p. 5)

• Install your package manager or build tool (p. 6)

Sign up for AWS

When you sign up for Amazon Web Services (AWS), your AWS account is automatically signed up for all services in AWS, including CodeArtifact. You are charged only for the services that you use. With CodeArtifact, you pay only for what you use.

If you already have an AWS account, skip to the next task, Install or upgrade and then conﬁgure the AWS CLI (p. 4). If you don't have an AWS account, use the following procedure to create one.

To create an AWS account

1. Open https://portal.aws.amazon.com/billing/signup.

2. Follow the online instructions.

Part of the sign-up procedure involves receiving a phone call and entering a veriﬁcation code on the phone keypad.

Install or upgrade and then conﬁgure the AWS CLI

To call CodeArtifact commands from the AWS Command Line Interface (AWS CLI) on a local development machine, you must install the AWS CLI.

If you have an older version of the AWS CLI installed, you must upgrade it so the CodeArtifact commands are available. 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.

To install and conﬁgure the AWS CLI

1. Install or upgrade the AWS CLI with the instructions in Installing the AWS Command Line Interface.

(12)

Provision an IAM User

2. Conﬁgure the AWS CLI, with the conﬁgure command, as follows.

aws configure

When prompted, specify the AWS access key and AWS secret access key of the IAM user that you will use with CodeArtifact. When prompted for the default region name, specify the region where you will create the pipeline, such as us-east-2. When prompted for the default output format, specify json.

Important

When you conﬁgure the AWS CLI, you are prompted to specify an AWS Region. Choose one of the supported regions listed in Region and Endpoints in the AWS General Reference.

For more information, see Conﬁguring the AWS Command Line Interface and Managing Access Keys for IAM Users.

3. To verify the installation or upgrade, call the following command from the AWS CLI.

aws codeartifact help

If successful, this command displays a list of available CodeArtifact commands.

Next, you can create an IAM user and grant that user access to CodeArtifact. For more information, see Provision an IAM User (p. 5).

Provision an IAM User

Follow these instructions to prepare an IAM user to use CodeArtifact.

To provision an IAM user

1. Create an IAM user, or use one that is associated with your AWS account. For more information, see Creating an IAM User and Overview of AWS IAM Policies in the IAM User Guide.

2. Grant the IAM user access to CodeArtifact.

• Option 1: Create a custom IAM policy. With a custom IAM policy, you can provide the minimum required permissions and change how long authentication tokens last. See Using identity-based policies for AWS CodeArtifact (p. 147) for more information and example policies.

• Option 2: Use the AWSCodeArtifactAdminAccess AWS managed policy. The following snippet shows the contents of this policy.

Important

This policy grants access to all CodeArtifact APIs. We recommend that you always use the minimum permissions required to accomplish your task. For more information, see IAM Best Practices in the IAM User Guide.

{ "Version": "2012-10-17", "Statement": [

{

"Action": [

"codeartifact:*"

],

"Effect": "Allow", "Resource": "*"

},

(13)

Install your package manager or build tool

{

"Effect": "Allow",

"Action": "sts:GetServiceBearerToken", "Resource": "*",

"Condition": { "StringEquals": {

"sts:AWSServiceName": "codeartifact.amazonaws.com"

} } } ] }

The sts:GetServiceBearerToken permission is required to call the CodeArtifact

GetAuthorizationToken API. This API returns a token that must be used when using a package manager such as npm or pip with CodeArtifact. To use a package manager with a CodeArtifact repository, your IAM user or role must Allow sts:GetServiceBearerToken as shown in the policy example above.

If you haven't installed the package manager or build tool that you plan to use with CodeArtifact, see Install your package manager or build tool (p. 6).

Install your package manager or build tool

If you have not already, install the package manager or build tool that you want to use with CodeArtifact.

• For npm, you can use the npm CLI or pnpm.

• For Maven, you can use either Maven (mvn) or Gradle.

• For Python, you can use pip to install packages and twine to upload packages to CodeArtifact.

• For NuGet, you can use the AWS Toolkit for Visual Studio Code in Visual Studio or the nuget or dotnet CLIs.

(14)

Prerequisites

Getting started with CodeArtifact

In this getting started tutorial, you 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.

Before starting this tutorial, we recommend that you review CodeArtifact AWS CodeArtifact Concepts (p. 1).

NoteThis tutorial requires you to create resources that might result in charges to your AWS account.

For more information, see CodeArtifact pricing.

Topics

• Prerequisites (p. 7)

• Getting started using the console (p. 7)

• Getting started using the AWS CLI (p. 9)

Prerequisites

You can complete this tutorial using the AWS Management Console or the AWS Command Line Interface (AWS CLI). To follow the tutorial, you must ﬁrst complete the following prerequisites:

• Complete the steps in Setting up with AWS CodeArtifact (p. 4).

• Install the npm CLI. For more information, see Downloading and installing Node.js and npm in the npm documentation.

Getting started using the console

Run the following steps to get started with CodeArtifact using the AWS Management Console. This guide uses the npm package manager, if you are using a diﬀerent package manager, you will need to modify some of the following steps.

1. Sign in to the AWS Management Console and open the AWS CodeArtifact console at https://

console.aws.amazon.com/codesuite/codeartifact/start. For more information, see Setting up with AWS CodeArtifact (p. 4).

2. Choose Create repository.

3. In Repository name, enter my-repo.

4. (Optional) In Repository Description, enter an optional description for your repository.

5. In Public upstream repositories, select npm-store to create a repository connected to npmjs that is upstream from your my-repo repository.

CodeArtifact assigns the name npm-store to this repository for you. All packages available in the upstream repository npm-store are also available to its downstream repository, my-repo.

6. Choose Next.

7. In AWS account, choose This AWS account.

(15)

Getting started using the console

8. In Domain name, enter my-domain.

9. Expand Additional conﬁguration.

10. You must use an AWS KMS key (KMS key) to encrypt all assets in your domain. You can use an AWS managed key or a KMS key that you manage:

• Choose AWS managed key if you want to use the default AWS managed key.

• Choose Customer managed key if you want to use a KMS key that you manage. To use a KMS key that you manage, in Customer managed key ARN, search for and choose the KMS key.

For more information, see AWS managed key and Customer managed key in the AWS Key Management Service Developer Guide.

11. Choose Next.

12. In Review and create, review what CodeArtifact is creating for you.

• Package ﬂow shows how my-domain, my-repo, and npm-store are related.

• Step 1: Create repository shows details about my-repo and npm-store.

• Step 2: Select domain shows details about my-domain.

When you're ready, choose Create repository.

13. On the my-repo page, choose View connection instructions, and then choose npm.

14. Use the AWS CLI to run the login command shown under Conﬁgure your npm client using this AWS CLI CodeArtifact command.

aws codeartifact login --tool npm --repository my-repo --domain my-domain --domainowner 111122223333

You should receive output conﬁrming your login succeeded.

Successfully configured npm to use AWS CodeArtifact repository https://my- domain-111122223333.d.codeartifact.us-east-2.amazonaws.com/npm/my-repo/

Login expires in 12 hours at 2020-10-08 02:45:33-04:00

If you receive the error Could not connect to the endpoint URL, make sure that your AWS CLI is conﬁgured and that your Default region name is set to the same region where you created your repository, see Conﬁguring the AWS Command Line Interface.

For more information, see Conﬁgure and use npm with CodeArtifact (p. 85)

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

npm install lodash

16. Return to the CodeArtifact console. If your my-repo repository is open, refresh the page. Otherwise, in the navigation pane, choose Repositories, and then choose my-repo.

Under Packages, you should see the npm library, or package, that you installed. You can choose the name of the package to view its version and status. You can choose its latest version to view package details such as dependencies, assets, and more.

NoteThere may be a delay between when you install the package and when it is ingested into your repository.

17. To avoid further AWS charges, delete the resources that you used during this tutorial:

(16)

Getting started using the AWS CLI

NoteYou cannot delete a domain that contains repositories, so you must delete my-repo and npm-store before you delete my-domain.

a. From the navigation pane, choose Repositories.

b. Choose npm-store, choose Delete, and then follow the steps to delete the repository.

c. Choose my-repo, choose Delete, and then follow the steps to delete the repository.

d. From the navigation pane, choose Domains.

e. Choose my-domain, choose Delete, and then follow the steps to delete the domain.

Getting started using the AWS CLI

Run the following steps to get started with CodeArtifact using the AWS Command Line Interface (AWS CLI). For more information, see Install or upgrade and then conﬁgure the AWS CLI (p. 4). This guide uses the npm package manager, if you are using a diﬀerent package manager, you will need to modify some of the following steps.

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

aws codeartifact create-domain --domain my-domain

JSON-formatted data appears in the output with details about your new domain.

{ "domain": {

"name": "my-domain", "owner": "111122223333",

"arn": "arn:aws:codeartifact:us-west-2:111122223333:domain/my-domain", "status": "Active",

"createdTime": "2020-10-07T15:36:35.194000-04:00",

"encryptionKey": "arn:aws:kms:us-west-2:111122223333:key/your-kms-key", "repositoryCount": 0,

"assetSizeBytes": 0 }

}

If you receive the error Could not connect to the endpoint URL, make sure that your AWS CLI is conﬁgured and that your Default region name is set to the same region where you created your repository, see Conﬁguring the AWS Command Line Interface.

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

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

JSON-formatted data appears in the output with details about your new repository.

{ "repository": { "name": "my-repo",

"administratorAccount": "111122223333", "domainName": "my-domain",

"domainOwner": "111122223333",

"arn": "arn:aws:codeartifact:us-west-2:111122223333:repository/my-domain/my- repo",

(17)

"upstreams": [],

"externalConnections": []

} }

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

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

JSON-formatted data appears in the output with details about your new repository.

{ "repository": {

"name": "npm-store",

"domainOwner": "111122223333",

"arn": "arn:aws:codeartifact:us-west-2:111122223333:repository/my-domain/npm- store",

"upstreams": [],

} }

4. 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 --domainowner 111122223333 --repository npm-store --external-connection "public:npmjs"

JSON-formatted data appears in the output with details about the repository and its new external connection.

{ "repository": {

"domainOwner": "111122223333",

"arn": "arn:aws:codeartifact:us-west-2:111122223333:repository/my-domain/npm- store",

"upstreams": [],

"externalConnections": [ {

"externalConnectionName": "public:npmjs", "packageFormat": "npm",

"status": "AVAILABLE"

} ] } }

For more information, see Add an external connection (p. 26).

5. 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 --domainowner 111122223333 --upstreams repositoryName=npm-store

(18)

JSON-formatted data appears in the output with details about your updated repository, including its new upstream repository.

{

"repository": { "name": "my-repo",

"domainOwner": "111122223333",

"arn": "arn:aws:codeartifact:us-west-2:111122223333:repository/my-domain/my- repo",

"upstreams": [ {

"repositoryName": "npm-store"

} ],

} }

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

6. Use the login command to conﬁgure your npm package manager with your my-repo repository.

aws codeartifact login --tool npm --repository my-repo --domain my-domain --domainowner 111122223333

You should receive output conﬁrming your login succeeded.

Successfully configured npm to use AWS CodeArtifact repository https://my- domain-111122223333.d.codeartifact.us-east-2.amazonaws.com/npm/my-repo/

Login expires in 12 hours at 2020-10-08 02:45:33-04:00

For more information, see Conﬁgure and use npm with CodeArtifact (p. 85).

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

npm install lodash

8. Use the list-packages command to view the package you just installed in your my-repo repository.

Note

There may be a delay between when you install the package and when it is ingested into your repository.

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

JSON-formatted data appears in the output with the format and name of the package that you installed.

{ "packages": [ {

"format": "npm", "package": "lodash"

} ]

(19)

}

You now have three CodeArtifact resources:

• The domain my-domain.

• The repository my-repo that is contained in my-domain. This repository has an npm package available to it.

• The repository npm-store that is contained in my-domain. This repository has an external connection to the public npm repository and is associated as an upstream repository with the my- repo repository.

9. To avoid further AWS charges, delete the resources that you used during this tutorial:

Note

You cannot delete a domain that contains repositories, so you must delete my-repo and npm-store before you delete my-domain.

a. Use the delete-repository command to delete the npm-store repository.

aws codeartifact delete-repository --domain my-domain --domain-owner 111122223333 --repository my-repo

JSON-formatted data appears in the output with details about the deleted repository.

{ "repository": { "name": "my-repo",

"domainOwner": "111122223333",

"arn": "arn:aws:codeartifact:us-west-2:111122223333:repository/my- domain/my-repo",

"upstreams": [ {

"repositoryName": "npm-store"

} ],

} }

b. Use the delete-repository command to delete the npm-store repository.

aws codeartifact delete-repository --domain my-domain --domain-owner 111122223333 --repository npm-store

JSON-formatted data appears in the output with details about the deleted repository.

{ "repository": {

"domainOwner": "111122223333",

"arn": "arn:aws:codeartifact:us-west-2:111122223333:repository/my- domain/npm-store",

"upstreams": [],

(20)

"packageFormat": "npm", "status": "AVAILABLE"

} ] } }

c. Use the delete-domain command to delete the my-domain repository.

aws codeartifact delete-domain --domain my-domain --domain-owner 111122223333

JSON-formatted data appears in the output with details about the deleted domain.

{ "domain": {

"name": "my-domain", "owner": "111122223333",

"arn": "arn:aws:codeartifact:us-west-2:111122223333:domain/my-domain", "status": "Deleted",

"createdTime": "2020-10-07T15:36:35.194000-04:00",

"encryptionKey": "arn:aws:kms:us-west-2:111122223333:key/your-kms-key", "repositoryCount": 0,

"assetSizeBytes": 0 }

}

(21)

Create a repository

Working with repositories in CodeArtifact

These topics show you how to use the CodeArtifact CLI and API to create, list, update, and delete repositories.

Topics

• Create a repository (p. 14)

• Connect to a repository (p. 16)

• Delete a repository (p. 17)

• List repositories (p. 18)

• View or modify a repository conﬁguration (p. 20)

• Repository policies (p. 22)

• Add an external connection (p. 26)

• Tag a repository in CodeArtifact (p. 32)

Create a repository

You can create a repository using the CodeArtifact console or the AWS Command Line Interface (AWS CLI). When you create a repository, it does not contain any packages. Each repository is associated with the AWS account that you use when you create it. An AWS account can have up to 10,000 repositories.

For more information on CodeArtifact service limits, see Quotas in AWS CodeArtifact (p. 172). You can delete repositories to make room for more.

Repositories are polyglot—a single repository can contain packages of any supported type.

A repository can have one or more CodeArtifact repositories associated with it as upstream repositories.

This allows a package manager client to access the packages contained in more than one repository using a single URL endpoint. For more information, see Working with upstream repositories in CodeArtifact (p. 38).

Note

After you create a repository, you cannot change its name, associated AWS account, or domain.

Topics

• Create a repository (console) (p. 14)

• Create a repository (AWS CLI) (p. 15)

• Create a repository with an upstream repository (p. 16)

Create a repository (console)

1. Open the AWS CodeArtifact console at https://console.aws.amazon.com/codesuite/codeartifact/

home.

2. On the navigation pane, choose Repositories, and then choose Create repository.

3. For Repository name, enter a name for your repository.

4. (Optional) In Repository description, enter an optional description for your repository.

(22)

Create a repository (AWS CLI)

5. (Optional) In Publish upstream repositories, add intermediate repositories that connect your repositories to package authorities such as Maven Central or npmjs.com.

6. Choose Next.

7. In AWS account, choose This AWS account if you are signed in to the account that owns the domain.

Choose Diﬀerent AWS account if another AWS account owns the domain.

8. In Domain, choose the domain that the repository will be created in.

If there are no domains in the account, you must create one. Enter the name for the new domain in Domain name.

Expand Additional conﬁguration.

You must use an AWS KMS key (KMS key) to encrypt all assets in your domain. You can use an AWS managed key or a KMS key that you manage:

Important

CodeArtifact only supports symmetric KMS keys. You cannot use an asymmetric KMS key to encrypt your CodeArtifact domains. For help determining whether a KMS key is symmetric or asymmetric, see Identifying symmetric and asymmetric KMS keys.

• Choose AWS managed key if you want to use the default AWS managed key.

• Choose Customer managed key if you want to use a KMS key that you manage. To use a KMS key that you manage, in Customer managed key ARN, search for and choose the KMS key.

For more information, see AWS managed keys and customer managed key in the AWS Key Management Service Developer Guide.

9. Choose Next.

10. In Review and create, review what CodeArtifact is creating for you.

• Package ﬂow shows how your domain and repositories are connected.

• Step 1: Create repository shows details about the repository and optional upstream repositories that will be created.

• Step 2: Select domain shows details about my_domain.

When you're ready, choose Create repository.

Create a repository (AWS CLI)

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

aws codeartifact create-repository --domain my_domain --domain-owner 111122223333 -- repository my_repo --description "My new repository"

Example output:

{

"repository": { "name": "my_repo",

"administratorAccount": "123456789012", "domainName": "my_domain",

"domainOwner": "111122223333",

"arn": "arn:aws:codeartifact:region-id:111122223333:repository/my_domain/my_repo", "description": "My new repository",

"upstreams": "[]",

(23)

Create a repository with an upstream repository

"externalConnections"" "[]"

} }

A new repository doesn't contain any packages. Each repository is associated with the AWS account that you're authenticated to when the repository is created. An AWS account can have a maximum of 100 repositories. Repositories that have been deleted with the delete-repository command don't count towards this limit.

Create a repository with tags

To create a repository with tags, add the --tags parameter to your create-domain command.

aws codeartifact create-repository --domain my_domain --domain-owner 111122223333 -- repository my_repo --tags key=k1,value=v1 key=k2,value=v2

Create a repository with an upstream repository

You can specify one or more upstream repositories when you create a repository.

aws codeartifact create-repository --domain my_domain --domain-owner 111122223333 -- repository my_repo \

--upstreams repositoryName=my-upstream-repo --repository-description "My new repository"

Example output:

{

"domainOwner": "111122223333",

"upstreams": [ {

"repositoryName": "my-upstream-repo"

} ],

"externalConnections"" "[]"

} }

NoteTo create a repository with an upstream, you must have permission for the AssociateWithDownstreamRepository action on the upstream repository.

To add an upstream to a repository after it's been created, see Add, update, or remove upstream repositories (console) (p. 38) and Add, update, or remove upstream repositories (AWS CLI) (p. 39).

Connect to a repository

After you have conﬁgured your proﬁle and credentials to authenticate to your AWS account, decide which repository to use in CodeArtifact. You have the following options:

• Create a repository. For more information, see Creating a Repository (p. 14).

(24)

Use a package manager client

• Use a repository that already exists in your account. You can use the list-repositories command to ﬁnd the repositories created in your AWS account. For more information, see ??? (p. 18).

• Use a repository in a diﬀerent AWS account. For more information, see Repository policies (p. 22).

Use a package manager client

After you know which repository you want to use, see one of the following topics.

• Using CodeArtifact with Maven (p. 102)

• Using CodeArtifact with npm (p. 85)

• Using CodeArtifact with NuGet (p. 115)

• Using CodeArtifact with Python (p. 97)

Delete a repository

You can delete a repository using the CodeArtifact console or the AWS CLI. After a repository has been deleted, you can no longer push packages to it or pull packages from it. All packages in the repository become permanently unavailable and cannot be restored. You can create a repository with the same name, but its contents will be empty.

Topics

• Delete a repository (console) (p. 17)

• Delete a repository (AWS CLI) (p. 17)

Delete a repository (console)

home.

2. On the navigation pane, choose Repositories, then choose the repository that you want to delete.

3. Choose Delete and then follow the steps to delete the domain.

Delete a repository (AWS CLI)

Use the delete-repository command to delete a repository.

aws codeartifact delete-repository --domain my_domain --domain-owner 111122223333 -- repository my_repo

Example output:

{ "repository": { "name": "my_repo",

"administratorAccount": "123456789012", "domainName": "my_domain", "domainOwner": "123456789012",

"upstreams": [],

(25)

List repositories

} }

List repositories

Use the commands in this topic to list repositories in an AWS account or domain.

List repositories in an AWS account

Use this command to list all of the repositories in your AWS account.

aws codeartifact list-repositories

Sample output:

{ "repositories": [ {

"name": "repo1",

"domainOwner": "123456789012", "arn": "arn:aws:codeartifact:region- id:123456789012:repository/my_domain/repo1", "description": "Description of repo1"

}, {

"name": "repo2",

"domainOwner": "123456789012", "arn": "arn:aws:codeartifact:region- id:123456789012:repository/my_domain/repo2",

"description": "Description of repo2"

}, {

"name": "repo3",

"administratorAccount": "123456789012", "domainName": "my_domain2",

"domainOwner": "123456789012", "arn": "arn:aws:codeartifact:region- id:123456789012:repository/my_domain2/repo3", "description": "Description of repo3"

} ] }

You can paginate the response from list-repositories using the --max-results and --next- token parameters. For --max-results, specify an integer from 1 to 1000 to specify the number of results returned in a single page. Its default is 50. To return subsequent pages, run list-repositories again and pass the nextToken value received in the previous command output to --next-token.

When the --next-token option is not used, the ﬁrst page of results is always returned.

List repositories in the domain

Use list-repositories-in-domain to get a list of all the repositories in a domain.

(26)

List repositories in the domain

aws codeartifact list-repositories-in-domain --domain my_domain --domain-owner 123456789012 --max-results 3

The output shows that some of the repositories are administered by diﬀerent AWS accounts.

{

"repositories": [ {

"name": "repo1",

"domainOwner": "111122223333", "arn": "arn:aws:codeartifact:region- id:111122223333:repository/my_domain/repo1", "description": "Description of repo1"

}, {

"name": "repo2",

}, {

"name": "repo3",

} ] }

You can paginate the response from list-repositories-in-domain using the --max-results and --next-token parameters. For --max-results, specify an integer from 1 to 1000 to specify the number of results returned in a single page. Its default is 50. To return subsequent pages, run list- repositories-in-domain again and pass the nextToken value received in the previous command output to --next-token. When the --next-token option is not used, the ﬁrst page of results is always returned.

To output the repository names in a more compact list, try the following command.

aws codeartifact list-repositories-in-domain --domain my_domain --domain-owner 111122223333 \ --query 'repositories[*].[name]' --output text

Sample output:

repo1 repo2 repo3

The following example outputs the account ID in addition to the repository name.

aws codeartifact list-repositories-in-domain --domain my_domain --domain-owner 111122223333 \

(27)

View or modify a repository conﬁguration

--query 'repositories[*].[name,administratorAccount]' --output text

Sample output:

repo1 710221105108 repo2 710221105108 repo3 532996949307

For more information about the --query parameter, see ListRepositories in the CodeArtifact API Reference.

View or modify a repository conﬁguration

You can view and update details about your repository using the CodeArtifact console or the AWS Command Line Interface (AWS CLI).

NoteAfter you create a repository, you cannot change its name, associated AWS account, or domain.

Topics

• View or modify a repository conﬁguration (console) (p. 20)

• View or modify a repository conﬁguration (AWS CLI) (p. 21)

View or modify a repository conﬁguration (console)

You can view details about and update your repository using the CodeArtifact console.

home.

2. In the navigation pane, choose Repositories, and then choose the repository name that you want to view or modify.

3. Expand Details to see the following:

• The repository's domain. Choose the domain name to learn more about it.

• The repository's resource policy. Choose Apply a repository policy to add one.

• The repository's Amazon Resource Name (ARN).

• If your repository has an external connection, you can choose the connection to learn more about it. A repository can have only one external connection. For more information, see Add an external connection (p. 26).

• If your repository has upstream repositories, you can choose one to see its details. A repository can have up to 10 direct upstream repositories. For more information, see Working with upstream repositories in CodeArtifact (p. 38).

NoteA repository can have an external connection or upstream repositories, but not both.

4. In Packages, you can see any packages that are available to this repository. Choose a package to learn more about it.

5. Choose View connection instructions, and then choose a package manager to learn how to conﬁgure it with CodeArtifact.

6. Choose Apply repository policy to update or add a resource policy to your repository. For more information, see Repository policies (p. 22).

(28)

View or modify a repository conﬁguration (AWS CLI)

7. Choose Edit to add or update the following.

• The repository description.

• Tags associated with the repository.

• If your repository has an external connection, you can change which public repository it connects to. Otherwise, you can add one or more existing repositories as upstream repositories. Arrange them in the order you want them prioritized by CodeArtifact when a package is requested. For more information, see Upstream repository priority order (p. 42).

View or modify a repository conﬁguration (AWS CLI)

To view a repository's current conﬁguration in CodeArtifact, use the describe-repository command.

aws codeartifact describe-repository --domain my_domain --domain-owner 111122223333 -- repository my_repo

Example output:

"administratorAccount": "123456789012, "domainName": "my_domain",

"domainOwner": "111122223333",

"arn": "arn:aws:codeartifact:region-id:111122223333:repository/my_domain/my_repo"

"upstreams": [],

} }

Modify a repository upstream conﬁguration

An upstream repository allows a package manager client to access the packages contained in more than one repository using a single URL endpoint. To add or change a repository's upstream relationship, use the update-repository command.

aws codeartifact update-repository --domain my_domain --domain-owner 111122223333 -- repository my_repo \

--upstreams repositoryName=my-upstream-repo

Example output:

"domainOwner": "111122223333",

"upstreams": [ {

"repositoryName": "my-upstream-repo"

} ],

}

(29)

Repository policies

}

NoteTo add an upstream repository, you must have permission for the

AssociateWithDownstreamRepository action on the upstream repository.

To remove a repository's upstream relationship, use an empty list as the argument to the --upstreams option.

aws codeartifact update-repository --domain my_domain --domain-owner 111122223333 -- repository my_repo --upstreams []

Example output:

{

"domainOwner": "111122223333",

"upstreams": [],

} }

Repository policies

CodeArtifact uses resource-based permissions to control access. Resource-based permissions let you specify who has access to a repository and what actions they can perform on it. By default, only the repository owner has access to a repository. You can apply a policy document that allows other IAM principals to access your repository.

For more information, see Resource-Based Policies and Identity-Based Policies and Resource-Based Policies.

Create a resource policy to grant read access

A resource policy is a text file in JSON format. The file must specify a principal (actor), one or more actions, and an effect (Allow or Deny). For example, the following resource policy grants the account 123456789012 permission to download packages from the repository.

{

"Action": [

"codeartifact:ReadFromRepository"

],

"Effect": "Allow", "Principal": {

"AWS": "arn:aws:iam::123456789012:root"

},

"Resource": "*"

} ]

(30)

Set a policy

}

Because the policy is evaluated only for operations against the repository that it's attached to, you don't need to specify a resource. Because the resource is implied, you can set the Resource to *.

Note

The codeartifact:ReadFromRepository action can only be used on a repository resource. You cannot put a package's Amazon Resource Name (ARN) as a resource with codeartifact:ReadFromRepository as the action to allow read access to a subset of packages in a repository. A given principal can either read all the packages in a repository or none of them.

Because the only action speciﬁed in the repository is ReadFromRepository, users and roles from account 1234567890 can download packages from the repository. However, they can't perform other actions on them (for example, listing package names and versions). Typically, you grant permissions in the following policy in addition to ReadFromRepository because a user who downloads packages from a repository needs to interact with it in other ways too.

{

"Version": "2012-10-17", "Statement": [

{

"Action": [

"codeartifact:DescribePackageVersion", "codeartifact:DescribeRepository", "codeartifact:GetPackageVersionReadme", "codeartifact:GetRepositoryEndpoint", "codeartifact:ListPackages",

"codeartifact:ListPackageVersions", "codeartifact:ListPackageVersionAssets", "codeartifact:ListPackageVersionDependencies", "codeartifact:ReadFromRepository"

],

},

"Resource": "*"

} ] }

Set a policy

After you create a policy document, use the put-repository-permissions-policy command to attach it to a repository:

aws codeartifact put-repository-permissions-policy --domain my_domain --domainowner 111122223333 \

--repository my_repo --policy-document file:///PATH/TO/policy.json

When you call put-repository-permissions-policy, the resource policy on the repository is ignored when evaluating permissions. This ensures that the owner of a domain cannot lock themselves out of the repository, which would prevent them from being able to update the resource policy.

NoteYou cannot grant permissions to another AWS account to update the resource policy on a repository using a resource policy, since the resource policy is ignored when calling put- repository-permissions-policy.

(31)

Read a policy

Sample output:

{ "policy": {

"resourceArn": "arn:aws:codeartifact:region- id:111122223333:repository/my_domain/my_repo",

"document": "{ ...policy document content...}", "revision": "MQlyyTQRASRU3HB58gBtSDHXG7Q3hvxxxxxxx="

} }

The output of the command contains the Amazon Resource Name (ARN) of the repository resource, the full contents of the policy document, and a revision identiﬁer. You can pass the revision identiﬁer to put-repository-permissions-policy using the --policy-revision option. This ensures that a known revision of the document is being overwritten, and not a newer version set by another writer.

Read a policy

Use the get-repository-permissions-policy command to read an existing version of a policy document. To format the output for readability, use the --output and --query policy.document together with the Python json.tool module.

aws codeartifact get-repository-permissions-policy --domain my_domain --domainowner 111122223333 \

--repository my_repo --output text --query policy.document | python -m json.tool

Sample output:

{

},

"Action": [

"codeartifact:DescribePackageVersion", "codeartifact:DescribeRepository", "codeartifact:GetPackageVersionReadme", "codeartifact:GetRepositoryEndpoint", "codeartifact:ListPackages",

"codeartifact:ListPackageVersions", "codeartifact:ListPackageVersionAssets", "codeartifact:ListPackageVersionDependencies", "codeartifact:ReadFromRepository"

],

"Resource": "*"

} ] }

Delete a policy

Use the delete-repository-permissions-policy command to delete a policy from a repository.

aws codeartifact delete-repository-permissions-policy --domain my_domain --domainowner 111122223333 \

(32)

Grant read access to principals

--repository my_repo

The format of the output is the same as that of the get-repository-permissions-policy command.

Grant read access to principals

When you specify the root user of an account as the principal in a policy document, you grant access to all of the users and roles in that account. To limit access to selected users or roles, use their ARN in the Principal section of the policy. For example, use the following to grant read access to the IAM user bob in account 123456789012.

{

"Version": "2012-10-17", "Statement": [

{

"Action": [

"codeartifact:ReadFromRepository"

],

"AWS": "arn:aws:iam::123456789012:user/bob"

},

"Resource": "*"

} ] }

Grant write access to packages

The codeartifact:PublishPackageVersion action is used to control permission to publish new versions of a package. The resource used with this action must be a package. The format of CodeArtifact package ARNs is as follows.

arn:aws:codeartifact:region-id:111122223333:package/my_domain/my_repo/package- format/package-namespace/package-name

The following example shows the ARN for an npm package with scope @parity and name ui in the example-repo repository in domain my_domain.

arn:aws:codeartifact:region-id:111122223333:package/my_domain/example-repo/npm/parity/ui

The ARN for an npm package without a scope has the empty string for the namespace ﬁeld. For example, the following is the ARN for a package without a scope and with name react in the example-repo repository in domain my_domain.

arn:aws:codeartifact:region-id:111122223333:package/my_domain/example-repo/npm//react

The following policy grants account 123456789012 permission to publish versions of @parity/ui in the example-repo repository.

{

(33)

Grant write access to a repository

"Action": [

"codeartifact:PublishPackageVersion"

],

},

"Resource": "arn:aws:codeartifact:region-

id:111122223333:package/my_domain/example-repo/npm/parity/ui"

} ] }

Important

To grant permission to publish Maven and NuGet package versions, add the following permissions in addition to codeartifact:PublishPackageVersion.

1. NuGet: codeartifact:ReadFromRepository and specify the repository resource 2. Maven: codeartifact:PutPackageMetadata

Because this policy speciﬁes a domain and repository as part of the resource, it allows publishing only when attached to that repository.

Grant write access to a repository

You can use wildcards to grant write permission for all packages in a repository. For example, use the following policy to grant an account permission to write to all packages in the example-repo repository.

{

"Action": [

"codeartifact:PublishPackageVersion"

],

},

"Resource": "*"

} ] }

Add an external connection

You can add a connection between a CodeArtifact repository and an external, public repository such as https://npmjs.com or the Maven Central repository. 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.

Topics

• Add an external connection to a repository (p. 27)

• Supported external connection repositories (p. 27)

(34)

Add an external connection to a repository

• Remove an external connection (p. 28)

• Fetch npm packages from an external connection (p. 28)

• Fetch Maven packages from an external connection (p. 29)

• npm ingestion behavior (p. 31)

• Maven ingestion behavior (p. 31)

• CodeArtifact behavior when an external repository is not available (p. 32)

• Availability of new package versions (p. 32)

Add an external connection to a repository

To add an external connection to a CodeArtifact repository, use associate-external-connection.

aws codeartifact associate-external-connection --external-connection public:npmjs \ --domain my_domain --domain-owner 111122223333 --repository my_repo

Example output:

{

"repository": { "name": my_repo

"domainOwner": "111122223333",

"arn": "arn:aws:codeartifact:us-west-2:111122223333:repository/my_domain/my_repo", "description": "A description of my_repo",

"upstreams": [],

"externalConnectionName": "public:npmjs", "packageFormat": "npm",

"status": "AVAILABLE"

} ] } }

NoteA repository is limited to a single external connection only.

Supported external connection repositories

CodeArtifact supports an external connection to the following public repositories. To use the CodeArtifact CLI to specify an external connection, use the value in the Name column for the --

external-connection parameter when you run the associate-external-connection command.

Repository type Description Name

npm npm public registry public:npmjs

Python Python Package Index public:pypi

Maven Maven Central public:maven-central

Maven Google Android repository public:maven-

googleandroid

CodeArtifact User Guide CodeArtifact

CodeArtifact