diff options
Diffstat (limited to 'doc/user/packages/npm_registry/index.md')
| -rw-r--r-- | doc/user/packages/npm_registry/index.md | 142 |
1 files changed, 109 insertions, 33 deletions
diff --git a/doc/user/packages/npm_registry/index.md b/doc/user/packages/npm_registry/index.md index 11e3d0e5131..52fdda0d523 100644 --- a/doc/user/packages/npm_registry/index.md +++ b/doc/user/packages/npm_registry/index.md @@ -23,6 +23,8 @@ You need an token to publish a package. There are different tokens available dep Create a token and save it to use later in the process. +Do not use authentication methods other than the methods documented here. Undocumented authentication methods might be removed in the future. + ### Naming convention Depending on how the package is installed, you may need to adhere to the naming convention. @@ -122,21 +124,50 @@ You can install a package from a GitLab project or instance: - **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. -### Install from the instance level +### Authenticate to the Package Registry -WARNING: -To install a package from the instance level, the package must have been published following the scoped [naming convention](#naming-convention). +You must authenticate to the Package Registry to install a package from a private project. +No authentication is needed if the project is public. -1. Authenticate to the Package Registry +To authenticate with `npm`: - If you would like to install a package from a private project, you would have to authenticate to the Package Registry. Skip this step if the project is not private. +```shell +npm config set -- //your_domain_name/:_authToken=your_token +``` - ```shell - npm config set -- //your_domain_name/api/v4/packages/npm/:_authToken=your_token - ``` +With npm version 7 or earlier, use the full URL to the endpoint. - - 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. +If you're installing: + +- From the instance level: + + ```shell + npm config set -- //your_domain_name/api/v4/packages/npm/:_authToken=your_token + ``` + + From the project level: + + ```shell + npm config set -- //your_domain_name/api/v4/projects/your_project_id/packages/npm/:_authToken=your_token + ``` + +In these examples: + +- 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. + +NOTE: +Starting with npm version 8, you can [use a URI fragment instead of a full URL](https://docs.npmjs.com/cli/v8/configuring-npm/npmrc?v=true#auth-related-configuration) +in the `_authToken` parameter. However, [group-level endpoints](https://gitlab.com/gitlab-org/gitlab/-/issues/299834) +are not supported. + +### Install from the instance level + +WARNING: +To install a package from the instance level, the package must have been published following the scoped [naming convention](#naming-convention). + +1. [Authenticate to the Package Registry](#authenticate-to-the-package-registry). 1. Set the registry @@ -156,17 +187,7 @@ To install a package from the instance level, the package must have been publish ### Install from the project level -1. Authenticate to the Package Registry - - If you would like to install a package from a private project, you would have to authenticate to the Package Registry. Skip this step if the project is not private. - - ```shell - npm config set -- //your_domain_name/api/v4/projects/your_project_id/packages/npm/:_authToken=your_token - ``` - - - 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. +1. [Authenticate to the Package Registry](#authenticate-to-the-package-registry). 1. Set the registry @@ -184,6 +205,39 @@ To install a package from the instance level, the package must have been publish npm install @scope/my-package ``` +## Deprecate a package + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/396763) in GitLab 16.0. + +You can deprecate a package so that a deprecation warning displays when the package is fetched. + +Pre-requisites: + +- The same [permissions](../../permissions.md) as deleting a package. +- [Authenticated to the package registry](#authentication-to-the-package-registry). + +From the command line, run: + +```shell +npm deprecate @scope/package "Deprecation message" +``` + +The CLI also accepts version ranges for `@scope/package`. For example: + +```shell +npm deprecate @scope/package "All package versions are deprecated" +npm deprecate @scope/package@1.0.1 "Only version 1.0.1 is deprecated" +npm deprecate @scope/package@"< 1.0.5" "All package versions less than 1.0.5 are deprecated" +``` + +### Remove deprecation warning + +To remove a package's deprecation warning, specify `""` (an empty string) for the message. For example: + +```shell +npm deprecate @scope/package "" +``` + ## Helpful hints ### Package forwarding to npmjs.com @@ -244,8 +298,19 @@ 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 ``` -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. +#### From CI/CD + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258835) in GitLab 15.10. + +You can use a [`CI_JOB_TOKEN`](../../../ci/jobs/ci_job_token.md) or [deploy token](../../project/deploy_tokens/index.md) +to run `npm dist-tag` commands in a GitLab CI/CD job. For example: + +```yaml +npm-deploy-job: + script: + - echo "//${CI_SERVER_HOST}/api/v4/projects/${CI_PROJECT_ID}/packages/npm/:_authToken=${CI_JOB_TOKEN}">.npmrc + - npm dist-tag add @scope/package@version my-tag +``` Due to a bug in npm 6.9.0, deleting distribution tags fails. Make sure your npm version is 6.9.1 or later. @@ -261,24 +326,35 @@ The GitLab npm repository supports the following commands for the npm CLI (`npm` - `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. +- `npm pack`: Create a tarball from a package. +- `npm deprecate`: Deprecate a version of a package. ## Troubleshooting ### `404 Not Found` errors are happening on `npm install` or `yarn` -Using `CI_JOB_TOKEN` to install npm packages with dependencies in another project gives you 404 Not Found errors. A fix for this problem is proposed in [issue 352962](https://gitlab.com/gitlab-org/gitlab/-/issues/352962). +Using `CI_JOB_TOKEN` to install npm packages with dependencies in another project gives you 404 Not Found errors. You need to authenticate with a token that has access to the package and all its dependencies. -As a workaround, you can: +If the package and its dependencies are in separate projects but in the same group, you can use a +[group deploy token](../../project/deploy_tokens/index.md#create-a-deploy-token): -1. Create a [personal access token](../../profile/personal_access_tokens.md). -1. Authenticate at both the instance level and project level for each package: +```ini +//gitlab.example.com/api/v4/packages/npm/:_authToken=<group-token> +@group-scope:registry=https://gitlab.example.com/api/v4/packages/npm/ +``` - ```ini - @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_a>/packages/npm/:_authToken=${MY_TOKEN} - //gitlab.example.com/api/v4/projects/<your_project_id_b>/packages/npm/:_authToken=${MY_TOKEN} - ``` +If the package and its dependencies are spread across multiple groups, you can use a [personal access token](../../profile/personal_access_tokens.md) +from a user that has access to all the groups or individual projects: + +```ini +//gitlab.example.com/api/v4/packages/npm/:_authToken=<personal-access-token> +@group-1:registry=https://gitlab.example.com/api/v4/packages/npm/ +@group-2:registry=https://gitlab.example.com/api/v4/packages/npm/ +``` + +WARNING: +Personal access tokens must be treated carefully. Read our [token security considerations](../../../security/token_overview.md#security-considerations) +for guidance on managing personal access tokens (for example, setting a short expiry and using minimal scopes). ### `npm publish` targets default npm registry (`registry.npmjs.org`) |