Yarnでパッケージを公開する

Yarn 1 (Classic)とYarn 2+を使ってパッケージを公開およびインストールできます。

デプロイコンテナで使用されているYarnのバージョンを見つけるには、yarn publishを呼び出すCI/CDスクリプトのジョブブロックのscriptブロックでyarn --versionを実行します。Yarnのバージョンはパイプラインの出力に表示されます。

パッケージレジストリへの認証

パッケージレジストリとやり取りするにはトークンが必要です。達成しようとしていることに応じて、さまざまなトークンが利用可能です。詳細については、トークンに関するガイダンス参照してください。

組織が2要素認証 (2FA) を使用している場合は、スコープがapiに設定されたパーソナルアクセストークンを使用する必要があります。
パッケージをCI/CDパイプラインで公開する場合、プライベートRunnerでCI/CDジョブトークンを使用できます。インスタンスRunner向けに変数を登録することもできます。

Yarnの公開

パッケージレジストリに公開するようにYarnを設定するには、.yarnrc.ymlファイルを編集します。このファイルは、package.jsonファイルと同じ場所にあるプロジェクトのルートディレクトリにあります。

.yarnrc.ymlを編集し、次の設定を追加します:
```
npmScopes:
  <my-org>:
    npmPublishRegistry: 'https://<domain>/api/v4/projects/<project_id>/packages/npm/'
    npmAlwaysAuth: true
    npmAuthToken: '<token>'
```
この設定では、次のようになります。
- <my-org>を組織のスコープに置き換えます。@記号は含めないでください。
- <domain>をドメイン名に置き換えます。
- <project_id>をプロジェクトのIDに置き換えます。プロジェクト概要ページで見つけることができます。
- <token>をデプロイトークン、グループアクセストークン、プロジェクトアクセストークン、またはパーソナルアクセストークンに置き換えます。

Yarn Classicでは、publishConfig["@scope:registry"]を使用したスコープ付きレジストリはサポートされていません。詳細については、Yarnプルリクエスト7829を参照してください。代わりに、package.jsonファイルでpublishConfigをregistryに設定します。

パッケージを公開する

コマンドラインから、またはGitLab CI/CDでパッケージを公開できます。

コマンドラインを使用

パッケージを手動で公開するには:

次のコマンドを実行します:

# Yarn 1 (Classic)
yarn publish

# Yarn 2+
yarn npm publish

CI/CDを使用

パッケージは、インスタンスRunner (デフォルト) またはプライベートRunner (アドバンスト) を使用して自動的に公開できます。CI/CDで公開する場合、パイプライン変数を使用できます。

プロジェクトまたはグループの認証トークンを作成します:
1. 上部のバーで、検索または移動先を選択して、プロジェクトまたはグループを見つけます。
2. 左サイドバーで、設定 > リポジトリ > Deploy Tokensを選択します。
3. read_package_registryとwrite_package_registryのスコープを持つデプロイトークンを作成し、生成されたトークンをコピーします。
4. 左サイドバーで、設定 > CI/CD > 変数を選択します。
5. Add variableを選択し、次の設定を使用します:
フィールド値
キー NPM_AUTH_TOKEN
値 <DEPLOY-TOKEN>
タイプ変数
保護された変数 CHECKED
Mask variable CHECKED
Expand variable CHECKED
オプション。保護された変数を使用するには:
1. Yarnパッケージのソースコードが含まれるリポジトリに移動します。
2. 左サイドバーで、設定 > リポジトリを選択します。
  - タグ付きのブランチからビルドしている場合は、保護されたタグを選択し、セマンティックバージョニング用にv* (ワイルドカード) を追加します。
  - タグなしのブランチからビルドしている場合は、ブランチルールを選択します。
作成したNPM_AUTH_TOKENを、package.jsonが見つかるパッケージプロジェクトのルートディレクトリにある.yarnrc.yml設定に追加します:
```
npmScopes:
  <my-org>:
    npmPublishRegistry: '${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/npm/'
    npmAlwaysAuth: true
    npmAuthToken: '${NPM_AUTH_TOKEN}'
```
この設定では、<my-org>を組織のスコープに置き換え、@記号は除外します。

フィールド	値
キー	`NPM_AUTH_TOKEN`
値	`<DEPLOY-TOKEN>`
タイプ	変数
保護された変数	`CHECKED`
Mask variable	`CHECKED`
Expand variable	`CHECKED`

package.jsonが存在するパッケージプロジェクトのルートディレクトリにある.yarnrc.yml設定にCI_JOB_TOKENを追加します:
```
npmScopes:
  <my-org>:
    npmPublishRegistry: '${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/npm/'
    npmAlwaysAuth: true
    npmAuthToken: '${CI_JOB_TOKEN}'
```
この設定では、<my-org>を組織のスコープに置き換え、@記号は除外します。

.yarnrc.ymlがあるGitLabプロジェクトで、.gitlab-ci.ymlファイルを編集または作成します。例えば、任意のタグプッシュのみをトリガーするには:

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

パイプラインが実行されると、パッケージがパッケージレジストリに追加されます。

パッケージをインストールする

インスタンスまたはプロジェクトからインストールできます。複数のパッケージが同じ名前とバージョンを持つ場合、パッケージをインストールする際には、最新で公開されたパッケージのみが取得されます。

スコープ付きのパッケージ名

インスタンスからインストールするには、パッケージにスコープを付けて命名する必要があります。パッケージのスコープは.yarnrc.ymlファイルとpackage.jsonのpublishConfigオプションで設定できます。プロジェクトまたはグループからインストールする場合、パッケージの命名規則に従う必要はありません。

パッケージスコープは@で始まり、@owner/package-nameの形式に従います:

@ownerは、パッケージをホストするトップレベルプロジェクトであり、パッケージのソースコードを持つプロジェクトのルートではありません。
パッケージ名は任意です。

例:

プロジェクトURL	パッケージレジストリ	組織スコープ	パッケージのフルネーム
`https://gitlab.com/<my-org>/<group-name>/<package-name-example>`	パッケージ名例	`@my-org`	`@my-org/package-name`
`https://gitlab.com/<example-org>/<group-name>/<project-name>`	プロジェクト名	`@example-org`	`@example-org/project-name`

インスタンスからのインストール

同じ組織スコープ内の多数のパッケージを扱っている場合は、インスタンスからインストールすることを検討してください。

組織のスコープを設定します。あなたの.yarnrc.ymlファイルに以下を追加します:
```
npmScopes:
 <my-org>:
   npmRegistryServer: 'https://<domain_name>/api/v4/packages/npm'
```
- <my-org>を、@記号を除外した、パッケージのインストール元となるプロジェクトのルートレベルグループに置き換えます。
- <domain_name>をドメイン名に置き換えます（例: gitlab.com）。
オプション。パッケージがプライベートである場合は、パッケージレジストリへのアクセスを設定する必要があります:
```
npmRegistries:
  //<domain_name>/api/v4/packages/npm:
    npmAlwaysAuth: true
    npmAuthToken: '<token>'
```
- <domain_name>をドメイン名に置き換えます（例: gitlab.com）。
- <token>をデプロイトークン（推奨）、グループアクセストークン、プロジェクトアクセストークン、またはパーソナルアクセストークンに置き換えます。
Yarnでパッケージをインストールします。

グループまたはプロジェクトからインストール

ワンオフのパッケージがある場合は、グループまたはプロジェクトからインストールできます。

グループスコープを設定します。あなたの.yarnrc.ymlファイルに以下を追加します:
```
npmScopes:
  <my-org>:
    npmRegistryServer: 'https://<domain_name>/api/v4/groups/<group_id>/-/packages/npm'
```
- <my-org>を、インストール元のグループを含むトップレベルグループに置き換えます。@記号を除外します。
- <domain_name>をドメイン名に置き換えます（例: gitlab.com）。
- <group_id>をグループIDに置き換えます。グループ概要ページで見つけることができます。
オプション。あなたのパッケージがプライベートである場合、レジストリを設定する必要があります:
```
npmRegistries:
  //<domain_name>/api/v4/groups/<group_id>/-/packages/npm:
    npmAlwaysAuth: true
    npmAuthToken: "<token>"
```
- <domain_name>をドメイン名に置き換えます（例: gitlab.com）。
- <token>をデプロイトークン（推奨）、グループアクセストークン、プロジェクトアクセストークン、またはパーソナルアクセストークンに置き換えます。
- <group_id>をグループIDに置き換えます。グループ概要ページで見つけることができます。
Yarnでパッケージをインストールします。

プロジェクトスコープを設定します。あなたの.yarnrc.ymlファイルに以下を追加します:
```
npmScopes:
 <my-org>:
   npmRegistryServer: "https://<domain_name>/api/v4/projects/<project_id>/packages/npm"
```
- <my-org>を、インストール元のプロジェクトを含むトップレベルグループに置き換えます。@記号を除外します。
- <domain_name>をドメイン名に置き換えます（例: gitlab.com）。
- <project_id>を、プロジェクトの概要ページのプロジェクトIDに置き換えます。
オプション。あなたのパッケージがプライベートである場合、レジストリを設定する必要があります:
```
npmRegistries:
  //<domain_name>/api/v4/projects/<project_id>/packages/npm:
    npmAlwaysAuth: true
    npmAuthToken: "<token>"
```
- <domain_name>をドメイン名に置き換えます（例: gitlab.com）。
- <token>をデプロイトークン（推奨）、グループアクセストークン、プロジェクトアクセストークン、またはパーソナルアクセストークンに置き換えます。
- <project_id>を、プロジェクトの概要ページのプロジェクトIDに置き換えます。
Yarnでパッケージをインストールします。

Yarnでインストール

コマンドラインまたはCI/CDパイプラインからyarn addを実行します:

yarn add @scope/my-package

Yarn Classicでは、.npmrcファイルと.yarnrcファイルの両方が必要です。詳細については、Yarnイシュー4451を参照してください。

あなたの認証情報を.npmrcファイルに、スコープ付きレジストリを.yarnrcファイルに配置します:

# .npmrc
## For the instance
//<domain_name>/api/v4/packages/npm/:_authToken='<token>'
## For the group
//<domain_name>/api/v4/groups/<group_id>/-/packages/npm/:_authToken='<token>'
## For the project
//<domain_name>/api/v4/projects/<project_id>/packages/npm/:_authToken='<token>'

# .yarnrc
## For the instance
'@scope:registry' 'https://<domain_name>/api/v4/packages/npm/'
## For the group
'@scope:registry' 'https://<domain_name>/api/v4/groups/<group_id>/-/packages/npm/'
## For the project
'@scope:registry' 'https://<domain_name>/api/v4/projects/<project_id>/packages/npm/'

コマンドラインまたはCI/CDパイプラインからyarn addを実行します:
```
yarn add @scope/my-package
```

Yarnパッケージを削除する

前提条件:

メンテナーまたはオーナーのロールを持っている必要があります。

パッケージを削除する前に、関連するセキュリティリスクを理解していることを確認してください。

パッケージを削除するには、次のいずれかの方法があります:

UIを使用する。
APIを使用する。

トラブルシューティング

npmレジストリ用のパッケージレジストリでYarnを実行中のエラー

npmレジストリでYarnを使用している場合、次のようなエラーメッセージが表示されることがあります:

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

この場合、次のコマンドは現在のディレクトリに.yarnrcという名前のファイルを作成します。グローバル設定の場合はユーザーのホームディレクトリに、プロジェクトごとの設定の場合はプロジェクトルートにいることを確認してください:

yarn config set '//gitlab.example.com/api/v4/projects/<project_id>/packages/npm/:_authToken' '<token>'
yarn config set '//gitlab.example.com/api/v4/packages/npm/:_authToken' '<token>'

グループインストールからtarballをフェッチする際に、Yarn Classicが`404 Not Found`を返します

Yarn Classicでグループ内のレジストリからパッケージをインストールする際に、パッケージの解決は成功しても、tarballのダウンロードが404 Not Foundエラーで失敗することがあります:

[1/4] Resolving packages...
[2/4] Fetching packages...
error Error: https://gitlab.example.com/api/v4/projects/<project_id>/packages/npm/@scope/my-package/-/@scope/my-package-1.0.0.tgz: Request failed "404 Not Found"

このエラーは、グループレジストリによって返されるパッケージメタデータに、プロジェクトエンドポイントを指すtarballダウンロードURLが含まれているために発生します。.npmrcファイルにグループエンドポイント用の認証トークンのみがある場合、プロジェクトエンドポイントへのリクエストは認証されません。そして404を返します。

この問題を解決するには、グループエンドポイントとプロジェクトエンドポイントの両方の認証トークンを.npmrcファイルに追加します:

# .npmrc
//gitlab.example.com/api/v4/groups/<group_id>/-/packages/npm/:_authToken='<token>'
//gitlab.example.com/api/v4/projects/<project_id>/packages/npm/:_authToken='<token>'

Yarn Classicは短縮された認証パスで`401 Unauthorized`を返します

GitLabパッケージレジストリでYarn Classicを使用すると、認証トークンが有効であっても401 Unauthorizedエラーを受け取ることがあります。エラーメッセージは次のようになります:

error Couldn't find package "@scope/my-package" on the "npm" registry.

--verboseフラグを使用すると、ログは401ステータスコードを表示します:

verbose Performing "GET" request to "https://gitlab.com/api/v4/groups/<group_id>/-/packages/npm/..."
verbose Request "https://gitlab.com/api/v4/groups/<group_id>/-/packages/npm/..." finished with status code 401.

このイシューは、.npmrcの_authTokenエントリが、完全なエンドポイントパスの代わりに短縮された親パスを使用している場合に発生します。例:

# Does NOT work with Yarn Classic
//gitlab.com/api/v4/:_authToken='<token>'

npmバージョン8以降は階層的な認証マッチング（親パスに設定されたトークンがすべてのサブパスに適用される）をサポートしていますが、Yarn Classicは_authTokenエントリとレジストリURLの正確なパスマッチングを必要とします。

このイシューを解決するには、認証する各レジストリの完全なエンドポイントパスを.npmrcファイルで使用します。たとえば、パッケージが特定のプロジェクトでホストされているグループレジストリからインストールする場合:

# .npmrc
//gitlab.com/api/v4/groups/<group_id>/-/packages/npm/:_authToken='<token>'
//gitlab.com/api/v4/projects/<project_id>/packages/npm/:_authToken='<token>'

プロジェクトエントリは、グループエンドポイントによって返されるパッケージメタデータに、プロジェクトエンドポイントを指すtarballダウンロードURLが含まれているため必要です。

`yarn install`がリポジトリを依存としてクローンするのに失敗します

Dockerfileからyarn installを使用してDockerfileをビルドすると、次のようなエラーが発生する場合があります:

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

このイシューを解決するには、.dockerignoreファイル内のすべてのYarn関連のパスに感嘆符 (!) を追加します。

**

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