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

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

249 lines
9.3 KiB
Markdown
Raw Normal View History

2023-03-04 22:38:38 +05:30
---
stage: Package
group: Package Registry
info: 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](../workflows/build_packages.md#yarn) package.
You can get started with Yarn 2 by following the [Yarn documentation](https://yarnpkg.com/getting-started/install/).
## 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](../../../user/packages/package_registry/index.md#authenticate-with-the-registry).
- 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](#install-from-the-project-level), you do not have to
adhere to the naming convention.
If you plan to install a package through the [instance level](#install-from-the-instance-level), then you must name
your package with a [scope](https://docs.npmjs.com/misc/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`:
```yaml
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`:
```yaml
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:
```shell
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:
```yaml
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](#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.
```shell
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.
1. Set the registry
```shell
npm config set @scope:registry https://your_domain_name.com/api/v4/packages/npm/
```
- Replace `@scope` with the [root level group](#naming-convention) 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.
1. Install the package
```shell
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.
```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. Set the registry
```shell
npm config set @scope:registry=https://your_domain_name/api/v4/projects/your_project_id/packages/npm/
```
- Replace `@scope` with the [root level group](#naming-convention) 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.
1. Install the package
```shell
yarn add @scope/my-package
```
## Helpful hints
For full helpful hints information, refer to the [npm documentation](../npm_registry/index.md#helpful-hints).
### 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](../npm_registry/index.md#troubleshooting).
### Error running Yarn with the Package Registry for the npm registry
If you are using [Yarn](https://classic.yarnpkg.com/en/) with the npm registry, you may get
an error message like:
```shell
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):
```plaintext
//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:
```shell
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>"
```