Skip to content

CI npm guidance for JS libraries #4266

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
s-stumbo merged 3 commits into from
Oct 21, 2026
Merged

CI npm guidance for JS libraries #4266

Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
101ed1f
CI npm guidance for JS libraries
s-stumbo Oct 20, 2026
bbfed1f
CI npm guidance for JS libraries
s-stumbo Oct 20, 2026
81ff8b9
update
s-stumbo Oct 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 30 additions & 1 deletion content/chainguard/libraries/javascript/build-configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ linktitle: "Configure build tools"
description: "Configuring Chainguard Libraries for JavaScript on your workstation"
type: "article"
date: 2025-06-05T09:00:00+00:00
lastmod: 2026-10-07T14:49:03+00:00
lastmod: 2026-10-20T15:15:42+00:00
draft: false
tags: ["Chainguard Libraries", "JavaScript"]
menu:
Expand Down Expand Up @@ -413,6 +413,35 @@ chainctl auth configure-npm

[This command](/platform/chainctl/chainctl-docs/chainctl_auth_configure-npm/) writes a project-level `.npmrc` with the registry URL and base64-encoded credentials. It also prints the equivalent `npm config set` commands for use in CI or other environments where you need to configure `.npmrc` manually. If this command returns an error, ensure that you are using the [latest version of `chainctl`](/platform/chainctl-usage/how-to-install-chainctl/#updating-chainctl).

For CI/CD, prefer an assumable identity when using this command. Expand the following to learn more:

@matthewhelmke matthewhelmke Oct 20, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we want to say "use" instead of "prefer"? Here and in line 420.


{{< details "Configure npm in CI and headless environments" >}}

Do not use `--headless` as a CI option. It starts a device-code login and waits for someone to complete authentication in a browser. For CI/CD, prefer an assumable identity. Authenticate the workload first, then run a job similar to the following:

```yaml
permissions:
id-token: write

steps:
- uses: chainguard-dev/setup-chainctl@<pinned-version>
with:
identity: <identity-id>
- run: chainctl auth configure-npm
```

If the runner already has a valid session scoped to `libraries.cgr.dev`, run `chainctl auth configure-npm` without `--headless`; the command can reuse that session. A session scoped only to `console-api.enforce.dev` is not sufficient.

If the environment has neither an assumable identity nor a reusable libraries-scoped session, use a pull token:

```bash
chainctl auth configure-npm --pull-token
```

`--pull-token` produces credentials suitable for non-interactive CI, but token creation is not an unauthenticated CI bootstrap step. Pre-create the token and store its credentials securely.

{{< /details >}}

Alternatively, you can configure the `.npmrc` file manually:

{{< details "Configure .npmrc manually" >}}
Expand Down
Loading