Github自动发版机器人semantic-release配置教程

发表于 分类于 阅读次数：

semantic-release 配合GitHub Actions提交代码后自动发版到NPM，自动修改 package.json 和 CHANGELOG。

为什么需要自动化

在 Github 上维护开源项目时，如果每次有代码提交需要发版时，都需要做很多工作，例如：

  • 构建产物
  • 生成一个新的版本
  • 发布版本到 NPM
  • 修改 package.json
  • 修改 CHANGELOG
  • 打 TAG
  • 生成一个 Release
  • 提交代码到 Github …

其中很多步骤都非必须，但是想要维护好一个项目，又是必须做的。全部人工不仅繁琐而且容易遗漏步骤。

同时，在本地发版也容易因为环境问题造成不同版本间非代码因素的不一致。

如果是一个多人维护的项目，就更糟糕了，可能两个人同时想要提交一个新的版本，也可能某个人提交版本之后忘记把版本号修改提交在 package.json 中。

总之，自动化势在必行。（且成本很低）

semantic-release

这里推荐 semantic-release 这个库，配置好以后，每次提交固定格式的 commit，他就会帮我们自动完成上述所有工作。

01.png

semantic-release 支持很多持续集成工具。之前比较常用的是 Travis CI，但在 Github 提供了 GitHub Actions 以后，基本没有理由还用之前的持续集成工具了。

接下来讲一下如何配置这个库，我们需要执行以下步骤：

上面这些步骤，自己搞比较麻烦（其实也没有），semantic-release做了一个 CLI 工具，可以使用命令行的方式配置这些内容。不足的是你需要在命令行中填写 NPM 帐号密码，Github token 等敏感内容，可能有的同学会有顾虑。其实不用 CLI，自己手动配置这些信息，semantic-release 在流水线中还是会读取到，毕竟发版等内容密钥是必须的。

当然，如果 CLI 全都搞定了，这篇文章就没有存在的价值了。

在使用 CLI 工具的时候，发现如果使用 GitHub Actions 作为持续集成工具，做不到配置后立刻使用。CLI 工具只帮我们配置了 Github 和 NPM 的权限。其他三个步骤还是需要我们自己来完成的。

完成 “配置了 Github 和 NPM 的权限” 也有 BUG，我提交了一个修复 CR：https://github.com/semantic-release/cli/pull/358 ，不知道会不会给合入。 update: 已经合入了，可以正常使用了。

在项目中安装 semantic-release

安装 semantic-release 没有太多可说的，直接 npm i 就好了。

这里推荐再装两个插件：

@semantic-release/changelog，这个插件可以自动生成 CHANGELOG 文件。 @semantic-release/git，这个插件可以在发版后修改 package.json 中的版本，并提交到 Github 上。

1
npm i -D semantic-release @semantic-release/changelog @semantic-release/git

配置持续集成

之后需要配置 GitHub Actions, 在我们的项目目录下创建 .github/workflows/release.yml 文件。

内容：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
name: Release
on:
  push:
    branches:
      - master
jobs:
  release:
    name: Release
    runs-on: ubuntu-18.04
    steps:
      - name: Checkout
        uses: actions/checkout@v2
        with:
          fetch-depth: 0
      - name: Setup Node.js
        uses: actions/setup-node@v1
        with:
          node-version: 12
      - name: Install dependencies
        run: npm ci
      - name: Release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
        run: npx semantic-release

内容比较好理解，首先声明环境是在 ubuntu-18.04 下，之后拉取代码，使用 Node.js 12，安装项目依赖，最后执行 semantic-release。

具体工作都是 semantic-release 来操作的。

配置 semantic-release 选项和插件

选项有很多，不过我们这里其实并用不到，有需要的同学可以自行查看文档。

这里我们只需要配置好相应的 plugins：

在项目根目录下创建 .releaserc 文件，内容：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
    "branches": "master",
    "plugins": [
        "@semantic-release/commit-analyzer",
        "@semantic-release/release-notes-generator",
        "@semantic-release/changelog",
        "@semantic-release/npm",
        [
            "@semantic-release/git",
            {
                "assets": [
                    "package.json",
                    "CHANGELOG.md"
                ],
                "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
            }
        ],
        "@semantic-release/github"
    ]
}

其中的一些插件在安装semantic-release的时候其实已经安装好了，不需要我们主动安装。

尝试执行

接下来可以试着提交 commit，push 到 github 中，就可以在 GitHub Actions 中查看进度了。

这里可以看这个项目作为一个例子：searchfe/san-ssr-plugin

02.png

配置虽然有些繁琐（后续 CLI 完善以后可能就简单很多了），但是一劳永逸。

发完版以后 NPM 会邮件通知，提交版本发布 Release 以后 Github 也会邮件通知。

03.png

以后只需要提交代码，就什么都不用管了，坐等收邮件的感觉实在是很惬意。