GitLab NPM Registry (PREMIUM)

Introduced in GitLab Premium 11.7.

With the GitLab NPM Registry, every project can have its own space to store NPM packages.

NOTE: Note: Only scoped packages are supported.

Enabling the NPM Registry

NOTE: Note: This option is available only if your GitLab administrator has enabled support for the NPM registry.(PREMIUM ONLY)

After the NPM registry is enabled, it will be available for all new projects by default. To enable it for existing projects, or if you want to disable it:

Navigate to your project's Settings > General > Permissions.
Find the Packages feature and enable or disable it.
Click on Save changes for the changes to take effect.

You should then be able to see the Packages section on the left sidebar.

Before proceeding to authenticating with the GitLab NPM Registry, you should get familiar with the package naming convention.

Package naming convention

Packages must be scoped in the root namespace of the project. The package name may be anything but it is preferred that the project name be used unless it is not possible due to a naming collision. For example:

Project	Package	Supported
`foo/bar`	`@foo/bar`	Yes
`foo/bar/baz`	`@foo/baz`	Yes
`foo/bar/buz`	`@foo/anything`	Yes
`gitlab-org/gitlab-ce`	`@gitlab-org/gitlab-ce`	Yes
`gitlab-org/gitlab-ce`	`@foo/bar`	No

Now, you can configure your project to authenticate with the GitLab NPM Registry.

Authenticating to the GitLab NPM Registry

If a project is private or you want to upload an NPM package to GitLab, credentials will need to be provided for authentication. Support is available for OAuth tokens or personal access tokens.

CAUTION: 2FA is only supported with personal access tokens: If you have 2FA enabled, you need to use a personal access token with OAuth headers. Standard OAuth tokens won't be able to authenticate to the GitLab NPM Registry.

Authenticating with an OAuth token

To authenticate with an OAuth token or personal access token, add a corresponding section to your .npmrc file:

; Set URL for your scoped packages.
; For example package with name `@foo/bar` will use this URL for download
@foo:registry=https://gitlab.com/api/v4/packages/npm/

; Add the token for the scoped packages URL. This will allow you to download
; `@foo/` packages from private projects.
//gitlab.com/api/v4/packages/npm/:_authToken=<your_token>

; Add token for uploading to the registry. Replace <your_project_id>
; with the project you want your package to be uploaded to.
//gitlab.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken=<your_token>

Replace <your_project_id> with your project ID which can be found on the home page of your project and <your_token> with your OAuth or personal access token.

If you have a self-hosted GitLab installation, replace gitlab.com with your domain name.

You should now be able to download and upload NPM packages to your project.

NOTE: Note: If you encounter an error message with Yarn, see the troubleshooting section.

Uploading packages

Before you will be able to upload a package, you need to specify the registry for NPM. To do this, add the following section to the bottom of package.json:

  "publishConfig": {
    "@foo:registry":"https://gitlab.com/api/v4/projects/<your_project_id>/packages/npm/"
  }

Replace <your_project_id> with your project ID, which can be found on the home page of your project, and replace @foo with your own scope.

If you have a self-hosted GitLab installation, replace gitlab.com with your domain name.

Once you have enabled it and set up authentication, you can upload an NPM package to your project:

npm publish

You can then navigate to your project's Packages page and see the uploaded packages or even delete them.

If you attempt to publish a package with a name that already exists within a given scope, you will receive a 403 Forbidden! error.

Uploading a package with the same version twice

If you upload a package with a same name and version twice, GitLab will show both packages in the UI, but the GitLab NPM Registry will expose the most recent one as it supports only one package per version for npm install.

Troubleshooting

Error running yarn with NPM registry

If you are using yarn with the NPM registry, you may get an error message like:

yarn install v1.15.2
warning package.json: No license field
info No lockfile found.
warning XXX: No license field
[1/4] 🔍  Resolving packages...
[2/4] 🚚  Fetching packages...
error An unexpected error occurred: "https://gitlab.com/api/v4/projects/XXX/packages/npm/XXX/XXX/-/XXX/XXX-X.X.X.tgz: Request failed \"404 Not Found\"".
info If you think this is a bug, please open a bug report with the information provided in "/Users/XXX/gitlab-migration/module-util/yarn-error.log".
info Visit https://yarnpkg.com/en/docs/cli/install for documentation about this command

In this case, try adding this to your .npmrc file (and replace <your_oauth_token> with your with your OAuth or personal access token):

//gitlab.com/api/v4/projects/:_authToken=<your_oauth_token>