debian-mirror-gitlab/doc/user/packages/yarn_repository/index.md

stage	group	info
Package	Package Registry	To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments

Publish packages with Yarn

Publish npm packages in your project's Package Registry using Yarn. Then install the packages whenever you need to use them as a dependency.

Learn how to build a yarn package.

You can get started with Yarn 2 by following the Yarn documentation.

Publish to GitLab Package Registry

Authentication to the Package Registry

You need a token to publish a package. Different tokens are available depending on what you're trying to achieve. For more information, review the guidance on tokens.

• If your organization uses two-factor authentication (2FA), you must use a personal access token with the scope set to api.
• If you publish a package via CI/CD pipelines, you must use a CI job token.

Create a token and save it to use later in the process.

Naming convention

Depending on how you install the package, you may need to adhere to the naming convention.

You can use one of two API endpoints to install packages:

• Instance-level: Use when you have many npm packages in different GitLab groups or in their own namespace.
• Project-level: Use when you have a few npm packages, and they are not in the same GitLab group.

If you plan to install a package through the project level, you do not have to adhere to the naming convention.

If you plan to install a package through the instance level, then you must name your package with a scope. Scoped packages begin with a @ and have the @owner/package-name format. You can set up the scope for your package in the .yarnrc.yml file and by using the publishConfig option in the package.json.

• The value used for the @scope is the root of the project that hosts the packages and not the root of the project with the package's source code. The scope should be lowercase.
• The package name can be anything you want

Project URL	Package Registry in	Scope	Full package name
https://gitlab.com/my-org/engineering-group/analytics	Analytics	@my-org	@my-org/package-name

Configuring .yarnrc.yml to publish from the project level

To publish with the project-level npm endpoint, set the following configuration in .yarnrc.yml:

npmScopes:
  foo:
    npmRegistryServer: 'https://<your_domain>/api/v4/projects/<your_project_id>/packages/npm/'
    npmPublishRegistry: 'https://<your_domain>/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>'

In this configuration:

• Replace <your_domain> with your domain name.
• Replace <your_project_id> with your project's ID, which you can find on the project's home page.
• Replace <your_token> with a deploy token, group access token, project access token, or personal access token.

Configuring .yarnrc.yml to publish from the instance level

For the instance-level npm endpoint, use this Yarn 2 configuration in .yarnrc.yml:

npmScopes:
  <scope>:
    npmRegistryServer: 'https://<your_domain>/api/v4/packages/npm/'

npmRegistries:
  //gitlab.example.com/api/v4/packages/npm/:
    npmAlwaysAuth: true
    npmAuthToken: '<your_token>'

In this configuration:

• Replace <your_domain> with your domain name.
• Your scope is <scope>, without @.
• Replace <your_token> with a deploy token, group access token, project access token, or personal access token.

Publishing a package via the command line

Publish a package:

npm publish

Your package should now publish to the Package Registry.

Publishing via a CI/CD pipeline

In the GitLab project that houses your yarnrc.yml, edit or create a .gitlab-ci.yml file. For example:

image: node:latest

stages:
  - deploy

deploy:
  stage: deploy
  script:
    - npm publish

Your package should now publish to the Package Registry when the pipeline runs.

Install a package

If multiple packages have the same name and version, the most recently-published package is retrieved when you install a package.

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 a few npm packages, and they are not in the same GitLab group.

Install from the instance level

WARNING: You must use packages published with the scoped naming convention when you install a package from the instance level.

1. Authenticate to the Package Registry

   If you install a package from a private project, you must authenticate to the Package Registry. Skip this step if the project is not private.

   npm config set -- //your_domain_name/api/v4/packages/npm/:_authToken=your_token
   

   • 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.

2. Set the registry

   npm config set @scope:registry https://your_domain_name.com/api/v4/packages/npm/
   

   • Replace @scope with the root level group 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.

3. Install the package

   yarn add @scope/my-package
   

Install from the project level

1. Authenticate to the Package Registry

   If you install a package from a private project, you must authenticate to the Package Registry. Skip this step if the project is not private.

   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.

2. Set the registry

   npm config set @scope:registry=https://your_domain_name/api/v4/projects/your_project_id/packages/npm/
   

   • Replace @scope with the root level group 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.

3. Install the package

   yarn add @scope/my-package
   

Helpful hints

For full helpful hints information, refer to the npm documentation.

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.

Troubleshooting

For full troubleshooting information, refer to the npm documentation.

Error running Yarn with the Package Registry for the 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.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):

//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:

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>"