Help us learn about your current experience with the documentation. Take the survey.

使用 semantic-release 发布 npm 包到 GitLab 包注册表

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

本指南演示了如何使用 semantic-release 自动将 npm 包发布到 GitLab 包注册表。

您也可以查看或分叉完整的 示例源代码。

初始化模块

  1. 打开终端并进入项目的仓库。

  2. 运行 npm init。根据 包注册表的命名约定 为模块命名。例如，如果项目路径是 gitlab-examples/semantic-release-npm，则将模块命名为 @gitlab-examples/semantic-release-npm。

  3. 安装以下 npm 包：

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

  4. 将以下属性添加到模块的 package.json：

    {
  "scripts": {
    "semantic-release": "semantic-release"
  },
  "publishConfig": {
    "access": "public"
  },
  "files": [ <此处填写文件路径> ]
}

  5. 使用 glob 模式更新 files 键，选择应包含在已发布模块中的所有文件。有关 files 的更多信息，请参阅 npm 文档。

  6. 在项目中添加 .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 会生成一个临时的 .npmrc 文件，用于在 publish 作业期间向包注册表进行身份验证。

设置 CI/CD 变量

作为发布包的一部分，semantic-release 会增加 package.json 中的版本号。为了使 semantic-release 能够提交此更改并将其推回 GitLab，流水线需要一个名为 GITLAB_TOKEN 的自定义 CI/CD 变量。要创建此变量：

  1. 打开左侧边栏。
  2. 选择 Settings > Access tokens。
  3. 在您的项目中，选择 Add new token。
  4. 在 Token name 框中，输入令牌名称。
  5. 在 Select scopes 下，选择 api 复选框。
  6. 选择 Create project access token。
  7. 复制令牌值。
  8. 在左侧边栏，选择 Settings > CI/CD。
  9. 展开 Variables。
  10. 选择 Add variable。
  11. 在 Visibility 下，选择 Masked。
  12. 在 Key 框中，输入 GITLAB_TOKEN。
  13. 在 Value 框中，输入令牌值。
  14. 选择 Add variable。

配置 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: 测试补丁版本发布

将提交推送到默认分支。流水线应该在项目的 Releases 页面上创建一个新版本（v1.0.0），并在项目的 Package registry 页面上发布一个新版本的包。

要创建次要版本，使用如下提交消息：

feat: 测试次要版本发布

或者，对于重大变更：

feat: 测试主要版本发布

BREAKING CHANGE: 这是一个重大变更。

有关提交消息如何映射到版本的更多信息，请参阅 semantic-release 的文档。

在项目中使用模块

要使用已发布的模块，请在依赖该模块的项目中添加一个 .npmrc 文件。例如，要使用 示例项目 的模块：

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

然后安装模块：

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

故障排除

已删除的 Git 标签重新出现

从仓库中删除的 Git 标签 有时会被 semantic-release 重新创建，当 GitLab runner 使用缓存的仓库版本时。如果作业在仍带有该标签的缓存仓库版本的 runner 上运行，semantic-release 会在主仓库中重新创建该标签。

为避免此行为，您可以：