semantic-releaseを使用して、npmパッケージをGitLabパッケージレジストリに公開する

プラン: Free、Premium、Ultimate
提供形態: GitLab.com、GitLab Self-Managed、GitLab Dedicated

このガイドでは、GitLabパッケージレジストリにnpmパッケージを自動的に公開する方法を、semantic-releaseを使用して示します。

完全なexample sourceを表示するか、フォークできます。

モジュールを初期化する

ターミナルを開き、プロジェクトのリポジトリに移動します。
npm initを実行します。モジュールをパッケージレジストリの命名規則に従って命名します。たとえば、プロジェクトのパスがgitlab-examples/semantic-release-npmの場合、モジュールに@gitlab-examples/semantic-release-npmという名前を付けます。

次のnpmパッケージをインストールします:

npm install semantic-release @semantic-release/git @semantic-release/gitlab @semantic-release/npm --save-dev

次のプロパティをモジュールのpackage.jsonに追加します:

{
  "scripts": {
    "semantic-release": "semantic-release"
  },
  "publishConfig": {
    "access": "public"
  },
  "files": [ <path(s) to files here> ]
}

filesキーを、公開されるモジュールに含めるすべてのファイルを選択するglobパターンで更新します。filesに関する詳細は、npmドキュメントにあります。
プロジェクトに.gitignoreファイルを追加して、node_modulesをコミットするのを避けます:
```
node_modules
```

パイプラインを設定する

次の内容を含む.gitlab-ci.ymlを作成します。

default:
  image: node:latest
  before_script:
    - npm ci --cache .npm --prefer-offline
    - |
      {
        echo "@${CI_PROJECT_ROOT_NAMESPACE}:registry=${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/npm/"
        echo "${CI_API_V4_URL#https?}/projects/${CI_PROJECT_ID}/packages/npm/:_authToken=\${CI_JOB_TOKEN}"
      } | tee -a .npmrc
  cache:
    key: ${CI_COMMIT_REF_SLUG}
    paths:
      - .npm/

workflow:
  rules:
    - if: $CI_COMMIT_BRANCH

variables:
  NPM_TOKEN: ${CI_JOB_TOKEN}

stages:
  - release

publish:
  stage: release
  script:
    - npm run semantic-release
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

この例では、単一のジョブであるpublishを使用してパイプラインを設定し、semantic-releaseを実行します。semantic-releaseライブラリはnpmパッケージの新しいバージョンを公開し、(必要に応じて)新しいGitLabリリースを作成します。

デフォルトのbefore_scriptは、publishジョブ中にパッケージレジストリへの認証に使用される一時的な.npmrcを生成します。

CI/CD変数を設定する

パッケージの公開の一部として、semantic-releaseはpackage.jsonのバージョン番号を増やします。semantic-releaseがこの変更をコミットしてGitLabにプッシュするには、パイプラインにGITLAB_TOKENという名前のカスタムCI/CD変数が必要です。この変数を作成するには:

左サイドバーを開きます。
設定 > アクセストークンを選択します。
プロジェクトで、新しいトークンを追加を選択します。
トークン名ボックスに、トークン名を入力します。
スコープを選択で、APIチェックボックスを選択します。
プロジェクトアクセストークンを作成を選択します。
トークンの値をコピーします。
左サイドバーで、設定 > CI/CDを選択します。
変数を展開します。
変数を追加を選択します。
表示レベルで、マスクするを選択します。
キーボックスに、GITLAB_TOKENと入力します。
値ボックスに、トークンの値を入力します。
変数を追加を選択します。

semantic-releaseを設定する

semantic-releaseは、プロジェクト内の.releaserc.jsonファイルから設定情報を取得します。リポジトリのルートに.releaserc.jsonを作成します:

{
  "branches": ["main"],
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/gitlab",
    "@semantic-release/npm",
    [
      "@semantic-release/git",
      {
        "assets": ["package.json"],
        "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
      }
    ]
  ]
}

以前のsemantic-releaseの設定例では、ブランチ名をプロジェクトのデフォルトのブランチに変更できます。

リリースの公開を開始する

次のようなコミットメッセージでコミットを作成して、パイプラインをテストします:

fix: testing patch releases

コミットをデフォルトのブランチにプッシュします。パイプラインは、プロジェクトのリリースページに新しいリリース (v1.0.0) を作成し、プロジェクトのパッケージレジストリページにパッケージの新しいバージョンを公開します。

マイナーリリースを作成するには、次のようなコミットメッセージを使用します:

feat: testing minor releases

または、破壊的な変更の場合は:

feat: testing major releases

BREAKING CHANGE: This is a breaking change.

コミットメッセージがリリースにマップされる方法の詳細については、semantic-releaseのドキュメントを参照してください。

プロジェクトでモジュールを使用する

公開されたモジュールを使用するには、そのモジュールに依存するプロジェクトに.npmrcファイルを追加します。たとえば、example projectのモジュールを使用するには:

@gitlab-examples:registry=https://gitlab.com/api/v4/packages/npm/

次に、モジュールをインストールします:

npm install --save @gitlab-examples/semantic-release-npm

トラブルシューティング

削除されたGitタグが再表示される

リポジトリから削除されたGitタグは、GitLab Runnerがリポジトリのキャッシュされたバージョンを使用している場合にsemantic-releaseによって再作成されることがあります。ジョブがタグをまだ持っているキャッシュされたリポジトリを持つRunner上で実行される場合、semantic-releaseはmainリポジトリにそのタグを再作成します。

この動作を回避するには、次のいずれかを実行できます:

RunnerをGIT_STRATEGY: cloneで設定します。
git fetch --prune-tagsコマンドをCI/CDスクリプトに含めます。