diff options
Diffstat (limited to 'doc/user/packages/npm_registry/index.md')
| -rw-r--r-- | doc/user/packages/npm_registry/index.md | 495 |
1 files changed, 250 insertions, 245 deletions
diff --git a/doc/user/packages/npm_registry/index.md b/doc/user/packages/npm_registry/index.md index f15b31d8b67..feb797240f4 100644 --- a/doc/user/packages/npm_registry/index.md +++ b/doc/user/packages/npm_registry/index.md @@ -4,331 +4,378 @@ group: Package info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- -# GitLab NPM Registry +# NPM packages in the Package Registry > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5934) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.7. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. -With the GitLab NPM Registry, every -project can have its own space to store NPM packages. +Publish NPM packages in your project's Package Registry. Then install the +packages whenever you need to use them as a dependency. - - -NOTE: **Note:** Only [scoped](https://docs.npmjs.com/misc/scope) 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](../../../administration/packages/index.md). - -Enabling the NPM registry makes it available for all new projects -by default. To enable it for existing projects, or if you want to disable it: - -1. Navigate to your project's **Settings > General > Visibility, project features, permissions**. -1. Find the Packages feature and enable or disable it. -1. Click on **Save changes** for the changes to take effect. - -You should then be able to see the **Packages & Registries** section on the left sidebar. +## Build an NPM package -Before proceeding to authenticating with the GitLab NPM Registry, you should -get familiar with the package naming convention. +This section covers how to install NPM or Yarn and build a package for your +JavaScript project. -## Getting started +If you already use NPM and know how to build your own packages, go to +the [next section](#authenticate-to-the-package-registry). -This section covers how to install NPM (or Yarn) and build a package for your -JavaScript project. This is a quickstart if you are new to NPM packages. If you -are already using NPM and understand how to build your own packages, move on to -the [next section](#authenticating-to-the-gitlab-npm-registry). +### Install NPM -### Installing NPM +Install Node.js and NPM in your local development environment by following +the instructions at [npmjs.com](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm). -Follow the instructions at [npmjs.com](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) to download and install Node.js and -NPM to your local development environment. - -Once installation is complete, verify you can use NPM in your terminal by +When installation is complete, verify you can use NPM in your terminal by running: ```shell npm --version ``` -You should see the NPM version printed in the output: +The NPM version is shown in the output: ```plaintext 6.10.3 ``` -### Installing Yarn +### Install Yarn -You may want to install and use Yarn as an alternative to NPM. Follow the -instructions at [yarnpkg.com](https://classic.yarnpkg.com/en/docs/install) to install on -your development environment. +As an alternative to NPM, you can install Yarn in your local environment by following the +instructions at [yarnpkg.com](https://classic.yarnpkg.com/en/docs/install). -Once installed, you can verify that Yarn is available with the following command: +When installation is complete, verify you can use Yarn in your terminal by +running: ```shell yarn --version ``` -You should see the version printed like so: +The Yarn version is shown in the output: ```plaintext 1.19.1 ``` -### Creating a project +### Create a project -Understanding how to create a full JavaScript project is outside the scope of -this guide but you can initialize a new empty package by creating and navigating -to an empty directory and using the following command: +To create a project: -```shell -npm init -``` +1. Create an empty directory. +1. Go to the directory and initialize an empty package by running: -Or if you're using Yarn: + ```shell + npm init + ``` -```shell -yarn init -``` + Or if you're using Yarn: + + ```shell + yarn init + ``` + +1. Enter responses to the questions. Ensure the **package name** follows + the [naming convention](#package-naming-convention) and is scoped to the + project or group where the registry exists. + +A `package.json` file is created. + +## Use the GitLab endpoint for NPM packages + +To use the GitLab endpoint for NPM packages, choose an option: + +- **Project-level**: Use when you have few NPM packages and they are not in + the same GitLab group. +- **Instance-level**: Use when you have many NPM packages in different + GitLab groups or in their own namespace. Be sure to comply with the [package naming convention](#package-naming-convention). -This takes you through a series of questions to produce a `package.json` -file, which is required for all NPM packages. The most important question is the -package name. NPM packages must [follow the naming convention](#package-naming-convention) -and be scoped to the project or group where the registry exists. +Some features such as [publishing](#publish-an-npm-package) a package is only available on the project-level endpoint. -Once you have completed the setup, you are now ready to upload your package to -the GitLab registry. To get started, you need to set up authentication and then -configure GitLab as a remote registry. +## Authenticate to the Package Registry -## Authenticating to the GitLab NPM Registry +To authenticate to the Package Registry, you must use one of the following: -If a project is private or you want to upload an NPM package to GitLab, -you need to provide credentials for authentication. [Personal access tokens](../../profile/personal_access_tokens.md) -and [deploy tokens](../../project/deploy_tokens/index.md) -are preferred, but support is available for [OAuth tokens](../../../api/oauth2.md#resource-owner-password-credentials-flow). +- A [personal access token](../../../user/profile/personal_access_tokens.md) + (required for two-factor authentication (2FA)), with the scope set to `api`. +- A [deploy token](../../project/deploy_tokens/index.md), with the scope set to `read_package_registry`, `write_package_registry`, or both. +- It's not recommended, but you can use [OAuth tokens](../../../api/oauth2.md#resource-owner-password-credentials-flow). + Standard OAuth tokens cannot authenticate to the GitLab NPM Registry. You must use a personal access token with OAuth headers. +- A [CI job token](#authenticate-with-a-ci-job-token). -CAUTION: **Two-factor authentication (2FA) is only supported with personal access tokens:** -If you have 2FA enabled, you need to use a [personal access token](../../profile/personal_access_tokens.md) with OAuth headers with the scope set to `api` or a [deploy token](../../project/deploy_tokens/index.md) with `read_package_registry` or `write_package_registry` scopes. Standard OAuth tokens cannot authenticate to the GitLab NPM Registry. +### Authenticate with a personal access token or deploy token -### Authenticating with a personal access token or deploy token +To authenticate with the Package Registry, you will need a [personal access token](../../profile/personal_access_tokens.md) or [deploy token](../../project/deploy_tokens/index.md). -To authenticate with a [personal access token](../../profile/personal_access_tokens.md) or [deploy token](../../project/deploy_tokens/index.md), -set your NPM configuration: +#### Project-level NPM endpoint + +To use the [project-level](#use-the-gitlab-endpoint-for-npm-packages) NPM endpoint, set your NPM configuration: ```shell # Set URL for your scoped packages. # For example package with name `@foo/bar` will use this URL for download -npm config set @foo:registry https://gitlab.com/api/v4/packages/npm/ +npm config set @foo:registry https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/npm/ -# Add the token for the scoped packages URL. This will allow you to download -# `@foo/` packages from private projects. -npm config set '//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. -npm config set '//gitlab.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken' "<your_token>" +# Add the token for the scoped packages URL. Replace <your_project_id> +# with the project where your package is located. +npm config set '//gitlab.example.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 personal access token or deploy token. - -If you have a self-managed GitLab installation, replace `gitlab.com` with your -domain name. +- `<your_project_id>` is your project ID, found on the project's home page. +- `<your_token>` is your personal access token or deploy token. +- Replace `gitlab.example.com` with your domain name. -You should now be able to download and upload NPM packages to your project. +You should now be able to publish and install NPM packages in your project. -NOTE: **Note:** -If you encounter an error message with [Yarn](https://classic.yarnpkg.com/en/), see the -[troubleshooting section](#troubleshooting). +If you encounter an error with [Yarn](https://classic.yarnpkg.com/en/), view +[troubleshooting steps](#troubleshooting). -### Using variables to avoid hard-coding auth token values +#### Instance-level NPM endpoint -To avoid hard-coding the `authToken` value, you may use a variables in its place: +To use the [instance-level](#use-the-gitlab-endpoint-for-npm-packages) NPM endpoint, set your NPM configuration: ```shell -npm config set '//gitlab.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken' "${NPM_TOKEN}" -npm config set '//gitlab.com/api/v4/packages/npm/:_authToken' "${NPM_TOKEN}" -``` +# Set URL for your scoped packages. +# For example package with name `@foo/bar` will use this URL for download +npm config set @foo:registry https://gitlab.example.com/api/v4/packages/npm/ -Then, you could run `npm publish` either locally or via GitLab CI/CD: +# Add the token for the scoped packages URL. This will allow you to download +# `@foo/` packages from private projects. +npm config set '//gitlab.example.com/api/v4/packages/npm/:_authToken' "<your_token>" +``` -- **Locally:** Export `NPM_TOKEN` before publishing: +- `<your_token>` is your personal access token or deploy token. +- Replace `gitlab.example.com` with your domain name. - ```shell - NPM_TOKEN=<your_token> npm publish - ``` +You should now be able to publish and install NPM packages in your project. -- **GitLab CI/CD:** Set an `NPM_TOKEN` [variable](../../../ci/variables/README.md) - under your project's **Settings > CI/CD > Variables**. +If you encounter an error with [Yarn](https://classic.yarnpkg.com/en/), view +[troubleshooting steps](#troubleshooting). -### Authenticating with a CI job token +### Authenticate with a CI job token -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9104) in GitLab Premium 12.5. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9104) in GitLab Premium 12.5. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. -If youโre using NPM with GitLab CI/CD, a CI job token can be used instead of a personal access token or deploy token. +If you're using NPM with GitLab CI/CD, a CI job token can be used instead of a personal access token or deploy token. The token inherits the permissions of the user that generates the pipeline. -Add a corresponding section to your `.npmrc` file: +#### Project-level NPM endpoint + +To use the [project-level](#use-the-gitlab-endpoint-for-npm-packages) NPM endpoint, add a corresponding section to your `.npmrc` file: ```ini -@foo:registry=https://gitlab.com/api/v4/packages/npm/ -//gitlab.com/api/v4/packages/npm/:_authToken=${CI_JOB_TOKEN} -//gitlab.com/api/v4/projects/${CI_PROJECT_ID}/packages/npm/:_authToken=${CI_JOB_TOKEN} +@foo:registry=https://gitlab.example.com/api/v4/projects/${CI_PROJECT_ID}/packages/npm/ +//gitlab.example.com/api/v4/projects/${CI_PROJECT_ID}/packages/npm/:_authToken=${CI_JOB_TOKEN} ``` -## Uploading packages +#### Instance-level NPM endpoint -Before you can upload a package, you need to specify the registry -for NPM. To do this, add the following section to the bottom of `package.json`: +To use the [instance-level](#use-the-gitlab-endpoint-for-npm-packages) NPM endpoint, add a corresponding section to your `.npmrc` file: -```json -"publishConfig": { - "@foo:registry":"https://gitlab.com/api/v4/projects/<your_project_id>/packages/npm/" -} +```ini +@foo:registry=https://gitlab.example.com/api/v4/packages/npm/ +//gitlab.example.com/api/v4/packages/npm/:_authToken=${CI_JOB_TOKEN} ``` -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-managed GitLab installation, replace `gitlab.com` with your -domain name. +#### Use variables to avoid hard-coding auth token values -Once you have enabled it and set up [authentication](#authenticating-to-the-gitlab-npm-registry), -you can upload an NPM package to your project: +To avoid hard-coding the `authToken` value, you may use a variable in its place: ```shell -npm publish +npm config set '//gitlab.example.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken' "${NPM_TOKEN}" +npm config set '//gitlab.example.com/api/v4/packages/npm/:_authToken' "${NPM_TOKEN}" ``` -You can then navigate to your project's **Packages & Registries** page and see the uploaded -packages or even delete them. +Then, you can run `npm publish` either locally or by using GitLab CI/CD. -Attempting to publish a package with a name that already exists within -a given scope causes a `403 Forbidden!` error. +- **Locally:** Export `NPM_TOKEN` before publishing: -## Uploading a package with the same version twice + ```shell + NPM_TOKEN=<your_token> npm publish + ``` -You cannot upload a package with the same name and version twice, unless you -delete the existing package first. This aligns with npmjs.org's behavior, with -the exception that npmjs.org does not allow users to ever publish the same version -more than once, even if it has been deleted. +- **GitLab CI/CD:** Set an `NPM_TOKEN` [variable](../../../ci/variables/README.md) + under your project's **Settings > CI/CD > Variables**. ## 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: +Your NPM package name must be in the format of `@scope:package-name`. + +- The `@scope` is the root namespace of the GitLab project. It must match exactly, including the case. +- The `package-name` can be whatever you want. + +For example, if your project is `https://gitlab.example.com/my-org/engineering-group/team-amazing/analytics`, +the root namespace is `my-org`. When you publish a package, it must have `my-org` as the scope. | Project | Package | Supported | | ---------------------- | ----------------------- | --------- | -| `foo/bar` | `@foo/bar` | Yes | -| `foo/bar/baz` | `@foo/baz` | Yes | -| `foo/bar/buz` | `@foo/anything` | Yes | +| `my-org/bar` | `@my-org/bar` | Yes | +| `my-org/bar/baz` | `@my-org/baz` | Yes | +| `My-org/Bar/baz` | `@My-org/Baz` | Yes | +| `my-org/bar/buz` | `@my-org/anything` | Yes | | `gitlab-org/gitlab` | `@gitlab-org/gitlab` | Yes | | `gitlab-org/gitlab` | `@foo/bar` | No | -The regex that is used for naming is validating all package names from all package managers: +In GitLab, this regex validates all package names from all package managers: ```plaintext /\A\@?(([\w\-\.\+]*)\/)*([\w\-\.]+)@?(([\w\-\.\+]*)\/)*([\w\-\.]*)\z/ ``` -It allows for capital letters, while NPM does not, and allows for almost all of the -characters NPM allows with a few exceptions (`~` is not allowed). +This regex allows almost all of the characters that NPM allows, with a few exceptions (for example, `~` is not allowed). + +The regex also allows for capital letters, while NPM does not. Capital letters are needed because the scope must be +identical to the root namespace of the project. -NOTE: **Note:** -Capital letters are needed because the scope is required to be -identical to the top level namespace of the project. So, for example, if your -project path is `My-Group/project-foo`, your package must be named `@My-Group/any-package-name`. -`@my-group/any-package-name` will not work. +CAUTION: **Caution:** +When you update the path of a user or group, or transfer a subgroup or project, +you must remove any NPM packages first. You cannot update the root namespace +of a project with NPM packages. Make sure you update your `.npmrc` files to follow +the naming convention and run `npm publish` if necessary. -CAUTION: **When updating the path of a user/group or transferring a (sub)group/project:** -Make sure to remove any NPM packages first. You cannot update the root namespace of a project with NPM packages. Don't forget to update your `.npmrc` files to follow the above naming convention and run `npm publish` if necessary. +## Publish an NPM package -Now, you can configure your project to authenticate with the GitLab NPM -Registry. +Prerequisites: -## Installing a package +- [Authenticate](#authenticate-to-the-package-registry) to the Package Registry. +- Set a [project-level NPM endpoint](#use-the-gitlab-endpoint-for-npm-packages). -NPM packages are commonly installed using the `npm` or `yarn` commands -inside a JavaScript project. If you haven't already, set the -URL for scoped packages. You can do this with the following command: +To upload an NPM package to your project, run this command: ```shell -npm config set @foo:registry https://gitlab.com/api/v4/packages/npm/ +npm publish ``` -Replace `@foo` with your scope. +To view the package, go to your project's **Packages & Registries**. -Next, you need to ensure [authentication](#authenticating-to-the-gitlab-npm-registry) -is setup so you can successfully install the package. Once this has been -completed, you can run the following command inside your project to install a -package: +If you try to publish a package [with a name that already exists](#publishing-packages-with-the-same-name-or-version) within +a given scope, you get a `403 Forbidden!` error. -```shell -npm install @my-project-scope/my-package -``` +## Publish an NPM package by using CI/CD -Or if you're using Yarn: +Prerequisites: -```shell -yarn add @my-project-scope/my-package +- [Authenticate](#authenticate-to-the-package-registry) to the Package Registry. +- Set a [project-level NPM endpoint](#use-the-gitlab-endpoint-for-npm-packages). + +To work with NPM commands within [GitLab CI/CD](../../../ci/README.md), you can use +`CI_JOB_TOKEN` in place of the personal access token or deploy token in your commands. + +An example `.gitlab-ci.yml` file for publishing NPM packages: + +```yaml +image: node:latest + +stages: + - deploy + +deploy: + stage: deploy + script: + - echo "//gitlab.example.com/api/v4/projects/${CI_PROJECT_ID}/packages/npm/:_authToken=${CI_JOB_TOKEN}">.npmrc + - npm publish ``` -### Forwarding requests to npmjs.org +## Publishing packages with the same name or version + +You cannot publish a package if a package of the same name and version already exists. +You must delete the existing package first. + +This aligns with npmjs.org's behavior. However, npmjs.org does not ever let you publish +the same version more than once, even if it has been deleted. + +## Install a package + +NPM packages are commonly-installed by using the `npm` or `yarn` commands +in a JavaScript project. + +1. Set the URL for scoped packages by running: + + ```shell + npm config set @foo:registry https://gitlab.example.com/api/v4/packages/npm/ + ``` + + Replace `@foo` with your scope. -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/55344) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.9. +1. Ensure [authentication](#authenticate-to-the-package-registry) is configured. -By default, when an NPM package is not found in the GitLab NPM Registry, the request is forwarded to [npmjs.com](https://www.npmjs.com/). +1. In your project, to install a package, run: + + ```shell + npm install @my-project-scope/my-package + ``` + + Or if you're using Yarn: + + ```shell + yarn add @my-project-scope/my-package + ``` + +In [GitLab 12.9 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/55344), +when an NPM package is not found in the Package Registry, the request is forwarded to [npmjs.com](https://www.npmjs.com/). Administrators can disable this behavior in the [Continuous Integration settings](../../admin_area/settings/continuous_integration.md). -### Installing packages from other organizations +### Install NPM packages from other organizations You can route package requests to organizations and users outside of GitLab. -To do this, add lines to your `.npmrc` file, replacing `my-org` with the namespace or group that owns your project's repository. The name is case-sensitive and must match the name of your group or namespace exactly. +To do this, add lines to your `.npmrc` file. Replace `my-org` with the namespace or group that owns your project's repository, +and use your organization's URL. The name is case-sensitive and must match the name of your group or namespace exactly. ```shell @foo:registry=https://gitlab.example.com/api/v4/packages/npm/ -//gitlab.com/api/v4/packages/npm/:_authToken= "<your_token>" -//gitlab.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken= "<your_token>" +//gitlab.example.com/api/v4/packages/npm/:_authToken= "<your_token>" +//gitlab.example.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken= "<your_token>" @my-other-org:registry=https://gitlab.example.com/api/v4/packages/npm/ -//gitlab.com/api/v4/packages/npm/:_authToken= "<your_token>" -//gitlab.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken= "<your_token>" +//gitlab.example.com/api/v4/packages/npm/:_authToken= "<your_token>" +//gitlab.example.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken= "<your_token>" ``` -## Removing a package +### NPM dependencies metadata -In the packages view of your project page, you can delete packages by clicking -the red trash icons or by clicking the **Delete** button on the package details -page. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11867) in GitLab Premium 12.6. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. -## Publishing a package with CI/CD +In GitLab 12.6 and later, packages published to the Package Registry expose the following attributes to the NPM client: -To work with NPM commands within [GitLab CI/CD](./../../../ci/README.md), you can use -`CI_JOB_TOKEN` in place of the personal access token or deploy token in your commands. +- name +- version +- dist-tags +- dependencies + - dependencies + - devDependencies + - bundleDependencies + - peerDependencies + - deprecated -A simple example `.gitlab-ci.yml` file for publishing NPM packages: +## Add NPM distribution tags -```yaml -image: node:latest +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9425) in GitLab Premium 12.8. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. -stages: - - deploy +You can add [distribution tags](https://docs.npmjs.com/cli/dist-tag) to newly-published packages. +Tags are optional and can be assigned to only one package at a time. -deploy: - stage: deploy - script: - - echo "//gitlab.com/api/v4/projects/${CI_PROJECT_ID}/packages/npm/:_authToken=${CI_JOB_TOKEN}">.npmrc - - npm publish +When you publish a package without a tag, the `latest` tag is added by default. +When you install a package without specifying the tag or version, the `latest` tag is used. + +Examples of the supported `dist-tag` commands: + +```shell +npm publish @scope/package --tag # Publish a package with new tag +npm dist-tag add @scope/package@version my-tag # Add a tag to an existing package +npm dist-tag ls @scope/package # List all tags under the package +npm dist-tag rm @scope/package@version my-tag # Delete a tag from the package +npm install @scope/package@my-tag # Install a specific tag ``` -Learn more about [using `CI_JOB_TOKEN` to authenticate to the GitLab NPM registry](#authenticating-with-a-ci-job-token). +You cannot use your `CI_JOB_TOKEN` or deploy token with the `npm dist-tag` commands. +View [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/258835) for details. + +Due to a bug in NPM 6.9.0, deleting distribution tags fails. Make sure your NPM version is 6.9.1 or later. ## Troubleshooting @@ -344,7 +391,7 @@ 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\"". +error An unexpected error occurred: "https://gitlab.example.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://classic.yarnpkg.com/en/docs/cli/install for documentation about this command ``` @@ -353,14 +400,14 @@ In this case, try adding this to your `.npmrc` file (and replace `<your_token>` with your personal access token or deploy token): ```plaintext -//gitlab.com/api/v4/projects/:_authToken=<your_token> +//gitlab.example.com/api/v4/projects/:_authToken=<your_token> ``` You can also use `yarn config` instead of `npm config` when setting your auth-token dynamically: ```shell -yarn config set '//gitlab.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken' "<your_token>" -yarn config set '//gitlab.com/api/v4/packages/npm/:_authToken' "<your_token>" +yarn config set '//gitlab.example.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken' "<your_token>" +yarn config set '//gitlab.example.com/api/v4/packages/npm/:_authToken' "<your_token>" ``` ### `npm publish` targets default NPM registry (`registry.npmjs.org`) @@ -375,23 +422,20 @@ should look like: "name": "@foo/my-package", "version": "1.0.0", "description": "Example package for GitLab NPM registry", - "publishConfig": { - "@foo:registry":"https://gitlab.com/api/v4/projects/<your_project_id>/packages/npm/" - } } ``` And the `.npmrc` file should look like: ```ini -//gitlab.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken=<your_token> -//gitlab.com/api/v4/packages/npm/:_authToken=<your_token> -@foo:registry=https://gitlab.com/api/v4/packages/npm/ +//gitlab.example.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken=<your_token> +//gitlab.example.com/api/v4/packages/npm/:_authToken=<your_token> +@foo:registry=https://gitlab.example.com/api/v4/packages/npm/ ``` ### `npm install` returns `Error: Failed to replace env in config: ${NPM_TOKEN}` -You do not need a token to run `npm install` unless your project is private (the token is only required to publish). If the `.npmrc` file was checked in with a reference to `$NPM_TOKEN`, you can remove it. If you prefer to leave the reference in, you need to set a value prior to running `npm install` or set the value using [GitLab environment variables](./../../../ci/variables/README.md): +You do not need a token to run `npm install` unless your project is private. The token is only required to publish. If the `.npmrc` file was checked in with a reference to `$NPM_TOKEN`, you can remove it. If you prefer to leave the reference in, you must set a value prior to running `npm install` or set the value by using [GitLab environment variables](../../../ci/variables/README.md): ```shell NPM_TOKEN=<your_token> npm install @@ -399,50 +443,11 @@ NPM_TOKEN=<your_token> npm install ### `npm install` returns `npm ERR! 403 Forbidden` -- Check that your token is not expired and has appropriate permissions. -- Check that [your token does not begin with `-`](https://gitlab.com/gitlab-org/gitlab/-/issues/235473). -- Check if you have attempted to publish a package with a name that already exists within a given scope. -- Ensure the scoped packages URL includes a trailing slash: - - Correct: `//gitlab.com/api/v4/packages/npm/` - - Incorrect: `//gitlab.com/api/v4/packages/npm` - -## NPM dependencies metadata - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11867) in GitLab Premium 12.6. - -Starting from GitLab 12.6, new packages published to the GitLab NPM Registry expose the following attributes to the NPM client: - -- name -- version -- dist-tags -- dependencies - - dependencies - - devDependencies - - bundleDependencies - - peerDependencies - - deprecated - -## NPM distribution tags - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9425) in GitLab Premium 12.8. - -You can add [distribution tags](https://docs.npmjs.com/cli/dist-tag) for newly published packages. -They follow NPM's convention where they are optional, and each tag can only be assigned to one -package at a time. The `latest` tag is added by default when a package is published without a tag. -The same applies to installing a package without specifying the tag or version. - -Examples of the supported `dist-tag` commands and using tags in general: - -```shell -npm publish @scope/package --tag # Publish new package with new tag -npm dist-tag add @scope/package@version my-tag # Add a tag to an existing package -npm dist-tag ls @scope/package # List all tags under the package -npm dist-tag rm @scope/package@version my-tag # Delete a tag from the package -npm install @scope/package@my-tag # Install a specific tag -``` - -NOTE: **Note:** -You cannot use your `CI_JOB_TOKEN` or deploy token with the `npm dist-tag` commands. View [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/258835) for details. +If you get this error, ensure that: -CAUTION: **Warning:** -Due to a bug in NPM 6.9.0, deleting dist tags fails. Make sure your NPM version is greater than 6.9.1. +- Your token is not expired and has appropriate permissions. +- [Your token does not begin with `-`](https://gitlab.com/gitlab-org/gitlab/-/issues/235473). +- A package with the same name doesn't already exist within the given scope. +- The scoped packages URL includes a trailing slash: + - Correct: `//gitlab.example.com/api/v4/packages/npm/` + - Incorrect: `//gitlab.example.com/api/v4/packages/npm` |