Skip to content

Commit 5dcdcb7

Browse files
skyrpexviren-nadkarni
skyrpex
and
viren-nadkarni
authored
CodeArtifact: Add documentation (#1775)
Co-authored-by: Viren Nadkarni <[email protected]>
1 parent 11d7a7c commit 5dcdcb7

File tree

5 files changed

+356
-2
lines changed

5 files changed

+356
-2
lines changed

‎.vscode/settings.json

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
{
22
"cSpell.words": [
33
"awslocal",
4+
"codeartifact",
45
"quickstart"
56
]
67
}

‎content/en/references/coverage/coverage_codeartifact/index.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
title: "codeartifact"
2+
title: "CodeArtifact"
33
linkTitle: "codeartifact"
44
description: >
55
Implementation details for API codeartifact

‎content/en/references/licensing.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -109,6 +109,7 @@ To learn more about how a service behaves in LocalStack, refer to that individua
109109
| [](https://docs.localstack.cloud/user-guide/aws/qldb/)[Amazon Quantum Ledger Database (QLDB)](https://docs.localstack.cloud/user-guide/aws/qldb/) | ❌ | ❌ | ✅ |
110110
| Developer Tools | | | |
111111
| [](https://docs.localstack.cloud/references/coverage/coverage_codecommit/)[AWS CodeCommit](https://docs.localstack.cloud/references/coverage/coverage_codecommit/) | ❌ | ✅ | ✅ |
112+
| AWS CodeArtifact | ❌ | ✅ | ✅ |
112113
| AWS CodeBuild | ❌ | ✅ | ✅ |
113114
| AWS CodeConnections | ❌ | ✅ | ✅ |
114115
| [](https://docs.localstack.cloud/user-guide/aws/fis/)[AWS Fault Injection Service](https://docs.localstack.cloud/user-guide/aws/fis/) | ❌ | ❌ | ✅ |

‎content/en/user-guide/aws/codeartifact/index.md

Lines changed: 351 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,351 @@
1+
---
2+
title: CodeArtifact
3+
linkTitle: CodeArtifact
4+
description: >
5+
Get started with CodeArtifact on LocalStack
6+
tags: ["Pro image"]
7+
---
8+
9+
## Introduction
10+
11+
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.
12+
13+
On AWS, CodeArtifact supports popular package formats such as Maven, npm, Python (pip), NuGet, etc.
14+
You can configure it to work with public repositories or use it to store your private packages.
15+
16+
LocalStack provides mocking support for several CodeArtifact API operations.
17+
You can find supported operations on the [API coverage page]({{< ref "coverage_codeartifact" >}}).
18+
It also has full support to create and use NPM repositories.
19+
20+
## Getting Started
21+
22+
This guide will help you create a domain, repository, and manage package publishing workflows using the `awslocal` CLI.
23+
24+
Basic knowledge of the AWS CLI and the [`awslocal`](https://github.com/localstack/awscli-local) wrapper is expected.
25+
26+
Start LocalStack using your preferred method.
27+
28+
### Domains
29+
30+
Domains are the top-level containers for repositories in CodeArtifact.
31+
32+
Create a domain with the [CreateDomain](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_CreateDomain.html) operation:
33+
34+
{{< command >}}
35+
$ awslocal codeartifact create-domain --domain demo-domain
36+
{{< /command >}}
37+
38+
The following output is displayed:
39+
40+
```json
41+
{
42+
"domain": {
43+
"name": "demo-domain",
44+
"owner": "000000000000",
45+
"arn": "arn:aws:codeartifact:eu-central-1:000000000000:domain/demo-domain",
46+
"status": "Active",
47+
"createdTime": "2025-05-20T11:30:52.073202+02:00",
48+
"repositoryCount": 0,
49+
"assetSizeBytes": 0
50+
}
51+
}
52+
```
53+
54+
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.
55+
56+
{{< command >}}
57+
$ awslocal codeartifact describe-domain --domain demo-domain
58+
{{< /command >}}
59+
60+
The following output is displayed:
61+
62+
```json
63+
{
64+
"domain": {
65+
"name": "demo-domain",
66+
"owner": "000000000000",
67+
"arn": "arn:aws:codeartifact:eu-central-1:000000000000:domain/demo-domain",
68+
"status": "Active",
69+
"createdTime": "2025-05-20T11:30:52.073202+02:00",
70+
"repositoryCount": 0,
71+
"assetSizeBytes": 0
72+
}
73+
}
74+
```
75+
76+
You can list all domains using [ListDomains](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_ListDomains.html).
77+
78+
{{< command >}}
79+
$ awslocal codeartifact list-domains
80+
{{< /command >}}
81+
82+
The following output is displayed:
83+
84+
```json
85+
{
86+
"domains": [
87+
{
88+
"name": "demo-domain",
89+
"owner": "000000000000",
90+
"arn": "arn:aws:codeartifact:eu-central-1:000000000000:domain/demo-domain",
91+
"status": "Active",
92+
"createdTime": "2025-05-20T11:30:52.073202+02:00"
93+
}
94+
]
95+
}
96+
```
97+
98+
### Repositories
99+
100+
Repositories store packages and are associated with a domain.
101+
102+
Create a repository using [CreateRepository](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_CreateRepository.html):
103+
104+
{{< command >}}
105+
$ awslocal codeartifact create-repository --domain demo-domain \
106+
--repository demo-repo
107+
{{< /command >}}
108+
109+
The following output is displayed:
110+
111+
```json
112+
{
113+
"repository": {
114+
"name": "demo-repo",
115+
"administratorAccount": "000000000000",
116+
"domainName": "demo-domain",
117+
"domainOwner": "000000000000",
118+
"arn": "arn:aws:codeartifact:eu-central-1:000000000000:repository/demo-domain/demo-repo",
119+
"upstreams": [],
120+
"externalConnections": [],
121+
"createdTime": "2025-05-20T11:34:27.712367+02:00"
122+
}
123+
}
124+
```
125+
126+
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.
127+
128+
{{< command >}}
129+
$ awslocal codeartifact describe-repository --domain demo-domain \
130+
--repository demo-repo
131+
{{< /command >}}
132+
133+
The following output is displayed:
134+
135+
```json
136+
{
137+
"repository": {
138+
"name": "demo-repo",
139+
"administratorAccount": "000000000000",
140+
"domainName": "demo-domain",
141+
"domainOwner": "000000000000",
142+
"arn": "arn:aws:codeartifact:eu-central-1:000000000000:repository/demo-domain/demo-repo",
143+
"upstreams": [],
144+
"externalConnections": [],
145+
"createdTime": "2025-05-20T11:34:27.712367+02:00"
146+
}
147+
}
148+
```
149+
150+
Use [ListRepositories](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_ListRepositories.html) to view all of the repositories.
151+
152+
{{< command >}}
153+
$ awslocal codeartifact list-repositories
154+
{{< /command >}}
155+
156+
The following output is displayed:
157+
158+
```json
159+
{
160+
"repositories": [
161+
{
162+
"name": "demo-repo",
163+
"administratorAccount": "000000000000",
164+
"domainName": "demo-domain",
165+
"domainOwner": "000000000000",
166+
"arn": "arn:aws:codeartifact:eu-central-1:000000000000:repository/demo-domain/demo-repo",
167+
"createdTime": "2025-05-20T11:34:27.712367+02:00"
168+
}
169+
]
170+
}
171+
```
172+
173+
Otherwise, list repositories in a specific domain using [ListRepositoriesInDomain](https://docs.aws.amazon.com/codeartifact/latest/APIReference/API_ListRepositoriesInDomain.html):
174+
175+
{{< command >}}
176+
$ awslocal codeartifact list-repositories-in-domain --domain demo-domain
177+
{{< /command >}}
178+
179+
The following output is displayed:
180+
181+
```json
182+
{
183+
"repositories": [
184+
{
185+
"name": "demo-repo",
186+
"administratorAccount": "000000000000",
187+
"domainName": "demo-domain",
188+
"domainOwner": "000000000000",
189+
"arn": "arn:aws:codeartifact:eu-central-1:000000000000:repository/demo-domain/demo-repo",
190+
"createdTime": "2025-05-20T11:34:27.712367+02:00"
191+
}
192+
]
193+
}
194+
```
195+
196+
### Upstream Repositories and External Connections
197+
198+
A repository can have other CodeArtifact repositories as upstream repositories.
199+
This enables a package manager client to access the packages that are contained in more than one repository using a single repository endpoint.
200+
201+
Furthermore, you can add a external connection between a CodeArtifact repository and an external, public repository such as [https://npmjs.com](https://npmjs.com).
202+
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.
203+
This makes it possible to consume open-source dependencies used by your application.
204+
205+
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).
206+
207+
{{< command >}}
208+
$ awslocal codeartifact associate-external-connection --domain demo-domain \
209+
--repository demo-repo \
210+
--external-connection "public:npmjs"
211+
{{< /command >}}
212+
213+
The following output is displayed:
214+
215+
```json
216+
{
217+
"repository": {
218+
"name": "demo-repo",
219+
"administratorAccount": "000000000000",
220+
"domainName": "demo-domain",
221+
"domainOwner": "000000000000",
222+
"arn": "arn:aws:codeartifact:eu-central-1:000000000000:repository/demo-domain/demo-repo",
223+
"upstreams": [],
224+
"externalConnections": [
225+
{
226+
"externalConnectionName": "public:npmjs",
227+
"packageFormat": "npm",
228+
"status": "AVAILABLE"
229+
}
230+
],
231+
"createdTime": "2025-05-20T14:03:27.539994+02:00"
232+
}
233+
}
234+
```
235+
236+
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).
237+
238+
{{< command >}}
239+
$ awslocal codeartifact create-repository --domain demo-domain \
240+
--repository demo-repo2 \
241+
--upstreams repositoryName=demo-repo
242+
{{< /command >}}
243+
244+
The following output is displayed:
245+
246+
```json
247+
{
248+
"repository": {
249+
"name": "demo-repo2",
250+
"administratorAccount": "000000000000",
251+
"domainName": "demo-domain",
252+
"domainOwner": "000000000000",
253+
"arn": "arn:aws:codeartifact:eu-central-1:000000000000:repository/demo-domain/demo-repo2",
254+
"upstreams": [
255+
{
256+
"repositoryName": "demo-repo"
257+
}
258+
],
259+
"externalConnections": [],
260+
"createdTime": "2025-05-20T14:07:56.741333+02:00"
261+
}
262+
}
263+
```
264+
265+
{{< callout "note">}}
266+
Please note, a repository can have one or more upstream repositories, or an external connection.
267+
{{< /callout >}}
268+
269+
## Using CodeArtifact with npm
270+
271+
### Configuring npm with the login command
272+
273+
Use the `awslocal codeartifact login` command to fetch credentials for use with npm.
274+
275+
{{< command >}}
276+
$ awslocal codeartifact login --tool npm --domain demo-domain --repository demo-repo
277+
{{< /command >}}
278+
279+
This command makes the following changes to your `~/.npmrc` file:
280+
281+
- Adds an authorization token after fetching it from CodeArtifact using your AWS credentials.
282+
- Sets the npm registry to the repository specified by the `--repository` option.
283+
- **For npm 6 and lower:** Adds `"always-auth=true"` so the authorization token is sent for every npm command.
284+
285+
The default authorization period after calling login is 12 hours, and login must be called to periodically refresh the token.
286+
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).
287+
288+
### Configuring npm manually
289+
290+
You can configure npm with your CodeArtifact repository without the `awslocal codeartifact login` command by manually updating the npm configuration.
291+
292+
#### To configure npm without using the login command
293+
294+
1. In a command line, fetch a CodeArtifact authorization token and store it in an environment variable.
295+
npm will use this token to authenticate with your CodeArtifact repository.
296+
297+
{{< command >}}
298+
$ export CODEARTIFACT_AUTH_TOKEN=$(awslocal codeartifact get-authorization-token --domain demo-domain --query authorizationToken --output text)
299+
{{< /command >}}
300+
301+
2. Get your CodeArtifact repository's endpoint by running the following command.
302+
Your repository endpoint is used to point npm to your repository to install or publish packages.
303+
304+
{{< command >}}
305+
$ awslocal codeartifact get-repository-endpoint --domain demo-domain --repository demo-repo --format npm
306+
{{< /command >}}
307+
308+
The following URL is an example repository endpoint.
309+
310+
```text
311+
http://demo-domain-000000000000.d.codeartifact.eu-central-1.localhost.localstack.cloud/npm/demo-repo/
312+
```
313+
314+
3. Use the `npm config set` command to set the registry to your CodeArtifact repository.
315+
Replace the URL with the repository endpoint URL from the previous step.
316+
317+
{{< command >}}
318+
$ npm config set registry http://demo-domain-000000000000.d.codeartifact.eu-central-1.localhost.localstack.cloud/npm/demo-repo/
319+
{{< /command >}}
320+
321+
4. Use the `npm config set` command to add your authorization token to your npm configuration.
322+
323+
{{< command >}}
324+
$ npm config set //demo-domain-000000000000.d.codeartifact.eu-central-1.localhost.localstack.cloud/:_authToken=${CODEARTIFACT_AUTH_TOKEN}
325+
{{< /command >}}
326+
327+
**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.
328+
329+
{{< command >}}
330+
$ npm config set //demo-domain-000000000000.d.codeartifact.eu-central-1.localhost.localstack.cloud/:always-auth=true
331+
{{< /command >}}
332+
333+
#### Example npm configuration file (`.npmrc`)
334+
335+
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`.
336+
337+
```text
338+
registry=http://demo-domain-000000000000.d.codeartifact.eu-central-1.localhost.localstack.cloud/npm/demo-repo/
339+
//demo-domain-000000000000.d.codeartifact.eu-central-1.localhost.localstack.cloud/:_authToken=eyJ2ZX...
340+
//demo-domain-000000000000.d.codeartifact.eu-central-1.localhost.localstack.cloud/:always-auth=true
341+
```
342+
343+
## Current Limitations
344+
345+
LocalStack does not support the following features yet:
346+
347+
- Domain owners are ignored
348+
- Copying package versions is not supported yet
349+
- Domain and repository permission policies are not supported yet
350+
- Package groups are not supported yet
351+
- Only supports the `npm` format

‎content/en/user-guide/lambda-tools/hot-reloading/index.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,8 @@ If using Docker Desktop on macOS, you might need to allow [file sharing](https:/
4141
MacOS may prompt you to grant Docker access to your target folders.
4242

4343
**WSL2-compatible paths required with Rancher Desktop on Windows:**
44-
Make sure your Lambda handler paths are specified using WSL2-compatible paths. For example, instead of using a Windows-style path such as:
44+
Make sure your Lambda handler paths are specified using WSL2-compatible paths.
45+
For example, instead of using a Windows-style path such as:
4546

4647
```bash
4748
C:\Users\myuser\projects\lambda\handler.py

0 commit comments

Comments
 (0)