GitLab NPMレジストリ

GitLab Premium11.7から導入されました。

GitLab Npmレジストリを使えば、すべてのプロジェクトはNPMパッケージを保存するための独自のスペースを持つことができます。

GitLab NPM Registry

注意:スコープされたパッケージのみがサポートされています。

npm レジストリの有効化

Note:このオプションは、GitLab管理者がレジストリのサポートを有効にしている場合にのみ使用できます。

NPM レジストリを有効にすると、デフォルトですべての新規プロジェクトで使用できるようになります。 既存のプロジェクトで有効にしたり、無効にしたりするには、次のようにします：

  1. プロジェクトの[設定]>[一般]>[権限]に移動します。
  2. パッケージ機能を検索し、有効または無効にします。
  3. 変更を有効にするには、[変更を保存]をクリックします。

左サイドバーに「パッケージ＆レジストリ」セクションが表示されます。

GitLab NPMレジストリでの認証に進む前に、パッケージの命名規則に慣れておく必要があります。

利用を開始

このセクションでは、NPM (または Yarn) のインストールと、JavaScript プロジェクト用のパッケージのビルドについて説明します。 NPM パッケージを初めて使用する場合のクイックスタートです。 すでに NPM を使用しており、独自のパッケージのビルド方法を理解している場合は、次のセクションに進んでください。

npmのインストール

npmjs.comの指示に従って、Node.jsとNPMをダウンロードしてローカル開発環境にインストールします。

インストールが完了したら、ターミナルで npm を実行し、使用できることを確認します： 

npm --version

npm のバージョンが出力されるはずです： 

6.10.3

毛糸のインストール

NPMの代替としてYarnをインストールして使用することもできます。yarnpkg.comの指示に従って開発環境にインストールしてください。

インストールが完了したら、以下のコマンドでYarnが利用可能であることを確認できます： 

yarn --version

このように印刷されます： 

1.19.1

プロジェクトの作成

完全なJavaScriptプロジェクトを作成する方法を理解することは、このガイドの範囲外ですが、空のディレクトリを作成して移動し、次のコマンドを使用することで、新しい空のパッケージを初期化することができます： 

npm init

あるいはヤーンを使うなら： 

yarn init

これはすべての NPM パッケージに必要なpackage.jsonファイルを作成するための一連の質問です。 最も重要な質問はパッケージ名です。 NPM パッケージは命名規則に従い、レジストリが存在するプロジェクトまたはグループにスコープされなければなりません。

設定が完了したら、あとは GitLab レジストリにパッケージをアップロードするだけです。 まずは認証を設定し、GitLab をリモートレジストリとして設定します。

GitLab NPMレジストリへの認証

プロジェクトが非公開であったり、GitLab に NPM パッケージをアップロードしたい場合は、認証のためにクレデンシャルを提供する必要があります。パーソナルアクセストークンやデイトプロイトークンが望ましいですが、OAuth トークンのサポートもあります。

二要素認証 (2FA) は個人アクセストークンでのみサポートされています。2FA を有効にしている場合は、スコープをapi に設定した OAuth ヘッダー付きの個人アクセストークン、またはread_package_registry またはwrite_package_registry スコープ付きのデプロイトークンを使用する必要があります。標準の OAuth トークンでは GitLab NPM レジストリを認証できません。

個人アクセストークンまたはデプロイトークンによる認証

個人アクセストークンまたはデプロイトークンで認証するには、npmの設定を行います： 

# Set URL for your scoped packages.
# For example package with name `@foo/bar` will use this URL for download
npm config set @foo:registry https://gitlab.com/api/v4/packages/npm/

# Add the token for the scoped packages URL. This will allow you to download
# `@foo/` packages from private projects.
npm config set '//gitlab.com/api/v4/packages/npm/:_authToken' "<your_token>"

# Add token for uploading to the registry. Replace <your_project_id>
# with the project you want your package to be uploaded to.
npm config set '//gitlab.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken' "<your_token>"

<your_project_id> をプロジェクトのホームページに記載されているプロジェクトIDに、<your_token> を個人のアクセストークンまたはデプロイトークンに置き換えてください。

GitLab をセルフマネジメントでインストールしている場合は、gitlab.com をドメイン名に置き換えてください。

これで npm パッケージをダウンロードしてプロジェクトにアップロードできるはずです。

注意：Yarnでエラーメッセージが表示された場合は、トラブルシューティングのセクションをご覧ください。

変数の使用による認証トークン値のハードコーディングの回避

authToken の値をハードコーディングするのを避けるために、変数を代わりに使うことができます： 

npm config set '//gitlab.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken' "${NPM_TOKEN}"
npm config set '//gitlab.com/api/v4/packages/npm/:_authToken' "${NPM_TOKEN}"

その後、npm publish を内部で実行するか、GitLab CI/CD経由で実行することができます：

  • 内部： NPM_TOKEN をエクスポートしてから公開します： 

     NPM_TOKEN=<your_token> npm publish

  • GitLab CI/CD:プロジェクトの設定 > CI/CD > 変数でNPM_TOKEN 変数を設定します。

CIジョブトークンによる認証

GitLab Premium 12.5で導入されました。

GitLab CI/CD で NPM を使っている場合、個人アクセストークンや デプロイトークンの代わりに CI ジョブトークンを使うことができます。 トークンはパイプラインを生成したユーザーの権限を継承します。

.npmrc ファイルに対応するセクションを追加してください： 

@foo:registry=https://gitlab.com/api/v4/packages/npm/
//gitlab.com/api/v4/packages/npm/:_authToken=${CI_JOB_TOKEN}
//gitlab.com/api/v4/projects/${CI_PROJECT_ID}/packages/npm/:_authToken=${CI_JOB_TOKEN}

パッケージのアップロード

パッケージをアップロードする前に、NPMのレジストリを指定する必要があります。 そのためには、package.jsonの一番下に以下のセクションを追加します： 

"publishConfig": {
  "@foo:registry":"https://gitlab.com/api/v4/projects/<your_project_id>/packages/npm/"
}

<your_project_id> はあなたのプロジェクトIDに置き換えてください。このIDはプロジェクトのホームページに記載されています。また、@foo はあなた自身のスコープに置き換えてください。

GitLab をセルフマネジメントでインストールしている場合は、gitlab.com をドメイン名に置き換えてください。

有効にして認証を設定したら、プロジェクトに npm パッケージをアップロードできます： 

npm publish

その後、プロジェクトのパッケージとレジストリページに移動して、アップロードされたパッケージを確認したり、削除したりすることができます。

指定したスコープ内にすでに存在する名前のパッケージを公開しようとすると、403 Forbidden! エラーが発生します。

同じバージョンのパッケージを2回アップロードする場合

まず既存のパッケージを削除しない限り、同じ名前とバージョンのパッケージを二度アップロードすることはできません。 これは npmjs.org の動作と一致していますが、npmjs.org では同じバージョンを二度以上公開することは、たとえ削除されたとしても許可されていません。

パッケージの命名規則

パッケージはプロジェクトのルート名前空間にスコープされなければなりません。 パッケージ名は何でもかまいませんが、名前の衝突で不可能な場合を除き、プロジェクト名を使用することが望ましいです。 例えば、以下のようになります：

プロジェクト Package サポート
foo/bar @foo/bar はい
foo/bar/baz @foo/baz はい
foo/bar/buz @foo/anything はい
gitlab-org/gitlab @gitlab-org/gitlab はい
gitlab-org/gitlab @foo/bar いいえ

名前付けに使われる正規表現は、すべてのパッケージマネージャのすべてのパッケージ名を検証します： 

/\A\@?(([\w\-\.\+]*)\/)*([\w\-\.]+)@?(([\w\-\.\+]*)\/)*([\w\-\.]*)\z/

大文字が使えますが npm では使えません。また、いくつかの例外を除いて NPM で使えるほぼすべての文字が使えます (~ は使えません)。

注：大文字が必要なのは、スコープがプロジェクトのトップレベルの名前空間と同一である必要があるためです。したがって、たとえばプロジェクトのパスがMy-Group/project-fooの場合、パッケージの名前は@My-Group/any-package-nameでなければなりません。@my-group/any-package-name ではうまくいきません。
ユーザー/グループのパスを更新したり、(サブ)グループ/プロジェクトを転送したりする場合:NPM パッケージを含むプロジェクトのルート名前空間を更新すると、変更が却下されます。 これを許可するには、まず NPM パッケージを削除してください。.npmrc ファイルを上記の命名規則に従って更新し、必要に応じてnpm publish を実行することを忘れないでください。

これで、GitLab NPM レジストリで認証するようにプロジェクトを設定することができます。

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

NPM パッケージは通常、JavaScript プロジェクト内部でnpm またはyarn コマンドを使ってインストールします。 まだインストールしていない場合は、scoped パッケージの URL を設定する必要があります。 これは次のコマンドで実行できます： 

npm config set @foo:registry https://gitlab.com/api/v4/packages/npm/

@foo をスコープと交換する必要があります。

次に、パッケージのインストールを成功させるために、認証がセットアップされていることを確認する必要があります。 これが完了したら、プロジェクト内で以下のコマンドを実行してパッケージをインストールします： 

npm install @my-project-scope/my-package

あるいはヤーンを使うなら： 

yarn add @my-project-scope/my-package

npmjs.org へのリクエスト転送

GitLab Premium12.9で導入されました。

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

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

パッケージの削除

プロジェクトページのPackagesビューで、赤いゴミ箱アイコンをクリックするか、パッケージ詳細ページのDeleteボタンをクリックすると、パッケージを削除できます。

CI/CDによるパッケージの公開

GitLab CI/CD内でNPMコマンドを操作するには、コマンド内でパーソナルアクセストークンやデプロイトークンの代わりにCI_JOB_TOKEN 。

NPM パッケージを公開するためのシンプルな例.gitlab-ci.yml ファイルです： 

image: node:latest

stages:
  - deploy

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

について詳しくはこちらCI_JOB_TOKEN を使って GitLab NPM レジストリに認証。

トラブルシューティング

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

この場合、.npmrc ファイルにこれを追加してみてください（<your_token>を個人のアクセストークンまたはデプロイトークンに置き換えてください）： 

//gitlab.com/api/v4/projects/:_authToken=<your_token>

npm publish はデフォルトの NPM レジストリ (registry.npmjs.org) を対象とします。

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

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

{
  "name": "@foo/my-package",
  "version": "1.0.0",
  "description": "Example package for GitLab NPM registry",
  "publishConfig": {
    "@foo:registry":"https://gitlab.com/api/v4/projects/<your_project_id>/packages/npm/"
  }
}

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

//gitlab.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken=<your_token>
//gitlab.com/api/v4/packages/npm/:_authToken=<your_token>
@foo:registry=https://gitlab.com/api/v4/packages/npm/

npm install 収益Error: Failed to replace env in config: ${NPM_TOKEN}

プロジェクトが非公開でない限り、npm install を実行するためにトークンは必要ありません（トークンは公開するときにのみ必要です）。.npmrc ファイルが$NPM_TOKENへの参照とともにチェックインされていた場合は、それを削除することができます。参照を残しておきたい場合は、npm install を実行する前に値を設定するか、GitLab環境変数を使って値を設定する必要があります： 

NPM_TOKEN=<your_token> npm install

npm install 収益npm ERR! 403 Forbidden

  • トークンの有効期限が切れていないか、適切な権限を持っているかを確認してください。
  • 指定されたスコープ内に既に存在する名前のパッケージを公開しようとしたかどうかをチェックします。
  • スコープされたパッケージのURLに末尾のスラッシュが含まれていることを確認してください：
    • その通りです：//gitlab.com/api/v4/packages/npm/
    • 不正解です：//gitlab.com/api/v4/packages/npm

npm 依存メタデータ

GitLab Premium 12.6で導入されました。

GitLab 12.6から、GitLab NPMレジストリに公開された新しいパッケージはNPMクライアントに以下の属性を公開します：

  • 名称
  • バージョン
  • ディストタグ
  • 依存関係
    • 依存関係
    • devDependencies
    • バンドル依存関係
    • ピア依存関係
    • 旧式

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

GitLab Premium 12.8で導入されました。

新しく公開されたパッケージにはディストリビューションタグを追加することができます。ディストリビューションタグはNPM の慣例にしたがって任意で、一度にひとつのパッケージにしか割り当てることができません。 タグなしでパッケージが公開された場合、デフォルトでlatest タグが追加されます。 タグやバージョンを指定せずにパッケージをインストールする場合も同様です。

サポートされているdist-tag コマンドの例と、一般的なタグの使い方： 

npm publish @scope/package --tag               # Publish new 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
警告:NPM 6.9.0のバグにより、distタグの削除に失敗します。 NPMのバージョンが6.9.1以上であることを確認してください。