diff options
Diffstat (limited to 'doc/user/packages/npm_registry/index.md')
-rw-r--r-- | doc/user/packages/npm_registry/index.md | 39 |
1 files changed, 20 insertions, 19 deletions
diff --git a/doc/user/packages/npm_registry/index.md b/doc/user/packages/npm_registry/index.md index 390b2c28e10..5b90ec6f18c 100644 --- a/doc/user/packages/npm_registry/index.md +++ b/doc/user/packages/npm_registry/index.md @@ -4,9 +4,10 @@ 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 **(PREMIUM)** +# GitLab NPM Registry -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5934) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.7. +> - [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. @@ -20,9 +21,9 @@ Only [scoped](https://docs.npmjs.com/misc/scope) packages are supported. NOTE: **Note:** This option is available only if your GitLab administrator has -[enabled support for the NPM registry](../../../administration/packages/index.md).**(PREMIUM ONLY)** +[enabled support for the NPM registry](../../../administration/packages/index.md). -After the NPM registry is enabled, it will be available for all new projects +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**. @@ -36,7 +37,7 @@ get familiar with the package naming convention. ## Getting started -This section will cover installing NPM (or Yarn) and building a package for your +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). @@ -93,24 +94,24 @@ Or if you're using Yarn: yarn init ``` -This will take you through a series of questions to produce a `package.json` +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. Once you have completed the setup, you are now ready to upload your package to -the GitLab registry. To get started, you will need to set up authentication then +the GitLab registry. To get started, you need to set up authentication and then configure GitLab as a remote 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. [Personal access tokens](../../profile/personal_access_tokens.md) +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). 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 won't be able to authenticate to the GitLab NPM Registry. +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. ### Authenticating with a personal access token or deploy token @@ -168,7 +169,7 @@ Then, you could run `npm publish` either locally or via GitLab CI/CD: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9104) in GitLab Premium 12.5. 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 will inherit the permissions of the user that generates the pipeline. +The token inherits the permissions of the user that generates the pipeline. Add a corresponding section to your `.npmrc` file: @@ -180,7 +181,7 @@ Add a corresponding section to your `.npmrc` file: ## Uploading packages -Before you will be able to upload a package, you need to specify the registry +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`: ```json @@ -205,8 +206,8 @@ npm publish You can then navigate to your project's **Packages & Registries** 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. +Attempting to publish a package with a name that already exists within +a given scope causes a `403 Forbidden!` error. ## Uploading a package with the same version twice @@ -245,7 +246,7 @@ project path is `My-Group/project-foo`, your package must be named `@My-Group/an `@my-group/any-package-name` will not work. CAUTION: **When updating the path of a user/group or transferring a (sub)group/project:** -If you update the root namespace of a project with NPM packages, your changes will be rejected. To be allowed to do that, make sure to remove any NPM package first. Don't forget to update your `.npmrc` files to follow the above naming convention and run `npm publish` if necessary. +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. Now, you can configure your project to authenticate with the GitLab NPM Registry. @@ -253,16 +254,16 @@ Registry. ## Installing a package NPM packages are commonly installed using the `npm` or `yarn` commands -inside a JavaScript project. If you haven't already, you will need to set the +inside a JavaScript project. If you haven't already, set the URL for scoped packages. You can do this with the following command: ```shell npm config set @foo:registry https://gitlab.com/api/v4/packages/npm/ ``` -You will need to replace `@foo` with your scope. +Replace `@foo` with your scope. -Next, you will need to ensure [authentication](#authenticating-to-the-gitlab-npm-registry) +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: @@ -281,7 +282,7 @@ yarn add @my-project-scope/my-package > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/55344) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.9. -By default, when an NPM package is not found in the GitLab NPM Registry, the request will be forwarded to [npmjs.com](https://www.npmjs.com/). +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/). Administrators can disable this behavior in the [Continuous Integration settings](../../admin_area/settings/continuous_integration.md). @@ -367,7 +368,7 @@ And the `.npmrc` file should look like: ### `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'll 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 need to set a value prior to running `npm install` or set the value using [GitLab environment variables](./../../../ci/variables/README.md): ```shell NPM_TOKEN=<your_token> npm install |