diff options
Diffstat (limited to 'doc/user/packages/npm_registry/index.md')
| -rw-r--r-- | doc/user/packages/npm_registry/index.md | 503 |
1 files changed, 124 insertions, 379 deletions
diff --git a/doc/user/packages/npm_registry/index.md b/doc/user/packages/npm_registry/index.md index 5d2efc52ba9..c62999100c1 100644 --- a/doc/user/packages/npm_registry/index.md +++ b/doc/user/packages/npm_registry/index.md @@ -6,250 +6,97 @@ info: To determine the technical writer assigned to the Stage/Group associated w # npm packages in the Package Registry **(FREE)** -> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3. - -Publish npm packages in your project's Package Registry. Then install the -packages whenever you need to use them as a dependency. - -Only [scoped](https://docs.npmjs.com/misc/scope/) packages are supported. - -For documentation of the specific API endpoints that the npm package manager -client uses, see the [npm API documentation](../../../api/packages/npm.md). - -WARNING: -Never hardcode GitLab tokens (or any tokens) directly in `.npmrc` files or any other files that can -be committed to a repository. +For documentation of the specific API endpoints that the npm package manager client uses, see the [npm API documentation](../../../api/packages/npm.md). Learn how to build an [npm](../workflows/build_packages.md#npm) or [yarn](../workflows/build_packages.md#yarn) package. -## Use the GitLab endpoint for npm packages - -To use the GitLab endpoint for npm packages, choose an option: +Watch a [video demo](https://youtu.be/yvLxtkvsFDA) of how to publish npm packages to the GitLab Package Registry. -- **Project-level**: Use when you have few npm packages and they are not in - the same GitLab group. The [package naming convention](#package-naming-convention) is not enforced at this level. - Instead, you should use a [scope](https://docs.npmjs.com/cli/v6/using-npm/scope/) for your package. - When you use a scope, the registry URL is [updated](#authenticate-to-the-package-registry) only for that scope. -- **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). +## Publish to GitLab Package Registry -Some features such as [publishing](#publish-an-npm-package) a package is only available on the project-level endpoint. +### Authentication to the Package Registry -## Authenticate to the Package Registry +You need an token to publish a package. There are different tokens available depending on what you're trying to achieve. For more information, review the [guidance on tokens](../../../user/packages/package_registry/index.md#authenticate-with-the-registry). -You must authenticate with the Package Registry when the project -is private. Public projects do not require authentication. +- If your organization uses two factor authentication (2FA), you must use a personal access token with the scope set to `api`. +- If you are publishing a package via CI/CD pipelines, you must use a CI job token. -To authenticate, use one of the following: +Create a token and save it to use later in the process. -- 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). -- Your npm package name must be in the format of [`@scope/package-name`](#package-naming-convention). - It must match exactly, including the case. +### Naming convention -### Authenticate with a personal access token or deploy token +Depending on how the package will be installed, you may need to adhere to the naming convention. -To authenticate with the Package Registry, you need a [personal access token](../../profile/personal_access_tokens.md) or [deploy token](../../project/deploy_tokens/index.md). +You can use one of two API endpoints to install packages: -#### Project-level npm endpoint +- **Instance-level**: Use when you have many npm packages in different GitLab groups or in their own namespace. +- **Project-level**: Use when you have few npm packages and they are not in the same GitLab group. -To use the [project-level](#use-the-gitlab-endpoint-for-npm-packages) npm endpoint, set your npm configuration: +If you plan to install a package through the [project level](#install-from-the-project-level), then you do not have to adhere to the naming convention. -```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.example.com/api/v4/projects/<your_project_id>/packages/npm/ - -# 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>" -``` - -- `<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. +If you plan to install a package through the [instance level](#install-from-the-instance-level), then you must name your package with a [scope](https://docs.npmjs.com/misc/scope/). Scoped packages begin with a `@` have the format of `@owner/package-name`. You can set up the scope for your package in the `.npmrc` file and by using the `publishConfig` option in the `package.json`. -You should now be able to publish and install npm packages in your project. +- The value used for the `@scope` is the root of the project that will host the packages and not the root + of the project with the source code of the package itself. The scope should be lowercase. +- The package name can be anything you want -If you encounter an error with [Yarn](https://classic.yarnpkg.com/en/), view -[troubleshooting steps](#troubleshooting). +| Project URL | Package Registry in | Scope | Full package name | +| ------------------------------------------------------- | ------------------- | --------- | ---------------------- | +| `https://gitlab.com/my-org/engineering-group/analytics` | Analytics | `@my-org` | `@my-org/package-name` | -#### Instance-level npm endpoint - -NOTE: -Note: Using `CI_JOB_TOKEN` to install npm packages with dependencies in another project will give you 404 errors. You can use a [personal access token](../../profile/personal_access_tokens.md) as a workaround. [GitLab-#352962](https://gitlab.com/gitlab-org/gitlab/-/issues/352962) proposes a fix to this bug. - -To use the [instance-level](#use-the-gitlab-endpoint-for-npm-packages) npm endpoint, set your npm configuration: +Make sure that the name of your package in the `package.json` file matches this convention: ```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.example.com/api/v4/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.example.com/api/v4/packages/npm/:_authToken' "<your_token>" -``` - -- `<your_token>` is your personal access token or deploy token. -- Replace `gitlab.example.com` with your domain name. - -You should now be able to install npm packages in your project. - -If you encounter an error with [Yarn](https://classic.yarnpkg.com/en/), view -[troubleshooting steps](#troubleshooting). - -### Authenticate with a CI job token - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9104) in GitLab 12.5. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free 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. -The token inherits the permissions of the user that generates the pipeline. - -#### 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.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} +"name": "@my-org/package-name" ``` -#### Instance-level npm endpoint - -To use the [instance-level](#use-the-gitlab-endpoint-for-npm-packages) npm endpoint, add a corresponding section to your `.npmrc` file: - -```ini -@foo:registry=https://gitlab.example.com/api/v4/packages/npm/ -//gitlab.example.com/api/v4/packages/npm/:_authToken=${CI_JOB_TOKEN} -``` +## Publishing a package via the command line -#### Use variables to avoid hard-coding auth token values +### Authenticating via the `.npmrc` -To avoid hard-coding the `authToken` value, you may use a variable in its place: +Create or edit the `.npmrc` file in the same directory as your `package.json`. Include the following lines in the `.npmrc` file: ```shell -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}" +@scope:registry=https://your_domain_name/api/v4/projects/your_project_id/packages/npm/ +//your_domain_name/api/v4/projects/your_project_id/packages/npm/:_authToken="${NPM_TOKEN}" ``` -Then, you can run `npm publish` either locally or by using GitLab CI/CD. +- Replace `@scope` with the [root level group](#naming-convention) of the project you're publishing to the package to. +- Replace `your_domain_name` with your domain name, for example, `gitlab.com`. +- Replace `your_project_id` is your project ID, found on the project's home page. +- `"${NPM_TOKEN}"` will be associated with the token you created later in the process. -- **Locally:** Export `NPM_TOKEN` before publishing: - - ```shell - NPM_TOKEN=<your_token> npm publish - ``` - -- **GitLab CI/CD:** Set an `NPM_TOKEN` [CI/CD variable](../../../ci/variables/index.md) - under your project's **Settings > CI/CD > Variables**. +WARNING: +Never hardcode GitLab tokens (or any tokens) directly in `.npmrc` files or any other files that can +be committed to a repository. -## Working with private registries +### Publishing a package via the command line -When working with private repositories, you may want to configure additional settings to ensure a secure communication channel: +Associate your [token](#authentication-to-the-package-registry) with the `"${NPM_TOKEN}"` in the `.npmrc`. Replace `your_token` with a deploy token, group access token, project access token, or personal access token. ```shell -# Force npm to always require authentication when accessing the registry, even for GET requests. -npm config set always-auth true -``` - -## Package naming convention - -When you use the [instance-level endpoint](#use-the-gitlab-endpoint-for-npm-packages), only the packages with names in the format of `@scope/package-name` are available. - -- The `@scope` is the root namespace of the GitLab project. To follow npm's convention, it should be - lowercase. However, the GitLab package registry allows for uppercase. Before GitLab 13.10, the - `@scope` had to be a case-sensitive match of the GitLab project's root namespace. This was - problematic because the npm public registry does not allow uppercase letters. GitLab 13.10 relaxes - this requirement and translates uppercase in the GitLab `@scope` to lowercase for npm. For - example, a package `@MyScope/package-name` in GitLab becomes `@myscope/package-name` for npm. -- The `package-name` can be whatever you want. - -NOTE: -The value used for the `@scope` is the root of the project that will end up hosting the packages and not the root -of the project with the source code of the package itself. For example, assume your package source code is located -at `source-code-group/package-code` and deployed to a package registry inside `registries-group/registry-project`. -In this case, the `@scope` needs to be `@registries-group` and not `@source-code-group`. - -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 | -| ------------------- | -------------------- | --------- | -| `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/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 | - -In GitLab, this regex validates all package names from all package managers: - -```plaintext -/\A\@?(([\w\-\.\+]*)\/)*([\w\-\.]+)@?(([\w\-\.\+]*)\/)*([\w\-\.]*)\z/ +NPM_TOKEN=your_token npm publish ``` -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. +Your package should now publish to the Package Registry. -## Limitations +## Publishing a package via a CI/CD pipeline -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. +### Authenticating via the `.npmrc` -## Publish an npm package - -Prerequisites: - -- [Authenticate](#authenticate-to-the-package-registry) to the Package Registry. -- Set a [project-level npm endpoint](#use-the-gitlab-endpoint-for-npm-packages). - -To upload an npm package to your project, run this command: +Create or edit the `.npmrc` file in the same directory as your `package.json` in a GitLab project. Include the following lines in the `.npmrc` file: ```shell -npm publish +@scope:registry=https://your_domain_name/api/v4/projects/your_project_id/packages/npm/ +//your_domain_name/api/v4/projects/${CI_PROJECT_ID}/packages/npm/:_authToken=${CI_JOB_TOKEN} ``` -To view the package, go to your project's **Packages and registries**. +- Replace `@scope` with the [root level group](#naming-convention) of the project you're publishing to the package to. +- The `${CI_PROJECT_ID}` and `${CI_JOB_TOKEN}` are [predefined variables](../../../ci/variables/predefined_variables.md) that are available in the pipeline and do not need to be replaced. -You can also define `"publishConfig"` for your project in `package.json`. For example: +### Publishing a package via a CI/CD pipeline -```json -{ - "publishConfig": { - "@foo:registry": " https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/npm/" - } -} -``` - -This forces the package to publish only to the specified registry. - -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. - -## Publish an npm package by using CI/CD - -Prerequisites: - -- [Authenticate](#authenticate-to-the-package-registry) to the Package Registry. -- Set a [project-level npm endpoint](#use-the-gitlab-endpoint-for-npm-packages). -- Your npm package name must be in the format of [`@scope/package-name`](#package-naming-convention). - It must match exactly, including the case. This is different than the - npm naming convention, but it is required to work with the GitLab Package Registry. - -To work with npm commands within [GitLab CI/CD](../../../ci/index.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: +In the GitLab project that houses your `.npmrc` and `package.json`, edit or create a `.gitlab-ci.yml` file. For example: ```yaml image: node:latest @@ -262,143 +109,105 @@ deploy: script: - echo "//${CI_SERVER_HOST}/api/v4/projects/${CI_PROJECT_ID}/packages/npm/:_authToken=${CI_JOB_TOKEN}">.npmrc - npm publish - environment: production ``` -See the -[Publish npm packages to the GitLab Package Registry using semantic-release](../../../ci/examples/semantic-release.md) -step-by-step guide and demo project for a complete example. - -## Configure the GitLab npm registry with Yarn 2 - -You can get started with Yarn 2 by following the [Yarn documentation](https://yarnpkg.com/getting-started/install/). +Your package should now publish to the Package Registry when the pipeline runs. -To publish and install with the project-level npm endpoint, set the following configuration in -`.yarnrc.yml`: +## Install a package -```yaml -npmScopes: - foo: - npmRegistryServer: 'https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/npm/' - npmPublishRegistry: 'https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/npm/' - -npmRegistries: - //gitlab.example.com/api/v4/projects/<your_project_id>/packages/npm/: - npmAlwaysAuth: true - npmAuthToken: '<your_token>' -``` +If multiple packages have the same name and version, when you install a package, the most recently-published package is retrieved. -For the instance-level npm endpoint, use this Yarn 2 configuration in `.yarnrc.yml`: +You can install a package from a GitLab project or instance: -```yaml -npmScopes: - foo: - npmRegistryServer: 'https://gitlab.example.com/api/v4/packages/npm/' - -npmRegistries: - //gitlab.example.com/api/v4/packages/npm/: - npmAlwaysAuth: true - npmAuthToken: '<your_token>' -``` +- **Instance-level**: Use when you have many npm packages in different GitLab groups or in their own namespace. +- **Project-level**: Use when you have few npm packages and they are not in the same GitLab group. -In this configuration: +### Install from the instance level -- Replace `<your_token>` with your personal access token or deploy token. -- Replace `<your_project_id>` with your project's ID, which you can find on the project's home page. -- Replace `gitlab.example.com` with your domain name. -- Your scope is `foo`, without `@`. +WARNING: +In order to install a package from the instance level, the package must have been published following the scoped [naming convention](#naming-convention). -## Publishing packages with the same name or version +1. Authenticate to the Package Registry -You cannot publish a package if a package of the same name and version already exists. -You must delete the existing package first. + If you would like to install a package from a private project, you will need to authenticate to the Package Registry. Skip this step if the project is not private. -This rule has a different impact depending on the package name: + ```shell + npm config set -- //your_domain_name/api/v4/packages/npm/:_authToken=your_token + ``` -- For packages following the [naming convention](#package-naming-convention), you can't publish a - package with a duplicate name and version to the root namespace. -- For packages not following the [naming convention](#package-naming-convention), you can't publish - a package with a duplicate name and version to the project you target with the upload. + - Replace `your_domain_name` with your domain name, for example, `gitlab.com`. + - Replace `your_token` with a deploy token, group access token, project access token, or personal access token. -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. +1. Set the registry -## `package.json` limitations + ```shell + npm config set @scope:registry https://your_domain_name.com/api/v4/packages/npm/ + ``` -You can't publish a package if its `package.json` file exceeds 20,000 characters. + - Replace `@scope` with the [root level group](#naming-convention) of the project you're installing to the package from. + - Replace `your_domain_name` with your domain name, for example `gitlab.com`. + - Replace `your_token` with a deploy token, group access token, project access token, or personal access token. -## Install a package +1. Install the package -npm packages are commonly-installed by using the `npm` or `yarn` commands -in a JavaScript project. You can install a package from the scope of a project or instance. + ```shell + npm install @scope/my-package + ``` -If multiple packages have the same name and version, when you install a package, the most recently-published package is retrieved. +### Install from the project level -1. Set the URL for scoped packages. +1. Authenticate to the Package Registry - For [instance-level endpoints](#use-the-gitlab-endpoint-for-npm-packages) run: + If you would like to install a package from a private project, you will need to authenticate to the Package Registry. Skip this step if the project is not private. ```shell - npm config set @foo:registry https://gitlab.example.com/api/v4/packages/npm/ + npm config set -- //your_domain_name/api/v4/projects/your_project_id/packages/npm/:_authToken=your_token ``` - - Replace `@foo` with your scope. - - Replace `gitlab.example.com` with your domain name. + - Replace `your_domain_name` with your domain name, for example, `gitlab.com`. + - Replace `your_project_id` is your project ID, found on the project's home page. + - Replace `your_token` with a deploy token, group access token, project access token, or personal access token. - For [project-level endpoints](#use-the-gitlab-endpoint-for-npm-packages) run: +1. Set the registry ```shell - npm config set @foo:registry https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/npm/ + npm config set @scope:registry=https://your_domain_name/api/v4/projects/your_project_id/packages/npm/ ``` - - Replace `@foo` with your scope. - - Replace `gitlab.example.com` with your domain name. - - Replace `<your_project_id>` with your project ID, found on the project's home page. + - Replace `@scope` with the [root level group](#naming-convention) of the project you're installing to the package from. + - Replace `your_domain_name` with your domain name, for example, `gitlab.com`. + - Replace `your_project_id` is your project ID, found on the project's home page. -1. Ensure [authentication](#authenticate-to-the-package-registry) is configured. - -1. To install a package in your project, run: +1. Install the package ```shell - npm install @my-scope/my-package + npm install @scope/my-package ``` - Or if you're using Yarn: +## Helpful hints - ```shell - yarn add @my-scope/my-package - ``` +### Package forwarding to npmjs.com -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/). +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). +Group owners can disable this behavior in the group Packages and Registries settings. + ### 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. Replace `my-org` with the namespace or group that owns your project's repository, +To do this, add lines to your `.npmrc` file. Replace `@my-other-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. -Use environment variables to set up your tokens: `export MY_TOKEN="<your token>"`. - ```shell -@foo:registry=https://gitlab.example.com/api/v4/packages/npm/ -//gitlab.example.com/api/v4/packages/npm/:_authToken=${MY_TOKEN} -//gitlab.example.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken=${MY_TOKEN} - -@my-other-org:registry=https://gitlab.example.com/api/v4/packages/npm/ -//gitlab.example.com/api/v4/packages/npm/:_authToken=${MY_TOKEN} -//gitlab.example.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken=${MY_TOKEN} +@scope:registry=https://my_domain_name.com/api/v4/packages/npm/ +@my-other-org:registry=https://my_domain_name.example.com/api/v4/packages/npm/ ``` ### npm metadata -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11867) in GitLab 12.6. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3. -> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/330929) in GitLab 14.5. - The GitLab Package Registry exposes the following attributes to the npm client. These are similar to the [abbreviated metadata format](https://github.com/npm/registry/blob/9e368cf6aaca608da5b2c378c0d53f475298b916/docs/responses/package-metadata.md#abbreviated-metadata-format): @@ -417,10 +226,7 @@ These are similar to the [abbreviated metadata format](https://github.com/npm/re - `engines` - `_hasShrinkwrap` -## Add npm distribution tags - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9425) in GitLab 12.8. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3. +### Add npm distribution tags 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. @@ -443,87 +249,46 @@ View [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/258835) for deta 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 - -When troubleshooting npm issues, first run the same command with the `--verbose` flag to confirm -what registry you are hitting. - -To improve performance, npm caches files related to a package. Note that npm doesn't remove data by -itself. The cache grows as new packages are installed. If you encounter issues, clear the cache with -this command: - -```shell -npm cache clean --force -``` - -### Error running Yarn with the Package Registry for npm registry - -If you are using [Yarn](https://classic.yarnpkg.com/en/) with the npm registry, you may get -an error message like: - -```shell -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.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 -``` - -In this case, try adding this to your `.npmrc` file (and replace `<your_token>` -with your personal access token or deploy token): +### Supported CLI commands -```plaintext -//gitlab.example.com/api/v4/projects/:_authToken=<your_token> -``` +The GitLab npm repository supports the following commands for the npm CLI (`npm`) and yarn CLI +(`yarn`): -You can also use `yarn config` instead of `npm config` when setting your auth-token dynamically: +- `npm install`: Install npm packages. +- `npm publish`: Publish an npm package to the registry. +- `npm dist-tag add`: Add a dist-tag to an npm package. +- `npm dist-tag ls`: List dist-tags for a package. +- `npm dist-tag rm`: Delete a dist-tag. +- `npm ci`: Install npm packages directly from your `package-lock.json` file. +- `npm view`: Show package metadata. -```shell -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>" -``` +## Troubleshooting ### `npm publish` targets default npm registry (`registry.npmjs.org`) Ensure that your package scope is set consistently in your `package.json` and `.npmrc` files. -For example, if your project name in GitLab is `foo/my-package`, then your `package.json` file +For example, if your project name in GitLab is `@scope/my-package`, then your `package.json` file should look like: ```json { - "name": "@foo/my-package", - "version": "1.0.0", - "description": "Example package for GitLab npm registry" + "name": "@scope/my-package" } ``` And the `.npmrc` file should look like: -```ini -//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 must set a value prior to running `npm install` or set the value by using [GitLab CI/CD variables](../../../ci/variables/index.md): - ```shell -NPM_TOKEN=<your_token> npm install +@scope:registry=https://your_domain_name/api/v4/projects/your_project_id/packages/npm/ +//your_domain_name/api/v4/projects/your_project_id/packages/npm/:_authToken="${NPM_TOKEN}" ``` ### `npm install` returns `npm ERR! 403 Forbidden` If you get this error, ensure that: -- The Package Registry is enabled in your project settings. Although the Package Registry is enabled - by default, it's possible to [disable it](../package_registry/index.md#disable-the-package-registry). +- The Package Registry is enabled in your project settings. Although the Package Registry is enabled by default, it's possible to [disable it](../package_registry/index.md#disable-the-package-registry). - Your token is not expired and has appropriate permissions. - A package with the same name or version doesn't already exist within the given scope. - The scoped packages URL includes a trailing slash: @@ -534,30 +299,25 @@ If you get this error, ensure that: If you get this error, one of the following problems could be causing it. -#### Package name does not meet the naming convention +### Package name does not meet the naming convention -Your package name may not meet the -[`@scope/package-name` package naming convention](#package-naming-convention). +Your package name may not meet the [`@scope/package-name` package naming convention](#naming-convention). -Ensure the name meets the convention exactly, including the case. -Then try to publish again. +Ensure the name meets the convention exactly, including the case. Then try to publish again. -#### Package already exists +### Package already exists -Your package has already been published to another project in the same -root namespace and therefore cannot be published again using the same name. +Your package has already been published to another project in the same root namespace and therefore cannot be published again using the same name. -This is also true even if the prior published package shares the same name, -but not the version. +This is also true even if the prior published package shares the same name, but not the version. -#### Package JSON file is too large +### Package JSON file is too large -Make sure that your `package.json` file does not [exceed `20,000` characters](#packagejson-limitations). +Make sure that your `package.json` file does not exceed `20,000` characters. ### `npm publish` returns `npm ERR! 500 Internal Server Error - PUT` -This is a [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/238950) in GitLab -13.3.x and later. The error in the logs will appear as: +This is a [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/238950) in GitLab 13.3.x and later. The error in the logs will appear as: ```plaintext >NoMethodError - undefined method `preferred_language' for #<Rack::Response @@ -572,22 +332,7 @@ This might be accompanied by another error: This is usually a permissions issue with either: - `'packages_storage_path'` default `/var/opt/gitlab/gitlab-rails/shared/packages/`. -- The remote bucket if [object storage](../../../administration/packages/index.md#using-object-storage) +- The remote bucket if [object storage](../../../administration/packages/index.md#use-object-storage) is used. In the latter case, ensure the bucket exists and GitLab has write access to it. - -## Supported CLI commands - -The GitLab npm repository supports the following commands for the npm CLI (`npm`) and yarn CLI -(`yarn`): - -- `npm install`: Install npm packages. -- `npm publish`: Publish an npm package to the registry. -- `npm dist-tag add`: Add a dist-tag to an npm package. -- `npm dist-tag ls`: List dist-tags for a package. -- `npm dist-tag rm`: Delete a dist-tag. -- `npm ci`: Install npm packages directly from your `package-lock.json` file. -- `npm view`: Show package metadata. -- `yarn add`: Install an npm package. -- `yarn update`: Update your dependencies. |