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 shared 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, exclude 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’s home 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 Shared Runners (Default) or Private Runners (Advanced).
Shared runners
To create an authentication token for your project or group:
- On the left sidebar, select Search or go to and find your project or group.
- On the left sidebar, select Settings > Repository > Deploy Tokens.
- Create a deployment token with
read_package_registry
andwrite_package_registry
scopes and copy the generated token. - On the left sidebar, select Settings > CI/CD > Variables.
- 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:
- Go to the repository that contains the Yarn package source code.
- 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.
- If you are building from branches with tags, select Protected Tags and add
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:
esp-code:
npmPublishRegistry: "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/npm/"
npmAlwaysAuth: true
npmAuthToken: "${NPM_AUTH_TOKEN}"
Private runners
Add the CI_JOB_TOKEN
to the .yarnrc.yml
configuration in your package project
root directory where package.json
is found:
npmScopes:
esp-code:
npmPublishRegistry: "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/npm/"
npmAlwaysAuth: true
npmAuthToken: "${CI_JOB_TOKEN}"
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
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 thepublishConfig
option in thepackage.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:
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:
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’s home 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’s home 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.
Related topics
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>"