はじめに
この記事はユニークビジョン株式会社 Advent Calendar 2020 12日目の記事です。
社内ライブラリをnpmプライベートパッケージとして公開したのですが、これがとても便利だったので記事にしようと思いました。プライベートなプロジェクトだからNPMに公開できないと思っている方は是非試して欲しいです。
当記事ではGitLabのプライベートプロジェクトをNPMパッケージとして公開する手順、及びGitLab CI/CDを使ったリリースの自動化手順、公開したパッケージのインストール手順を紹介します。
ちなみに同手順の公式ドキュメントはこちらになります。
NPMパッケージを公開するメリット
- ライブラリを導入するプロジェクトから完全に切り離して開発ができる。
- 独自ライブラリをnpmの管理下にできる。
- ライブラリの導入が簡単になる。
- ライブラリバージョン管理できる
プライベートなGitLabプロジェクトをNPMパッケージとして公開
公開までの手順は以下になります。
- パッケージ名の命名規則
- パッケージレジストリへの認証設定を
.npmrcに記述 - パーソナルアクセストークンの取得
- パッケージの公開
パッケージ名の命名規則
パッケージ名は@scope/package-nameのような形式である必要があります。
scope： GitLabプロジェクトのルート名前空間です。
例えばプロジェクトがhttps://gitlab.example.com/my-org/engineering-group/team-amazing/analytics場合、ルート名前空間はmy-orgになります。package-name： 好きなパッケージ名を指定できます。
命名規則に沿ったpackage.jsonは以下のようになります。
{
"name": "@scope/package-name",
"version": "0.1.0",
...
}
パッケージレジストリへの認証設定を.npmrcに記述
@scope:registry=https://gitlab.example.com/api/v4/projects/${GITLAB_PROJECT_ID}/packages/npm/
//gitlab.example.com/api/v4/packages/npm/:_authToken=${GITLAB_ACCESS_TOKEN}
//gitlab.example.com/api/v4/projects/${GITLAB_PROJECT_ID}/packages/npm/:_authToken=${GITLAB_ACCESS_TOKEN}
-
scope： GitLabプロジェクトのルート名前空間に置き換えます。パッケージ名のscopeと同一です。 -
gitlab.example.com： ドメイン名に置き換えます。 -
GITLAB_PROJECT_ID： プロジェクトのホームページにあるプロジェクトIDです。環境変数として指定します。 -
GITLAB_ACCESS_TOKEN： パーソナルアクセストークンまたはデプロイトークンです。後述する手順でトークンを取得します。環境変数として指定します。
プロジェクトのホームページにあるプロジェクトIDです。
パーソナルアクセストークンまたはデプロイトークンです。
gitlab.example.comドメイン名に置き換えます。
パーソナルアクセストークンの取得
※ 後述するGitLab CI/CDからリリースする手順では別のトークンを利用するため、ここで作成したトークンはローカルからの実行のみに使います。
- パーソナルアクセストークンはGitLabのWebページから作成できます。
- 「設定」→「アクセストークン」からアクセストークン画面を開きます。
名前有効期限日(任意)を入力し、スコープはapiをチェックします。
「Create personal access token」をクリックするとトークンが生成されます。
取得したトークンを
GITLAB_ACCESS_TOKEN環境変数にセットします。
パッケージの公開
GITLAB_PROJECT_IDとGITLAB_ACCESS_TOKENの環境変数を設定し、npm publishコマンドを実行します。
以下コマンド例
$ GITLAB_PROJECT_ID=12345678 GITLAB_ACCESS_TOKEN=_nk4przrfWPLMCppDW9s npm publish
※ このコードのGITLAB_ACCESS_TOKENは失効済みです。
403 Forbiddenエラーが発生した場合
npm publishする際はパッケージ名とバージョンがユニークである必要があります。すでに一度公開していた場合、バージョン番号が公開済みのものと重複していると思われますのでpackage.jsonのversionを変更してリトライしましょう。
GitLab CI/CDでリリースを更に簡単に
.gitlab-ci.ymlファイルの作成
以下のような.gitlab-ci.ymlファイルサンプルコードを用意しました。
stages:
- publish
variables:
GITLAB_PROJECT_ID: '$CI_PROJECT_ID'
GITLAB_ACCESS_TOKEN: '$CI_JOB_TOKEN'
publish:
image: node:14
stage: publish
rules:
- if: '$CI_PIPELINE_SOURCE == "web"'
when: on_success
- when: never
script:
- npm publish
$CI_PROJECT_ID： CI/CDで使えるプロジェクトIDの環境変数です。
$CI_JOB_TOKEN： CI/CDで使えるジョブトークンの環境変数です。パッケージレジストリの認証にはこのトークンも使用できます。
このサンプルコードではrulesでWebページから実行されたときだけ公開されるようになっています。
必要ならテストやビルドも含めることもできます。詳細はGitLab CI/CDで調べてみてください。
リリース手順
前述の.gitlab-ci.ymlファイルの場合の手順を載せています。
-
package.jsonのversionを変更してプッシュします。 - GitLab Webページ CI/CD画面の「パイプラインを実行」からリリースしたいブランチを選んで実行します。
公開したパッケージのインストール手順
公開したパッケージのインストール手順は以下になります。
- パッケージレジストリへの認証設定を
.npmrcに記述 - パーソナルアクセストークンの取得
- パッケージをインストール
パッケージレジストリへの認証設定を.npmrcに記述
インストール手順としては以下のようなコマンドを用意しましょう。
$ echo "@scope:registry=https://gitlab.example.com/api/v4/projects/<GITLAB_PROJECT_ID>/packages/npm/" >> .npmrc
$ echo "//gitlab.example.com/api/v4/packages/npm/:_authToken=${GITLAB_ACCESS_TOKEN}" >> .npmrc
$ echo "//gitlab.example.com/api/v4/projects/<GITLAB_PROJECT_ID>/packages/npm/:_authToken=${GITLAB_ACCESS_TOKEN}" >> .npmrc
-
scope： GitLabプロジェクトのルート名前空間に置き換えます。パッケージ名のscopeと同一です。 -
gitlab.example.com： ドメイン名に置き換えます。 -
<GITLAB_PROJECT_ID>： プロジェクトのホームページにあるプロジェクトIDに置き換えます。 -
GITLAB_ACCESS_TOKEN： パーソナルアクセストークンまたはデプロイトークンです。後述する手順でトークンを取得します。環境変数として指定してもらいます。
パーソナルアクセストークンの取得
インストール時に必要なトークンを取得してもらいます。
手順は公開時のトークン取得とほぼ同じですが、要求されるスコープがread_apiでも良くなります。
- パーソナルアクセストークンはGitLabのWebページから作成できます。
- 「設定」→「アクセストークン」からアクセストークン画面を開きます。
名前有効期限日(任意)を入力し、スコープはread_api（apiでも良い）をチェックします。
「Create personal access token」をクリックするとトークンが生成されます。
取得したトークンを
GITLAB_ACCESS_TOKEN環境変数にセットします。
パッケージをインストール
GITLAB_ACCESS_TOKEN環境変数にトークンをセットしてnpm installを実行します。
$ GITLAB_ACCESS_TOKEN=_nk4przrfWPLMCppDW9s npm i @scope/package-name
トークンの持ち方はもう少し考えたほうが良いですが、これでインストールできます。
まとめ
以上でGitLabプライベートプロジェクトのNPM公開手順になります。
これらの環境を整えてからライブラリのリリースとインストールがとても簡単になりました。
特にCIが強力で毎日リリースしても全然苦では無いのでとても便利になります。
社内で共有しているライブラリがあればぜひ活用してください。