Publish packages with Yarn

You can publish packages with Yarn 1 (Classic) and Yarn 2+.

To find the Yarn version used in the deployment container, run yarn --version in the script block of the CI script job block that is responsible for calling yarn publish. The Yarn version is shown in the pipeline output.

Learn how to build a Yarn package.

You can use the Yarn documentation to get started with Yarn Classic and Yarn 2+.

Publish to GitLab package registry

You can use Yarn to publish to the 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 can use a CI job token in private runners or you can register a variable for instance runners.

Publish configuration

To publish, set the following configuration in .yarnrc.yml. This file should be located in the root directory of your package project source where package.json is found. 

npmScopes:
  <my-org>:
    npmPublishRegistry: 'https://<your_domain>/api/v4/projects/<your_project_id>/packages/npm/'
    npmAlwaysAuth: true
    npmAuthToken: '<your_token>'

In this configuration:

  • Replace <my-org> with your organization scope, excluding the @ symbol.
  • Replace <your_domain> with your domain name.
  • Replace <your_project_id> with your project’s ID, which you can find on the project overview page.
  • Replace <your_token> with a deployment token, group access token, project access token, or personal access token.

Scoped registry does not work in Yarn Classic in package.json file, based on this issue. Therefore, under publishConfig there should be registry and not @scope:registry for Yarn Classic. You can publish using your command line or a CI/CD pipeline to the GitLab package registry.

Publishing via the command line - Manual Publish 

# Yarn 1 (Classic)
yarn publish

# Yarn 2+
yarn npm publish

Your package should now publish to the package registry.

Publishing via a CI/CD pipeline - Automated Publish

You can use pipeline variables when you use this method.

You can use instance runners (Default) or Private Runners (Advanced).

Instance runners

To create an authentication token for your project or group:

  1. On the left sidebar, select Search or go to and find your project or group.
  2. On the left sidebar, select Settings > Repository > Deploy Tokens.
  3. Create a deployment token with read_package_registry and write_package_registry scopes and copy the generated token.
  4. On the left sidebar, select Settings > CI/CD > Variables.
  5. Select Add variable and use the following settings:
Field Value
key NPM_AUTH_TOKEN
value <DEPLOY-TOKEN-FROM-STEP-3>
type Variable
Protected variable CHECKED
Mask variable CHECKED
Expand variable CHECKED

To use any Protected variable:

  1. Go to the repository that contains the Yarn package source code.
  2. On the left sidebar, select Settings > Repository.
    • If you are building from branches with tags, select Protected Tags and add v* (wildcard) for semantic versioning.
    • If you are building from branches without tags, select Protected Branches.

Then add the NPM_AUTH_TOKEN created above, to the .yarnrc.yml configuration in your package project root directory where package.json is found: 

npmScopes:
  <my-org>:
    npmPublishRegistry: "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/npm/"
    npmAlwaysAuth: true
    npmAuthToken: "${NPM_AUTH_TOKEN}"

In this configuration, replace <my-org> with your organization scope, excluding the @ symbol.

Private runners

Add the CI_JOB_TOKEN to the .yarnrc.yml configuration in your package project root directory where package.json is found: 

npmScopes:
  <my-org>:
    npmPublishRegistry: "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/npm/"
    npmAlwaysAuth: true
    npmAuthToken: "${CI_JOB_TOKEN}"

In this configuration, replace <my-org> with your organization scope, excluding the @ symbol.

To publish the package using CI/CD pipeline, In the GitLab project that houses your .yarnrc.yml, edit or create a .gitlab-ci.yml file. For example to trigger only on any tag push: 

# Yarn 1
image: node:lts

stages:
  - deploy

rules:
- if: $CI_COMMIT_TAG

deploy:
  stage: deploy
  script:
    - yarn publish

# Yarn 2+
image: node:lts

stages:
  - deploy

rules:
  - if: $CI_COMMIT_TAG

deploy:
  stage: deploy
  before_script:
    - corepack enable
    - yarn set version stable
  script:
    - yarn npm publish

Your package should now publish to the package registry when the pipeline runs.

Install a package

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

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

  • Instance-level: Best used when working with many packages in an organization scope.

  • 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 organization root (top-level project) ...com/my-org (@my-org) that hosts the packages, not the root of the project with the package’s source code.
  • The scope is always lowercase.

  • The package name can be anything you want @my-org/any-name.

  • Project-level: For when you have a one-off package.

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

Project URL Package registry Organization Scope Full package name
https://gitlab.com/<my-org>/<group-name>/<package-name-example> Package Name Example @my-org @my-org/package-name
https://gitlab.com/<example-org>/<group-name>/<project-name> Project Name @example-org @example-org/project-name

You can install from the instance level or from the project level.

The configurations for .yarnrc.yml can be added per package consuming project root where package.json is located, or you can use a global configuration located in your system user home directory.

Install from the instance level

Use these steps for global configuration in the .yarnrc.yml file:

  1. Configure organization scope.
  2. Set the registry.

Configure organization scope 

npmScopes:
 <my-org>:
   npmRegistryServer: "https://<your_domain_name>/api/v4/packages/npm"
  • Replace <my-org> with the root level group of the project you’re installing to the package from excluding the @ symbol.
  • Replace <your_domain_name> with your domain name, for example, gitlab.com.

Set the registry

Skip this step if your package is public not private. 

  npmRegistries:
    //<your_domain_name>/api/v4/packages/npm:
      npmAlwaysAuth: true
      npmAuthToken: "<your_token>"
  • Replace <your_domain_name> with your domain name, for example, gitlab.com.
  • Replace <your_token> with a deployment token (recommended), group access token, project access token, or personal access token.

Install from the project level

Use these steps for each project in the .yarnrc.yml file:

  1. Configure project scope.
  2. Set the registry.

Configure project scope 

  npmScopes:
    <my-org>:
      npmRegistryServer: "https://<your_domain_name>/api/v4/projects/<your_project_id>/packages/npm"
  • Replace <my-org> with the root level group of the project you’re installing to the package from excluding the @ symbol.
  • Replace <your_domain_name> with your domain name, for example, gitlab.com.
  • Replace <your_project_id> with your project ID, found on the project overview page.

Set the registry (project level)

Skip this step if your package is public not private. 

npmRegistries:
  //<your_domain_name>/api/v4/projects/<your_project_id>/packages/npm:
    npmAlwaysAuth: true
    npmAuthToken: "<your_token>"
  • Replace <your_domain_name> with your domain name, for example, gitlab.com.
  • Replace <your_token> with a deployment token (recommended), group access token, project access token, or personal access token.
  • Replace <your_project_id> with your project ID, found on the project overview page.

Install the package

For Yarn 2+, use yarn add either in the command line or in the CI/CD pipelines to install your packages: 

yarn add @scope/my-package

For Yarn Classic

The Yarn Classic setup, requires both .npmrc and .yarnrc files as mentioned in issue:

  • Place credentials in the .npmrc file.
  • Place the scoped registry in the .yarnrc file. 
# .npmrc
//<your_domain_name>/api/v4/projects/<your_project_id>/packages/npm/:_authToken="<your_token>"

# .yarnrc
"@scope:registry" "https://<your_domain_name>/api/v4/projects/<your_project_id>/packages/npm/"

Then you can use yarn add to install your packages.

Troubleshooting

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, the following commands creates a file called .yarnrc in the current directory. Make sure to be in either your user home directory for global configuration or your project root for per-project configuration: 

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

yarn install fails to clone repository as a dependency

If you use yarn install from a Dockerfile, when you build the Dockerfile you might get an error like this: 

...
#6 8.621 fatal: unable to access 'https://gitlab.com/path/to/project/': Problem with the SSL CA cert (path? access rights?)
#6 8.621 info Visit https://yarnpkg.com/en/docs/cli/install for documentation about this command.
#6 ...

To resolve this issue, add an exclamation mark (!) to every Yarn-related path in your .dockerignore file. 

**

!./package.json
!./yarn.lock
...