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

Node Package Manager（npm）は、JavaScriptおよびNode.jsのデフォルトのパッケージマネージャーです。デベロッパーはnpmを使用して、コードの共有と再利用、依存関係の管理、プロジェクトワークフローの効率化を行います。GitLabでは、npmパッケージはソフトウェア開発ライフサイクルにおいて重要な役割を果たします。

APIについては、こちらをご覧ください。

GitLabパッケージレジストリにnpmパッケージを公開する方法については、こちらの動画デモをご覧ください。

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

プライベートプロジェクトまたはプライベートグループからパッケージを公開またはインストールするには、パッケージレジストリに対して認証を行う必要があります。プロジェクトまたはグループがパブリックの場合、認証は不要です。プロジェクトが内部の場合、GitLabインスタンスの登録ユーザーである必要があります。匿名ユーザーは内部プロジェクトからパッケージをプルできません。

認証するには、次のいずれかを使用できます:

• スコープがapiに設定された次のいずれかのトークン:
  • パーソナルアクセストークン
  • グループアクセストークン
  • プロジェクトアクセストークン
• スコープがread_package_registryとwrite_package_registryのどちらか、または両方に設定されたデプロイトークン。
• CI/CDパイプラインでパッケージを公開する場合は、CI/CDジョブトークン。

組織が2要素認証（2FA）を使用している場合、スコープがapiに設定されたパーソナルアクセストークンを使用する必要があります。詳細については、トークンに関するガイダンス参照してください。

ここに記載されている方法以外の認証方法は使用しないでください。ドキュメント化されていない認証方法は、将来削除される可能性があります。

.npmrcファイルを使用する場合

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

  //<domain_name>/api/v4/projects/<project_id>/packages/npm/:_authToken="${NPM_TOKEN}"

次に例を示します:

//<domain_name>/api/v4/packages/npm/:_authToken="${NPM_TOKEN}"

//<domain_name>/api/v4/groups/<group_id>/-/packages/npm/:_authToken="${NPM_TOKEN}"

//<domain_name>/api/v4/projects/<project_id>/packages/npm/:_authToken="${NPM_TOKEN}"

npm config setを使用する場合

これを行うには、以下を実行します:

npm config set -- //<domain_name>/:_authToken=<token>

npmのバージョンによっては、URLを変更する必要が生じる場合があります:

• npmバージョン7以前では、完全なURLをエンドポイントに使用してください。
• バージョン8以降では、_authTokenパラメータに対して、完全なURIの代わりにURIフラグメントを使用できます。詳細については、Auth related configurationを参照してください。

次に例を示します:

npm config set -- //<domain_name>/api/v4/packages/npm/:_authToken=<token>

npm config set -- //<domain_name>/api/v4/groups/<group_id>/-/packages/npm/:_authToken=<token>

npm config set -- //<domain_name>/api/v4/projects/<project_id>/packages/npm/:_authToken=<token>

レジストリURLを設定する

GitLabパッケージレジストリからパッケージを公開またはインストールするには、正しいレジストリURLを使用するようにnpmを設定する必要があります。設定方法とURL構造は、パッケージを公開するかインストールするかによって異なります。

レジストリURLを設定する前に、さまざまな設定方法のスコープを理解することが重要です:

• .npmrcファイル: ファイルを含むフォルダーに対してローカルに設定されます。
• npm config setコマンド: グローバルnpm設定を変更し、システムで実行されるすべてのnpmコマンドに影響します。
• publishConfig（package.json内）: この設定はパッケージに固有であり、そのパッケージを公開するときにのみ適用されます。

パッケージを公開する場合

パッケージを公開する場合は、プロジェクトエンドポイントを使用します:

https://gitlab.example.com/api/v4/projects/<project_id>/packages/npm/

gitlab.example.comをGitLabインスタンスのドメインに、<project_id>をプロジェクトIDに置き換えます。このURLを設定するには、次のいずれかの方法を使用します:

@scope:registry=https://gitlab.example.com/api/v4/projects/<project_id>/packages/npm/
//gitlab.example.com/api/v4/projects/<project_id>/packages/npm/:_authToken="${NPM_TOKEN}"

npm config set @scope:registry=https://gitlab.example.com/api/v4/projects/<project_id>/packages/npm/

{
  "publishConfig": {
    "@scope:registry": "https://gitlab.example.com/api/v4/projects/<project_id>/packages/npm/"
  }
}

@scopeをパッケージのスコープに置き換えます。

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

パッケージをインストールするときは、プロジェクト、グループ、またはインスタンスのエンドポイントを使用できます。URL構造はそれぞれに応じて異なります。これらのURLを設定するには、次のいずれかの方法を使用します:

gitlab.example.com、<project_id>、<group_id>、@scopeを、GitLabインスタンスとパッケージの適切な値に置き換えます。

レジストリURLを設定したら、パッケージレジストリに対して認証を行うことができます。

GitLabパッケージレジストリに公開する

npmパッケージをGitLabパッケージレジストリに公開するには、認証されている必要があります。

命名規則

パッケージのインストール方法によっては、命名規則に従う必要がある場合があります。

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

• インスタンス: 異なるGitLabグループまたは独自のネームスペースに多数のnpmパッケージがある場合に使用します。
• グループ: 同じグループまたはサブグループの異なるプロジェクトに多数のnpmパッケージがある場合に使用します。
• プロジェクト: npmパッケージの数が少なく、それらが同じGitLabグループにない場合に使用します。

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

インスタンスからパッケージをインストールする場合は、スコープを使用してパッケージに名前を付ける必要があります。スコープ付きパッケージは@で始まり、@owner/package-nameの形式になります。.npmrcファイルで、およびpackage.jsonでpublishConfigオプションを使用して、パッケージのスコープを設定できます。

• @scopeに使用される値は、パッケージのソースコードを含むプロジェクトのルートではなく、パッケージをホストしているプロジェクトのルートです。スコープは小文字にする必要があります。
• パッケージ名は任意に設定できます。

詳細については、スコープ付きパッケージを参照してください。

package.jsonファイル内のパッケージの名前が、次の規則に一致していることを確認してください:

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

コマンドラインでパッケージを公開する

認証を設定したら、次のコマンドでNPMパッケージを公開します:

npm publish

.npmrcファイルを認証に使用している場合は、予想される環境変数を設定します:

NPM_TOKEN=<token> npm publish

アップロードされたパッケージに複数のpackage.jsonファイルがある場合、最初に見つかったファイルのみが使用され、その他は無視されます。

CI/CDパイプラインでパッケージを公開する

CI/CDパイプラインを使用して公開する場合は、定義済み変数の${CI_PROJECT_ID}と${CI_JOB_TOKEN}を使用して、プロジェクトのパッケージレジストリで認証できます。これらの変数を使用して、CI/CDパイプラインジョブの実行中に認証を行うための.npmrcファイルを作成できます。

package.jsonを含むGitLabプロジェクトで、.gitlab-ci.ymlファイルを編集または作成します。次に例を示します:

default:
  image: node:latest

stages:
  - deploy

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

@scopeを、公開するパッケージのスコープに置き換えます。

パイプラインでpublish-npmジョブが実行されると、パッケージがパッケージレジストリに公開されます。

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

複数のパッケージの名前とバージョンが同じ場合、パッケージをインストールすると、最後に公開されたパッケージが取得されます。

GitLabのプロジェクト、グループ、またはインスタンスからパッケージをインストールできます:

• インスタンス: 異なるGitLabグループまたは独自のネームスペースに多数のnpmパッケージがある場合に使用します。
• グループ: 同じGitLabグループの異なるプロジェクトに多数のnpmパッケージがある場合に使用します。
• プロジェクト: npmパッケージの数が少なく、それらが同じGitLabグループにない場合に使用します。

インスタンスからインストールする

前提要件:

• パッケージが、スコープ付き命名規則に従って公開されていること。

1. パッケージレジストリに対して認証する

2. レジストリを次のように設定します:

   npm config set @scope:registry https://<domain_name>.com/api/v4/packages/npm/

   • @scopeを、パッケージをインストールするプロジェクトのトップレベルグループに置き換えます。
   • <domain_name>をドメイン名に置き換えます（例: gitlab.com）。

3. パッケージをインストールします:

   npm install @scope/my-package

グループからインストールする

1. パッケージレジストリに対して認証する

2. レジストリを次のように設定します:

   npm config set @scope:registry=https://<domain_name>/api/v4/groups/<group_id>/-/packages/npm/

   • @scopeを、パッケージをインストールするグループのトップレベルグループに置き換えます。
   • <domain_name>をドメイン名に置き換えます（例: gitlab.com）。
   • <group_id>を、グループのホームページのグループIDに置き換えます。

3. パッケージをインストールします:

   npm install @scope/my-package

プロジェクトからインストールする

1. パッケージレジストリに対して認証する

2. レジストリを次のように設定します:

   npm config set @scope:registry=https://<domain_name>/api/v4/projects/<project_id>/packages/npm/

   • @scopeを、パッケージをインストールするプロジェクトのトップレベルグループに置き換えます。
   • <domain_name>をドメイン名に置き換えます（例: gitlab.com）。
   • <project_id>を、プロジェクトの概要ページのプロジェクトIDに置き換えます。

3. パッケージをインストールします:

   npm install @scope/my-package

CI/CDパイプライン内でパッケージをインストールする

CI/CDパイプライン内でパッケージをインストールする場合、定義済み変数である${CI_PROJECT_ID}と${CI_JOB_TOKEN}を使用して、プロジェクトのパッケージレジストリで認証できます。これらの変数を使用して、CI/CDパイプラインジョブの実行中に認証を行うための.npmrcファイルを作成できます。

package.jsonを含むGitLabプロジェクトで、.gitlab-ci.ymlファイルを編集または作成します。次に例を示します:

default:
  image: node:latest

stages:
  - deploy

publish-npm:
  stage: deploy
  script:
    - echo "@scope:registry=https://${CI_SERVER_HOST}/api/v4/projects/${CI_PROJECT_ID}/packages/npm/" > .npmrc
    - echo "//${CI_SERVER_HOST}/api/v4/projects/${CI_PROJECT_ID}/packages/npm/:_authToken=${CI_JOB_TOKEN}" >> .npmrc
    - npm install @scope/my-package

@scopeを、インストールするパッケージのスコープ、およびパッケージ名に置き換えます。

前の例では、プロジェクトレベルのエンドポイントを使用しています。グループレベルまたはインスタンスレベルのエンドポイントを使用するには、グループからのインストールまたはインスタンスからのインストールで説明されているように、レジストリと認証トークンのURLを設定します。

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

npmパッケージがパッケージレジストリにない場合、GitLabはHTTPリダイレクトで応答し、リクエストクライアントがnpmjs.comにリクエストを再送信できるようにします。

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

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

改善点はエピック3608で追跡されています。

パッケージを非推奨にする

パッケージを非推奨にすると、パッケージのフェッチ時に非推奨の警告を表示できます。

前提要件:

• パッケージを削除するために必要な権限を持っていること。
• パッケージレジストリに対して認証されていること。

コマンドラインから、以下を実行します:

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"

パッケージが非推奨になると、そのステータスがdeprecatedに更新されます。

非推奨の警告を削除する

パッケージの非推奨の警告を削除するには、メッセージに""（空の文字列）を指定します。次に例を示します:

npm deprecate @scope/package ""

パッケージの非推奨の警告が削除されると、そのステータスがdefaultに更新されます。

役立つヒント

他の組織から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
  • hasInstallScript：このバージョンにインストールスクリプトがある場合はtrue。

詳細については、省略形のバージョンオブジェクトを参照してください。

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

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

タグを指定せずにパッケージを公開すると、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 CI/CDジョブでnpm dist-tagコマンドを実行するには、次のいずれかのトークンを使用できます:

• CI_JOB_TOKEN
• デプロイトークン

前提要件:

• npmバージョン6.9.1以降が必要です。以前のバージョンでは、npm 6.9.0のバグによりディストリビューションタグの削除に失敗します。

次に例を示します:

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パッケージを監査する

GitLabはnpm auditコマンドをサポートしており、既知の脆弱性がないかパッケージをチェックできます。

npm auditを使用する

前提要件:

• パッケージレジストリへの認証を設定します。
• レジストリURLを設定します。

セキュリティ監査を実行するには、次のコマンドを実行します:

npm audit --registry=https://gitlab.example.com/api/v4/packages/npm/

または、レジストリ設定がすでに完了している場合は、次のコマンドを実行します:

npm audit

npm auditコマンドは、既知の脆弱性の依存関係をチェックし、レポートを提供します。

npm auditワークフロー

GitLabパッケージレジストリに対してnpm auditを実行すると、次の2つのシナリオのいずれかが発生します:

1. パッケージ転送が有効になっている場合（デフォルト）、GitLabは監査リクエストをnpmjs.comに転送して、パブリックパッケージとプライベートパッケージの両方に関する脆弱性情報を取得します。
2. パッケージ転送が無効になっている場合、GitLabは空の結果セットを返します。GitLabは、脆弱性についてパッケージを個別にスキャンしません。

セキュリティに関する重要な考慮事項

GitLabをパッケージレジストリとして指定しない場合（--registryフラグを使用するか、.npmrcファイルでGitLabをデフォルトのレジストリとして設定することにより）、監査リクエストは、代わりにパブリックnpmレジストリに送信されます。

この場合、リクエスト本文には、プライベートGitLabパッケージを含む、プロジェクト内のすべてのパッケージに関する情報が含まれます。

プライベートパッケージ情報がGitLab内に留まるようにするには、npm auditコマンドを実行する際に、常にGitLabレジストリを指定するようにしてください。

既知の問題

• 監査の結果は、パッケージ転送が有効になっているかどうかによって異なります。管理者またはグループのオーナーが転送を無効している場合、npm auditは脆弱性情報を返しません。
• 監査リクエストには、プライベートパッケージを含む、プロジェクト内のすべてのパッケージに関する情報が含まれます。

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

GitLab npmリポジトリは、npm CLI（npm）とyarn CLI（yarn）の次のコマンドをサポートしています:

• npm install: npmパッケージをインストールします。
• npm publish: npmパッケージをレジストリに公開します。
• npm dist-tag add: npmパッケージにディストリビューションタグを追加します。
• npm dist-tag ls: パッケージのディストリビューションタグを一覧表示します。
• npm dist-tag rm: ディストリビューションタグを削除します。
• npm ci: package-lock.jsonファイルからnpmパッケージを直接インストールします。
• npm view: パッケージのメタデータを表示します。
• npm pack: パッケージからtarballを作成します。
• npm deprecate: パッケージのバージョンを非推奨にします。
• npm audit: プロジェクトの依存関係に脆弱性がないかチェックします。

トラブルシューティング

npmログが正しく表示されない

次のエラーが発生する可能性があります:

npm ERR! A complete log of this run can be found in: .npm/_logs/<date>-debug-0

ログが.npm/_logs/ディレクトリに表示されない場合は、ログをルートディレクトリにコピーして、そこで表示できます:

  script:
    - npm install --loglevel verbose
    - cp -r /root/.npm/_logs/ .
  artifacts:
    paths:
      - './_logs'

npmログは、アーティファクトとして/root/.npm/_logs/にコピーされます。

npm installまたはyarnで404 Not Foundエラーが発生している

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/

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パッケージの命名規則を満たしていない可能性があります。

名前が、大文字と小文字を含め、規則に正確に合致していることを確認してください。その後、再度公開してみてください。

パッケージがすでに存在する

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

これは、以前に公開されたパッケージが同じ名前で、バージョンが異なる場合でも当てはまります。

Package JSONファイルが大きすぎる

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