diff --git a/.vscode/settings.json b/.vscode/settings.json index 114284e3ac..5691b09b86 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -1,6 +1,7 @@ { "cSpell.words": [ "awslocal", + "codeartifact", "quickstart" ] } \ No newline at end of file diff --git a/content/en/references/coverage/coverage_codeartifact/index.md b/content/en/references/coverage/coverage_codeartifact/index.md index 827d551979..f7c5f88ce1 100644 --- a/content/en/references/coverage/coverage_codeartifact/index.md +++ b/content/en/references/coverage/coverage_codeartifact/index.md @@ -1,5 +1,5 @@ --- -title: "codeartifact" +title: "CodeArtifact" linkTitle: "codeartifact" description: > Implementation details for API codeartifact diff --git a/content/en/user-guide/aws/codeartifact/index.md b/content/en/user-guide/aws/codeartifact/index.md new file mode 100644 index 0000000000..12aca7b45f --- /dev/null +++ b/content/en/user-guide/aws/codeartifact/index.md @@ -0,0 +1,345 @@ +--- +title: CodeArtifact +linkTitle: CodeArtifact +description: > + Get started with CodeArtifact on LocalStack +tags: ["Pro image"] +--- +{{< callout >}} +CodeArtifact is under active development and available in LocalStack as a preview feature. +{{< /callout >}} +## 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 common package formats such as Maven, npm, Python (pip), and NuGet. +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]({{< ref "coverage_codeartifact" >}}). + +## 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`](https://github.com/localstack/awscli-local) wrapper is expected. + +Start LocalStack using your preferred method. + +### Domains + +Domains are the top-level containers for repositories in CodeArtifact. + +Create a domain with the [CreateDomain](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_CreateDomain.html) operation: + +{{< command >}} +$ awslocal codeartifact create-domain --domain demo-domain +{{< /command >}} + +The following output is displayed: + +```json +{ + "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 [DescribeDomain](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_DescribeDomain.html), [UpdateDomain](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_UpdateDomain.html), and [DeleteDomain](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_DeleteDomain.html) for domain management. + +{{< command >}} +$ awslocal codeartifact describe-domain --domain demo-domain +{{< /command >}} + +The following output is displayed: + +```json +{ + "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 [ListDomains](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_ListDomains.html). + +{{< command >}} +$ awslocal codeartifact list-domains +{{< /command >}} + +The following output is displayed: + +```json +{ + "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 + +Repositories store packages and are associated with a domain. + +Create a repository using [CreateRepository](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_CreateRepository.html): + +{{< command >}} +$ awslocal codeartifact create-repository --domain demo-domain \ + --repository demo-repo +{{< /command >}} + +The following output is displayed: + +```json +{ + "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 [DescribeRepository](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_DescribeRepository.html), [UpdateRepository](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_UpdateRepository.html), and [DeleteRepository](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_DeleteRepository.html) to manage repositories. + +{{< command >}} +$ awslocal codeartifact describe-repository --domain demo-domain \ + --repository demo-repo +{{< /command >}} + +The following output is displayed: + +```json +{ + "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 [ListRepositories](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_ListRepositories.html) to view all of the repositories. + +{{< command >}} +$ awslocal codeartifact list-repositories +{{< /command >}} + +The following output is displayed: + +```json +{ + "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 [ListRepositoriesInDomain](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_ListRepositoriesInDomain.html): + +{{< command >}} +$ awslocal codeartifact list-repositories-in-domain --domain demo-domain +{{< /command >}} + +The following output is displayed: + +```json +{ + "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" + } + ] +} +``` + +### External Connections and Upstream Repositories + +Repositories can be associated with external connections using [AssociateExternalConnection](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_AssociateExternalConnection.html) and [DisassociateExternalConnection](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_DisassociateExternalConnection.html). + +{{< command >}} +$ awslocal codeartifact associate-external-connection --domain demo-domain \ + --repository demo-repo \ + --external-connection "public:npmjs" +{{< /command >}} + +The following output is displayed: + +```json +{ + "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](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_CreateRepository.html) and [UpdateRepository](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_UpdateRepository.html). + +{{< command >}} +$ awslocal codeartifact create-repository --domain demo-domain \ + --repository demo-repo2 \ + --upstreams repositoryName=demo-repo +{{< /command >}} + +The following output is displayed: + +```json +{ + "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" + } +} +``` + +{{< callout "note">}} +Please note, a repository can have one or more upstream repositories, or an external connection. +{{< /callout >}} + +## Using CodeArtifact with npm + +### Configuring npm with the login command + +Use the `awslocal codeartifact login` command to fetch credentials for use with npm. + +{{< command >}} +$ awslocal codeartifact login --tool npm --domain demo-domain --repository demo-repo +{{< /command >}} + +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](https://docs.aws.amazon.com/codeartifact/latest/ug/tokens-authentication.html#auth-token-login). + +### 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 + +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. + +{{< command >}} +$ export CODEARTIFACT_AUTH_TOKEN=$(awslocal codeartifact get-authorization-token --domain demo-domain --query authorizationToken --output text) +{{< /command >}} + +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. + +{{< command >}} +$ awslocal codeartifact get-repository-endpoint --domain demo-domain --repository demo-repo --format npm +{{< /command >}} + +The following URL is an example repository endpoint. + +```text +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. + +{{< command >}} +$ npm config set registry http://demo-domain-000000000000.d.codeartifact.eu-central-1.localhost.localstack.cloud/npm/demo-repo/ +{{< /command >}} + +4. Use the `npm config set` command to add your authorization token to your npm configuration. + +{{< command >}} +$ npm config set //demo-domain-000000000000.d.codeartifact.eu-central-1.localhost.localstack.cloud/:_authToken=${CODEARTIFACT_AUTH_TOKEN} +{{< /command >}} + +**For npm 6 or lower:** To make npm always pass the auth token to CodeArtifact, even for GET requests, set the always-auth configuration variable with npm config set. + +{{< command >}} +$ npm config set //demo-domain-000000000000.d.codeartifact.eu-central-1.localhost.localstack.cloud/:always-auth=true +{{< /command >}} + +#### 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`. + +```text +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 + +LocalStack doesn't 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