{{< details >}}

  • Tier: 基础版, 专业版, 旗舰版
  • Offering: JihuLab.com, 私有化部署

{{< /details >}}

这篇指南演示了如何使用 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": [ <path(s) to files here> ]
}

  5. 使用 glob 模式更新 files 键，以选择所有应包含在发布模块中的文件。

  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. 选择 设置 > 访问令牌。
  3. 在你的项目中，选择 添加新令牌。
  4. 在 令牌名称 框中输入令牌名称。
  5. 在 选择范围 下，选择 api 复选框。
  6. 选择 创建项目访问令牌。
  7. 复制令牌值。
  8. 在左侧边栏中，选择 设置 > CI/CD。
  9. 展开 变量。
  10. 选择 添加变量。
  11. 在 可见性 下，选择 Masked。
  12. 在 Key 框中输入 GITLAB_TOKEN。
  13. 在 Value 框中输入令牌值。
  14. 选择 添加变量。

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

在项目中使用模块

要使用发布的模块，请将一个 .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 会在主仓库中重新创建标签。

为了避免这种行为，你可以：