npm packages in Artifact Registry
- Tier: Premium, Ultimate
- Offering: GitLab.com
- Status: Beta
An npm repository in Artifact Registry stores npm packages.
Supported clients
npmyarnpnpm
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:
glab auth statusIf the command does not report that you are logged in, authenticate with the GitLab CLI:
glab auth loginThe 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:
glab artifact-registry login --npm --registry <repository_url>This command writes an
_authTokenline in~/.npmrc. -
In
~/.npmrc, add a@scope:registry=line for a scoped package. Point it at the same URL:@<scope>:registry=<repository_url>Do not set a hosted repository as your default registry with
registry=. Installing a public package then fails with404 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:npmScopes: <scope>: npmRegistryServer: "<repository_url>" npmPublishRegistry: "<repository_url>" npmAuthToken: "${ARTIFACT_REGISTRY_TOKEN:-}"For
<scope>, enter the package scope without the@. -
Set the environment variable:
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:
glab artifact-registry login --npm --registry <repository_url> -
In
~/.npmrc, set the repository as your default registry: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 theARTIFACT_REGISTRY_TOKENenvironment variable:npmRegistryServer: "<repository_url>" npmRegistries: "<repository_url>": npmAlwaysAuth: true npmAuthToken: "${ARTIFACT_REGISTRY_TOKEN:-}"Keep
npmAuthTokenin thenpmRegistriesentry. Yarn ignores a top-levelnpmAuthTokenwhen the registry has its own entry. -
Set the environment variable:
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.
Version attribution
A version of a hosted repository records who published it and, when a CI/CD job published it, which job:
created_by: the GitLab user ID of the user who published the version.project_id,git_commit_sha,pipeline_id, andjob_id: the project, commit, pipeline, and job of the CI/CD job that published the version.
Attribution works as follows:
- Only a publish with a token that GitLab exchanged from a CI/CD ID token records the four build fields.
Other credentials, including
CI_JOB_TOKEN, leave them empty. - The four build fields are recorded together or not at all. A job that sends values the registry cannot store leaves all four empty, and the publish still succeeds.
- The first publish sets the values, and they are never changed. A republish of the version is rejected.
- A version created before the registry recorded attribution, and a version of a remote repository, has no attribution.
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 unpublishremoves a single version or a whole package.- Removing a version takes two requests.
The first request removes the version and its tarball.
The second request is cleanup, and it is refused with
409when the first request did not run for that version. - 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.
- A delete or an unpublish on a hosted repository is permanent and can’t be undone.
For specific steps, see Artifact Registry API.
Commands that do not work
npm searchreturns no results. The registry does not implement search.npm auditreturns no advisories. The registry does not implement the audit endpoints.- Both return a not-found response deliberately, so
npm installkeeps 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.