npm packages in Artifact Registry

Tier: Premium, Ultimate
Offering: GitLab.com
Status: Beta

An npm repository in Artifact Registry stores npm packages.

Supported clients

npm
yarn
pnpm

Authenticate

Authentication steps vary depending on the repository and client type.

Prerequisites:

The GitLab CLI, version 1.115.0 or later.
For Yarn clients, version 2.4 or later.

The GitLab CLI uses the GITLAB_TOKEN environment variable if it is set. Otherwise, it uses the credential that glab auth login stores. To check that the GitLab CLI can authenticate, run:

shell

glab auth status

If the command does not report that you are logged in, authenticate with the GitLab CLI:

shell

glab auth login

The glab commands in the following steps get a token that lasts 15 minutes by default, and up to 12 hours if you request a longer duration. To refresh the token, run the glab command for your client again before the token expires.

Choose a registry for your client

npm and pnpm look for packages in exactly one registry:

A registry= line sets your default registry. npm uses it for unscoped packages and publishes to it unless another setting overrides it.
A @scope:registry= line sends one scope, such as @my-org, to a different registry.

If the registry does not have the package, the install fails. npm does not try another registry.

To install your own packages and public packages from one registry, use a virtual repository as your default registry.

Point your client at the repository type that serves the packages you need. For more information, see repository types.

Authenticate to a hosted repository

A hosted repository serves only the packages published to it.

Run the following command:
shell
```
glab artifact-registry login --npm --registry <repository_url>
```
This command writes an _authToken line in ~/.npmrc.
In ~/.npmrc, add a @scope:registry= line for a scoped package. Point it at the same URL:
ini
```
@<scope>:registry=<repository_url>
```
Do not set a hosted repository as your default registry with registry=. Installing a public package then fails with 404 Not Found.

Yarn reads registry settings from .yarnrc.yml. The GitLab CLI cannot write this file, so .yarnrc.yml reads the token from the ARTIFACT_REGISTRY_TOKEN environment variable instead. Support for Yarn version 2.0 and later in the GitLab CLI is proposed in issue 8559.

In .yarnrc.yml, add an entry for your package scope:

yaml
npmScopes:
  <scope>:
    npmRegistryServer: "<repository_url>"
    npmPublishRegistry: "<repository_url>"
    npmAuthToken: "${ARTIFACT_REGISTRY_TOKEN:-}"

For <scope>, enter the package scope without the @.

Set the environment variable:
shell
```
export ARTIFACT_REGISTRY_TOKEN="$(glab artifact-registry get-token)"
```
The token stays out of .yarnrc.yml, which projects commit. While the variable is unset, other Yarn commands still run, and registry requests carry no credentials.

Authenticate to a remote or virtual repository

Authenticate to a remote or virtual repository and use it as your default registry. With this approach, clients resolve public packages through artifact registry instead of npmjs.com. Artifact registry caches each package it fetches and serves the cached copy to later requests.

A virtual repository also serves the packages in its hosted upstreams, so one default registry serves both your own packages and public packages.

If you use a virtual repository, list your hosted repositories before the remote repository that proxies npmjs.com. A virtual repository combines the versions and dist-tags of every upstream that has the package. When more than one upstream has the same version or dist-tag, the virtual repository uses the one from the upstream listed first. Your own versions and dist-tags take precedence over a package with the same name on npmjs.com.

You cannot publish to a remote or virtual repository. To publish, use a hosted repository.

Prerequisites:

One of the following:
- A remote npm repository that proxies npmjs.com.
- A virtual npm repository with a remote repository that proxies npmjs.com as one of its upstreams.

To use the repository as your default registry:

Authenticate with the repository:

shell

glab artifact-registry login --npm --registry <repository_url>

In ~/.npmrc, set the repository as your default registry:
ini
```
registry=<repository_url>
```

Packages that use the default registry now resolve through the repository. Scope-specific registry settings, such as @scope:registry= lines, still apply.

To use the repository as your default registry:

In .yarnrc.yml, set the repository as your default registry, and add an entry for it that reads the token from the ARTIFACT_REGISTRY_TOKEN environment variable:
yaml
```
npmRegistryServer: "<repository_url>"
npmRegistries:
  "<repository_url>":
    npmAlwaysAuth: true
    npmAuthToken: "${ARTIFACT_REGISTRY_TOKEN:-}"
```
Keep npmAuthToken in the npmRegistries entry. Yarn ignores a top-level npmAuthToken when the registry has its own entry.

Set the environment variable:

shell
export ARTIFACT_REGISTRY_TOKEN="$(glab artifact-registry get-token)"

Configure your client

An npm repository is available at:

https://<registry_host>/<registry_handle>/npm/<repository_name>/

This URL has the following placeholders:

<registry_host>: Enter the hostname from your repository’s setup instructions. To find it, go to your repository and select More actions > View setup instructions.
<registry_handle>: Enter your organization’s registry handle.
<repository_name>: Enter the name of your repository.

Do not delete the trailing slash at the end of the npm repository URL.

Republishing a version

npm rejects a version that already exists, with 409.
Unlike npmjs.com, a hosted repository applies no 24-hour window after publishing.
An unpublished version number can be used again.

Limits

Limit	Value
Tarball size	5 GB
`package.json` size	20 KB
Versions per package	25,000
Tags per version	1,000

For the full list of limits, see Artifact Registry limits.

Delete an npm package

npm unpublish removes a single version or a whole package.
The Management API also deletes packages, versions, files, and dist-tags.
Unpublishing marks a package for removal rather than removing it at once. A repository delete that requires an empty repository keeps failing until the removal finishes.

For specific steps, see Artifact Registry API.

Commands that do not work

npm search returns no results. The registry does not implement search.
npm audit returns no advisories. The registry does not implement the audit endpoints.
Both return a not-found response deliberately, so npm install keeps working.

The registry line and the authentication line in your configuration must carry the same URL, including the trailing slash. npm matches the authentication line by URL prefix, so a mismatch fails with 401 and does not say which URL was wrong.