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

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

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

完全なサンプルソースを表示またはフォークすることもできます。

モジュールを初期化します

ターミナルを開き、プロジェクトのリポジトリに移動します。
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キーを更新します。filesの詳細については、NPMドキュメントをご覧ください。
node_modulesのコミットを回避するために、プロジェクトに.gitignoreファイルを追加します。
```
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

この例では、semantic-releaseを実行する単一のジョブpublishを使用してパイプラインを構成します。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-releasesのドキュメントをご覧ください。

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

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

@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のリポジトリにタグを再作成します。

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

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