From e6d9c1db69a0111e3976d6a0b2d755f0832b9bcb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cristian=20Pallar=C3=A9s?= Date: Tue, 20 May 2025 11:58:20 +0200 Subject: [PATCH 1/9] add codeartifact docs --- .vscode/settings.json | 1 + .../coverage/coverage_codeartifact/index.md | 14 + .../en/user-guide/aws/codeartifact/index.md | 246 ++++++++++++++++++ 3 files changed, 261 insertions(+) create mode 100644 content/en/references/coverage/coverage_codeartifact/index.md create mode 100644 content/en/user-guide/aws/codeartifact/index.md 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 new file mode 100644 index 0000000000..274b918e4a --- /dev/null +++ b/content/en/references/coverage/coverage_codeartifact/index.md @@ -0,0 +1,14 @@ +--- +title: "CodeArtifact" +linkTitle: "codeartifact" +description: > + Implementation details for API codeartifact +hide_readingtime: true +draft: true +--- + +## Coverage Overview +{{< localstack_coverage_table service="codeartifact" >}} + +## Testing Details +{{< localstack_coverage_details service="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..448bfbc2d9 --- /dev/null +++ b/content/en/user-guide/aws/codeartifact/index.md @@ -0,0 +1,246 @@ +--- +title: CodeArtifact +linkTitle: CodeArtifact +description: > + Get started with CodeArtifact on LocalStack +tags: ["Pro image"] +--- + +## 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), [ListDomains](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_ListDomains.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 + } +} +``` + +{{< 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" + } + ] +} +``` + +{{< command >}} +$ awslocal codeartifact delete-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": "Deleted", + "createdTime": "2025-05-20T11:30:52.073202+02:00", + "repositoryCount": 0, + "assetSizeBytes": 0 + } +} +``` + +### 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" + } +} +``` + +Use [DescribeRepository](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_DescribeRepository.html) to view a specific repository. + +{{< 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" + } + ] +} +``` + +Update a repository using [UpdateRepository](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_UpdateRepository.html): + +{{< command >}} +$ awslocal codeartifact update-repository --domain demo-domain --repository demo-repo --description "My demo repository" +{{< /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", + "description": "My demo repository", + "upstreams": [], + "externalConnections": [], + "createdTime": "2025-05-20T11:34:27.712367+02:00" + } +} +``` + +Delete a repository using [DeleteRepository](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_DeleteRepository.html): + +{{< command >}} +$ awslocal codeartifact delete-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" + } +} +``` From 9a9d46ccda0e4ec268ad01aa2a7dbf8480e606cb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cristian=20Pallar=C3=A9s?= Date: Tue, 20 May 2025 14:15:36 +0200 Subject: [PATCH 2/9] wip --- .../en/user-guide/aws/codeartifact/index.md | 74 +++++++++++-------- 1 file changed, 42 insertions(+), 32 deletions(-) diff --git a/content/en/user-guide/aws/codeartifact/index.md b/content/en/user-guide/aws/codeartifact/index.md index 448bfbc2d9..8b81047f1a 100644 --- a/content/en/user-guide/aws/codeartifact/index.md +++ b/content/en/user-guide/aws/codeartifact/index.md @@ -48,7 +48,7 @@ The following output is displayed: } ``` -You can use [DescribeDomain](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_DescribeDomain.html), [ListDomains](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_ListDomains.html), and [DeleteDomain](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_DeleteDomain.html) for domain management. +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 @@ -69,6 +69,8 @@ The following output is displayed: } ``` +You can list all domains using [ListDomains](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_ListDomains.html). + {{< command >}} $ awslocal codeartifact list-domains {{< /command >}} @@ -88,25 +90,6 @@ The following output is displayed: } ``` -{{< command >}} -$ awslocal codeartifact delete-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": "Deleted", - "createdTime": "2025-05-20T11:30:52.073202+02:00", - "repositoryCount": 0, - "assetSizeBytes": 0 - } -} -``` - ### Repositories Repositories store packages and are associated with a domain. @@ -134,7 +117,7 @@ The following output is displayed: } ``` -Use [DescribeRepository](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_DescribeRepository.html) to view a specific repository. +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 @@ -200,10 +183,16 @@ The following output is displayed: } ``` -Update a repository using [UpdateRepository](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_UpdateRepository.html): +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. + + +### 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 update-repository --domain demo-domain --repository demo-repo --description "My demo repository" +$ awslocal codeartifact associate-external-connection --domain demo-domain --repository demo-repo \ + --external-connection "public:npmjs" {{< /command >}} The following output is displayed: @@ -215,32 +204,53 @@ The following output is displayed: "domainName": "demo-domain", "domainOwner": "000000000000", "arn": "arn:aws:codeartifact:eu-central-1:000000000000:repository/demo-domain/demo-repo", - "description": "My demo repository", "upstreams": [], - "externalConnections": [], - "createdTime": "2025-05-20T11:34:27.712367+02:00" + "externalConnections": [ + { + "externalConnectionName": "public:npmjs", + "packageFormat": "npm", + "status": "AVAILABLE" + } + ], + "createdTime": "2025-05-20T14:03:27.539994+02:00" } } ``` -Delete a repository using [DeleteRepository](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_DeleteRepository.html): +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 delete-repository --domain demo-domain --repository demo-repo +$ awslocal codeartifact create-repository --domain demo-domain \ + --repository demo-repo2 \ + --upstreams repositoryName=demo-repo {{< /command >}} The following output is displayed: ```json { "repository": { - "name": "demo-repo", + "name": "demo-repo2", "administratorAccount": "000000000000", "domainName": "demo-domain", "domainOwner": "000000000000", - "arn": "arn:aws:codeartifact:eu-central-1:000000000000:repository/demo-domain/demo-repo", - "upstreams": [], + "arn": "arn:aws:codeartifact:eu-central-1:000000000000:repository/demo-domain/demo-repo2", + "upstreams": [ + { + "repositoryName": "demo-repo" + } + ], "externalConnections": [], - "createdTime": "2025-05-20T11:34:27.712367+02:00" + "createdTime": "2025-05-20T14:07:56.741333+02:00" } } ``` + +Please note, a repository can have one or more upstream repositories, or an external connection. + +## Limitations + +LocalStack doesn't support the following features yet: + +- Domain and repository permission policies +- Packages and package groups handlers +- Retrieving repository endpoints From 0f05682fe5a207232d059ed03c1a5bb1544c88e4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cristian=20Pallar=C3=A9s?= Date: Tue, 20 May 2025 14:21:43 +0200 Subject: [PATCH 3/9] remove duplicated paragraph --- content/en/user-guide/aws/codeartifact/index.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/content/en/user-guide/aws/codeartifact/index.md b/content/en/user-guide/aws/codeartifact/index.md index 8b81047f1a..228ea1dc28 100644 --- a/content/en/user-guide/aws/codeartifact/index.md +++ b/content/en/user-guide/aws/codeartifact/index.md @@ -183,9 +183,6 @@ The following output is displayed: } ``` -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. - - ### 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). From 1c3beea33018c49f378ad3687b5e82c1022fc215 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cristian=20Pallar=C3=A9s?= Date: Tue, 20 May 2025 14:23:24 +0200 Subject: [PATCH 4/9] style changes --- content/en/user-guide/aws/codeartifact/index.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/content/en/user-guide/aws/codeartifact/index.md b/content/en/user-guide/aws/codeartifact/index.md index 228ea1dc28..db7d8889e0 100644 --- a/content/en/user-guide/aws/codeartifact/index.md +++ b/content/en/user-guide/aws/codeartifact/index.md @@ -34,6 +34,7 @@ $ awslocal codeartifact create-domain --domain demo-domain {{< /command >}} The following output is displayed: + ```json { "domain": { @@ -55,6 +56,7 @@ $ awslocal codeartifact describe-domain --domain demo-domain {{< /command >}} The following output is displayed: + ```json { "domain": { @@ -76,6 +78,7 @@ $ awslocal codeartifact list-domains {{< /command >}} The following output is displayed: + ```json { "domains": [ @@ -102,6 +105,7 @@ $ awslocal codeartifact create-repository --domain demo-domain \ {{< /command >}} The following output is displayed: + ```json { "repository": { @@ -124,6 +128,7 @@ $ awslocal codeartifact describe-repository --domain demo-domain --repository de {{< /command >}} The following output is displayed: + ```json { "repository": { @@ -146,6 +151,7 @@ $ awslocal codeartifact list-repositories {{< /command >}} The following output is displayed: + ```json { "repositories": [ @@ -168,6 +174,7 @@ $ awslocal codeartifact list-repositories-in-domain --domain demo-domain {{< /command >}} The following output is displayed: + ```json { "repositories": [ @@ -193,6 +200,7 @@ $ awslocal codeartifact associate-external-connection --domain demo-domain --rep {{< /command >}} The following output is displayed: + ```json { "repository": { @@ -223,6 +231,7 @@ $ awslocal codeartifact create-repository --domain demo-domain \ {{< /command >}} The following output is displayed: + ```json { "repository": { From 6b7fa03381724e0b66dad7c62c2b5ba68ad0049b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cristian=20Pallar=C3=A9s?= Date: Tue, 20 May 2025 14:44:41 +0200 Subject: [PATCH 5/9] fix style --- content/en/user-guide/aws/codeartifact/index.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/content/en/user-guide/aws/codeartifact/index.md b/content/en/user-guide/aws/codeartifact/index.md index db7d8889e0..728a9fa70c 100644 --- a/content/en/user-guide/aws/codeartifact/index.md +++ b/content/en/user-guide/aws/codeartifact/index.md @@ -10,7 +10,8 @@ tags: ["Pro image"] 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. +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" >}}). From b28303146bb0422ddd928d11c91fac31ef583fd5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cristian=20Pallar=C3=A9s?= Date: Tue, 20 May 2025 15:00:55 +0200 Subject: [PATCH 6/9] style changes --- content/en/user-guide/aws/codeartifact/index.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/content/en/user-guide/aws/codeartifact/index.md b/content/en/user-guide/aws/codeartifact/index.md index 728a9fa70c..a5458317cb 100644 --- a/content/en/user-guide/aws/codeartifact/index.md +++ b/content/en/user-guide/aws/codeartifact/index.md @@ -191,7 +191,7 @@ The following output is displayed: } ``` -### External connections and upstream repositories +### 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). @@ -252,9 +252,11 @@ The following output is displayed: } ``` +{{< callout "note">}} Please note, a repository can have one or more upstream repositories, or an external connection. +{{< /callout >}} -## Limitations +## Current Limitations LocalStack doesn't support the following features yet: From 736fe939b4a711444919043824f9f01c65aafc82 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cristian=20Pallar=C3=A9s?= Date: Tue, 20 May 2025 15:38:21 +0200 Subject: [PATCH 7/9] break some command examples for clarity --- content/en/user-guide/aws/codeartifact/index.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/content/en/user-guide/aws/codeartifact/index.md b/content/en/user-guide/aws/codeartifact/index.md index a5458317cb..7d845fd162 100644 --- a/content/en/user-guide/aws/codeartifact/index.md +++ b/content/en/user-guide/aws/codeartifact/index.md @@ -125,7 +125,8 @@ The following output is displayed: 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 +$ awslocal codeartifact describe-repository --domain demo-domain \ + --repository demo-repo {{< /command >}} The following output is displayed: @@ -196,7 +197,8 @@ The following output is displayed: 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 \ +$ awslocal codeartifact associate-external-connection --domain demo-domain \ + --repository demo-repo \ --external-connection "public:npmjs" {{< /command >}} From 5a26c7c006c18e4d7abff8fd0c2bbbf4cf2c72a5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cristian=20Pallar=C3=A9s?= Date: Mon, 26 May 2025 15:23:54 +0200 Subject: [PATCH 8/9] Update content/en/user-guide/aws/codeartifact/index.md Co-authored-by: Viren Nadkarni --- content/en/user-guide/aws/codeartifact/index.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/content/en/user-guide/aws/codeartifact/index.md b/content/en/user-guide/aws/codeartifact/index.md index 7d845fd162..6ed821af51 100644 --- a/content/en/user-guide/aws/codeartifact/index.md +++ b/content/en/user-guide/aws/codeartifact/index.md @@ -5,7 +5,9 @@ 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. From 378a2eaee5076a23fefc76884674d02ae52f6f24 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cristian=20Pallar=C3=A9s?= Date: Fri, 13 Jun 2025 10:30:49 +0200 Subject: [PATCH 9/9] Add "Using CodeArtifact with npm" --- .../en/user-guide/aws/codeartifact/index.md | 82 ++++++++++++++++++- 1 file changed, 79 insertions(+), 3 deletions(-) diff --git a/content/en/user-guide/aws/codeartifact/index.md b/content/en/user-guide/aws/codeartifact/index.md index 6ed821af51..12aca7b45f 100644 --- a/content/en/user-guide/aws/codeartifact/index.md +++ b/content/en/user-guide/aws/codeartifact/index.md @@ -260,10 +260,86 @@ The following output is displayed: 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 and repository permission policies -- Packages and package groups handlers -- Retrieving repository endpoints +- 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