パッケージレジストリの npm パッケージ

npm パッケージマネージャークライアントが使用する特定の API エンドポイントのドキュメントについては、npm API ドキュメント を参照してください。

npmまたはyarnパッケージのビルド方法については、こちらを参照してください。

npmパッケージをGitLabパッケージレジストリに公開する方法のビデオデモをご覧ください。

GitLab パッケージレジストリへの公開

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

パッケージを公開するにはトークンが必要です。実現しようとしていることに応じて、利用可能なトークンは異なります。詳しくはトークンに関するガイダンスをレビューしてください。

  • 組織で二要素認証 (2FA) を使用している場合は、スコープをapi に設定した個人アクセストークンを使用する必要があります。
  • CI/CD パイプライン経由でパッケージを公開する場合は、CI ジョブ トークンを使用する必要があります。

トークンを作成し、後で使用するために保存してください。

ここで説明されている以外の認証方法は使用しないでください。文書化されていない認証方法は、将来削除される可能性があります。

命名規約

パッケージのインストール方法によっては、命名規則に従う必要があるかもしれません。

パッケージのインストールには、3つのAPIエンドポイントのいずれかを使用できます：

  • インスタンスレベル：インスタンスレベル: 多くの npm パッケージを異なる GitLab グループや独自の名前空間に置いている場合に使います。
  • グループレベル：同じグループやサブグループの異なるプロジェクトに多くの npm パッケージがある場合に使います。
  • プロジェクトレベル：npmパッケージが少なく、同じGitLabグループにない場合に使用します。

プロジェクトレベルやグループレベルでパッケージをインストールする場合は、命名規則に従う必要はありません。

インスタンスレベルでパッケージをインストー ルする場合は、パッケージにスコープ名を付ける必要があります。スコープ付きパッケージは、@ で始まり、@owner/package-name の形式を持ちます。.npmrc ファイルや、package.jsonのpublishConfig オプションを使用することで、パッケージのスコープを設定できます。

  • @scope に使われる値は、パッケージをホストしているプロジェクトのルートであり、パッケージ自体のソースコードがあるプロジェクトのルートではありません。スコープは小文字にしてください。
  • パッケージ名は何でもかまいません
プロジェクトの URLパッケージのレジストリスコープパッケージ名
https://gitlab.com/my-org/engineering-group/analytics分析@my-org@my-org/package-name

package.json ファイルのパッケージ名がこの規約と一致していることを確認してください：

"name": "@my-org/package-name"

コマンドラインからのパッケージの発行

による認証.npmrc

package.json と同じディレクトリに.npmrc ファイルを作成または編集します。.npmrc ファイルに以下の行を含めます：

@scope:registry=https://your_domain_name/api/v4/projects/your_project_id/packages/npm/
//your_domain_name/api/v4/projects/your_project_id/packages/npm/:_authToken="${NPM_TOKEN}"
  • @scope を、パッケージを公開するプロジェクトのルート・レベル・グループに置き換えてください。
  • your_domain_name はドメイン名に置き換えてください。例えば、gitlab.com.
  • your_project_id は、プロジェクトのホームページにあるプロジェクトIDに置き換えてください。
  • "${NPM_TOKEN}" は、このプロセスの後半で作成したトークンに関連付けられます。
caution
.npmrc ファイルやリポジトリにコミットできるその他のファイルには、GitLab トークン（あるいはあらゆるトークン）を直接ハードコードしないでください。

コマンドラインからのパッケージの発行

.npmrc の"${NPM_TOKEN}" にトークンを関連付けます。your_token をデプロイトークン、グループアクセストークン、プロジェクトアクセストークン、または個人アクセストークンに置き換えてください。

NPM_TOKEN=your_token npm publish

これでパッケージがパッケージレジストリに公開されます。

CI/CD パイプラインによるパッケージの公開

による認証.npmrc

GitLabプロジェクトのpackage.json と同じディレクトリに.npmrc ファイルを作成または編集します。.npmrc ファイルに以下の行を含めます：

@scope:registry=https://your_domain_name/api/v4/projects/your_project_id/packages/npm/
//your_domain_name/api/v4/projects/${CI_PROJECT_ID}/packages/npm/:_authToken=${CI_JOB_TOKEN}
  • @scope を、パッケージを公開するプロジェクトのルート・レベル・グループに置き換えてください。
  • ${CI_PROJECT_ID} と${CI_JOB_TOKEN} はパイプラインで利用できる定義済みの変数で、置き換える必要はありません。

CI/CD パイプラインによるパッケージの公開

.npmrc とpackage.json を内部で保存している GitLab プロジェクトで、.gitlab-ci.yml ファイルを編集または作成します。例えば

image: node:latest

stages:
  - deploy

deploy:
  stage: deploy
  script:
    - echo "//${CI_SERVER_HOST}/api/v4/projects/${CI_PROJECT_ID}/packages/npm/:_authToken=${CI_JOB_TOKEN}">.npmrc
    - npm publish

これで、パイプラインの実行時にパッケージがパッケージレジストリに公開されるようになります。

パッケージのインストール

複数のパッケージが同じ名前、同じバージョンである場合、パッケージをインストー ルする際には、最も新しく公開されたパッケージが取得されます。

GitLab プロジェクト、グループ、インスタンスからパッケージをインストールすることができます：

  • インスタンスレベル：インスタンスレベル: 多くの npm パッケージを異なる GitLab グループや独自の名前空間に置いている場合に使います。
  • グループレベル：同じGitLabグループ内の異なるプロジェクトに多くのnpmパッケージがある場合に使用します。
  • プロジェクトレベル：npmパッケージが少なく、同じGitLabグループにない場合に使用します。

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

非公開プロジェクトや非公開グループからパッケージをインストールするには、パッケージレジストリへの認証が必要です。プロジェクトやグループが公開されている場合は、認証は必要ありません。

npm で認証するには、以下のようにします：

npm config set -- //your_domain_name/:_authToken=your_token

npm バージョン 7 以前では、エンドポイントへの完全な URL を使用してください。

インストールする場合：

  • インスタンス・レベルから：

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

  • グループレベルから：

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

  • プロジェクトレベルから：

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

これらの例では

  • your_domain_name はドメイン名に置き換えてください。例えば、gitlab.com.
  • your_group_id は、グループのホームページに記載されているグループIDに置き換えてください。
  • your_project_id は、プロジェクトのホームページにあるプロジェクトIDに置き換えてください。
  • your_token をデプロイトークン、グループアクセストークン、プロジェクトアクセストークン、または個人アクセストークンに置き換えてください。
note
npm バージョン 8 以降では、_authToken パラメータに完全な URL ではなく URI フラグメントを使用できます。ただし、グループレベルのエンドポイントはサポートされていません。

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

caution
インスタンスレベルからパッケージをインストールするには、scoped命名規則に従ってパッケージが発行されている必要があります。

  1. パッケージ・レジストリに認証します。

  2. レジストリを設定します。

    npm config set @scope:registry https://your_domain_name.com/api/v4/packages/npm/
    • @scope をパッケージにインストールするプロジェクトのルートレベルのグループに置き換えます。
    • your_domain_name はドメイン名に置き換えてください。例えばgitlab.com.
    • your_token をデプロイトークン、グループアクセストークン、プロジェクトアクセストークン、または個人アクセストークンに置き換えてください。

  3. パッケージのインストール

    npm install @scope/my-package

グループレベルからのインストール

  1. パッケージ・レジストリに認証します。

  2. レジストリを設定します。

    npm config set @scope:registry=https://your_domain_name/api/v4/groups/your_group_id/-/packages/npm/
    • @scope をパッケージにインストールするグループのルートレベルのグループに置き換えてください。
    • your_domain_name はドメイン名に置き換えてください。例えば、gitlab.com.
    • your_group_id は、グループのホームページに記載されているグループIDに置き換えてください。

  3. パッケージのインストール

    npm install @scope/my-package

プロジェクトレベルからのインストール

  1. パッケージ・レジストリに認証します。

  2. レジストリを設定します。

    npm config set @scope:registry=https://your_domain_name/api/v4/projects/your_project_id/packages/npm/
    • @scope をパッケージにインストールするプロジェクトのルートレベルのグループに置き換えます。
    • your_domain_name はドメイン名に置き換えてください。例えば、gitlab.com.
    • your_project_id は、プロジェクトのホームページにあるプロジェクトIDに置き換えてください。

  3. パッケージのインストール

    npm install @scope/my-package

パッケージの廃止

GitLab 16.0 で導入されました。

パッケージを非推奨にすることで、そのパッケージがフェッチされた時に非推奨の警告を表示させることができます。

前提条件

コマンドラインから

npm deprecate @scope/package "Deprecation message"

CLIは、@scope/package のバージョン範囲も受け付けます。例えば

npm deprecate @scope/package "All package versions are deprecated"
npm deprecate @scope/package@1.0.1 "Only version 1.0.1 is deprecated"
npm deprecate @scope/package@"< 1.0.5" "All package versions less than 1.0.5 are deprecated"

非推奨警告の削除

パッケージの非推奨警告を削除するには、メッセージに"" (空文字列) を指定してください。例えば

npm deprecate @scope/package ""

役立つヒント

npmjs.comへのパッケージ転送

npm パッケージがパッケージレジストリに見つからない場合、リクエストはnpmjs.com に転送されます。

管理者は継続的インテグレーションの設定でこの動作を無効にすることができます。

グループのオーナーは、グループのパッケージとレジストリの設定でこの動作を無効にできます。

他の組織からの npm パッケージのインストール

GitLab外の組織やユーザーにパッケージリクエストをルーティングすることができます。

これを行うには、.npmrc ファイルに行を追加します。@my-other-org をプロジェクトのリポジトリを所有する名前空間やグループで置き換え、組織の URL を使用します。名前は大文字小文字を区別し、グループ名や名前空間名と正確に一致させなければなりません。

@scope:registry=https://my_domain_name.com/api/v4/packages/npm/
@my-other-org:registry=https://my_domain_name.example.com/api/v4/packages/npm/

npm メタデータ

GitLab パッケージレジストリは npm クライアントに以下の属性を公開します。これらは省略されたメタデータフォーマットに似ています：

  • name
  • versions
    • name
    • version
    • deprecated
    • dependencies
    • devDependencies
    • bundleDependencies
    • peerDependencies
    • bin
    • directories
    • dist
    • engines
    • _hasShrinkwrap

npm ディストリビューションタグの追加

新しく公開されたパッケージにディストリビューションタグを追加できます。タグはオプションで、一度に一つのパッケージにのみ割り当てることができます。

タグなしでパッケージを公開すると、latest デフォルトでタグが追加 latestされます。latest タグやバージョンを指定せずにパッケージをインストール latestすると、タグが使用されます。

サポートされているdist-tag コマンドの例です：

npm publish @scope/package --tag               # Publish a package with new tag
npm dist-tag add @scope/package@version my-tag # Add a tag to an existing package
npm dist-tag ls @scope/package                 # List all tags under the package
npm dist-tag rm @scope/package@version my-tag  # Delete a tag from the package
npm install @scope/package@my-tag              # Install a specific tag

CI/CDから

GitLab 15.10 で導入されました。

CI_JOB_TOKEN やデプロイトークンを使って、GitLab CI/CD ジョブでnpm dist-tag コマンドを実行することができます。例えば

npm-deploy-job:
  script:
    - echo "//${CI_SERVER_HOST}/api/v4/projects/${CI_PROJECT_ID}/packages/npm/:_authToken=${CI_JOB_TOKEN}">.npmrc
    - npm dist-tag add @scope/package@version my-tag

npm 6.9.0のバグにより、ディストリビューションタグの削除に失敗します。npmのバージョンが6.9.1以降であることを確認してください。

サポートされているCLIコマンド

GitLab npmリポジトリは、npm CLI (npm) と yarn CLI (yarn) で以下のコマンドをサポートしています：

  • npm install:npm パッケージをインストールします。
  • npm publish:npm パッケージをレジストリに公開します。
  • npm dist-tag add:npm パッケージに dist タグを追加します。
  • npm dist-tag ls:パッケージのdist-tagをリストアップします。
  • npm dist-tag rm:dist-tag を削除します。
  • npm ci:package-lock.json ファイルから直接 npm パッケージをインストールします。
  • npm view:パッケージのメタデータを表示します。
  • npm pack:パッケージから tarball を作成します。
  • npm deprecate:パッケージのバージョンを非推奨にします。

トラブルシューティング

404 Not Found npm install 、エラーが発生しました。yarn

CI_JOB_TOKEN を使用して、別のプロジェクトに依存する npm パッケージをインストールすると、404 Not Found エラーが発生します。パッケージとその依存関係にアクセスできるトークンで認証する必要があります。

パッケージとその依存関係が別々のプロジェクトにありながら同じグループにある場合は、グループデプロイトークンを使うことができます：

//gitlab.example.com/api/v4/packages/npm/:_authToken=<group-token>
@group-scope:registry=https://gitlab.example.com/api/v4/packages/npm/

パッケージとその依存関係が複数のグループにまたがっている場合は、すべてのグループまたは個々のプロジェクトへのアクセス権を持つユーザーの個人アクセストークンを使用できます：

//gitlab.example.com/api/v4/packages/npm/:_authToken=<personal-access-token>
@group-1:registry=https://gitlab.example.com/api/v4/packages/npm/
@group-2:registry=https://gitlab.example.com/api/v4/packages/npm/
caution
個人アクセストークンの扱いには注意が必要です。個人アクセストークンを管理するためのガイダンス (たとえば、有効期限を短く設定する、最小限のスコープを使うなど) については、トークンのセキュリティに関する考慮事項をお読みください。

npm publish ターゲットのデフォルト npm レジストリ (registry.npmjs.org)

package.json と.npmrc ファイルで、パッケージスコープが一貫して設定されていることを確認してください。

たとえば、GitLab のプロジェクト名が@scope/my-package の場合、package.json ファイルは次のようになります：

{
  "name": "@scope/my-package"
}

また、.npmrc ファイルは次のようになります：

@scope:registry=https://your_domain_name/api/v4/projects/your_project_id/packages/npm/
//your_domain_name/api/v4/projects/your_project_id/packages/npm/:_authToken="${NPM_TOKEN}"

npm install リターンnpm ERR! 403 Forbidden

このエラーが発生した場合は、次のことを確認してください：

  • プロジェクト設定でパッケージ・レジストリが有効になっていることを確認してください。パッケージ・レジストリはデフォルトで有効になっていますが、無効にすることもできます。
  • あなたのトークンは有効期限が切れておらず、適切な権限を持っています。
  • 指定されたスコープ内に同じ名前またはバージョンのパッケージが既に存在しません。
  • スコープされたパッケージの URL には末尾のスラッシュが含まれます：
    • 正しいです：//gitlab.example.com/api/v4/packages/npm/
    • 不正解：//gitlab.example.com/api/v4/packages/npm

npm publish リターンnpm ERR! 400 Bad Request

このエラーが発生した場合、以下のいずれかの問題が原因となっている可能性があります。

パッケージ名が命名規則に適合していません。

あなたのパッケージ名は@scope/package-name パッケージ命名規約を満たしていないかもしれません。

大文字と小文字を含め、パッケージ名が規約を正確に満たしていることを確認してください。その後、再度公開を試みてください。

パッケージがすでに存在します

パッケージはすでに同じルート名前空間の別のプロジェクトに公開されているため、同じ名前を使用して再度公開することはできません。

これは、先に公開されたパッケージが同じ名前であっても同じです。

パッケージのJSONファイルが大きすぎます

package.json ファイルが20,000 文字を超えないようにしてください。

npm publish リターンnpm ERR! 500 Internal Server Error - PUT

これはGitLab 13.3.x以降の既知のイシューです。ログのエラーは以下のように表示されます：

>NoMethodError - undefined method `preferred_language' for #<Rack::Response

これは別のエラーを伴っている可能性があります：

>Errno::EACCES","exception.message":"Permission denied

これは通常、どちらかの権限の問題です：

後者の場合、バケットが存在し、GitLabがそのバケットへの書き込みアクセス権を持っていることを確認します。