GitHub Action 是一套提供给 GitHub 仓库使用的 CI/CD 工具。它可以自动化、自定义和执行软件开发工作流程。本文将介绍如何利用 GitHub Action 自动化发布 npm 包版本和 GitHub release。
CHANGELOG
作为一个开源仓库,CHANGELOG
变更记录是必不可少的。有很多的工具可以生成 CHANGELOG.md
,这里我们使用@changesets/cli
。
安装
pnpm i @changesets/cli
使用
执行以下命令进行初始化,它会在你的项目根目录生成一个.changeset
文件夹,里面包括一个配置文件和 README。
pnpm exec changeset init
每次修改代码之后,运行以下命令:
pnpm exec changeset
这里会提示我们选择这次更改的类型。不了解的可以自行搜索 npm semver 版本号规范。
简单来说 patch
是小的 bug 修改,不影响之前功能的小 feature 功能增加可以选 minjor
,major
代表包含了 breaking change 的大版本号变动,比如 1.0.0 到 2.0.0。
输入本次修改的信息,一路回车就行。
这时候它会在.changeset
文件夹生成一个随机名字的 md 文件,包含你刚才提交的信息。
接下来生成版本号。
pnpm exec changeset version
这个命令会读取你刚才生成的 changeset 文件,写入 CHANGELOG.md
,并且把 package.json
中的版本号按照你选择的类型进行升级。
以上就是 changeset
的完整用法。
release.yml
接下来开始创建 GitHub Action 的自动化脚本。
在你的项目根目录创建一个.github
的文件夹,里面再创建一个workflows
的文件夹,创建一个release.yml
的文件。
文件内容如下,我来一一解读:
# 整个流程的名字
name: Release
# 触发时机,在 main 分支 push 操作触发
on:
push:
branches:
- main
# 默认shell
defaults:
run:
shell: bash
# 任务,定义个changelog 的任务
jobs:
changelog:
name: Changelog PR or Release
# 这里判断仓库owner是否是我自己,为了避免别人 fork 仓库触发,请自行修改
if: ${{ github.repository_owner == 'liruifengv' }}
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
# 设置 pnpm。指定版本7.0,不然会报错
- name: Setup PNPM
uses: pnpm/action-setup@v2.2.1
with:
version: ^7.0
# 设置 Node
- name: Setup Node
uses: actions/setup-node@v3
with:
node-version: 16
cache: 'pnpm'
# 安装依赖
- name: Install dependencies
run: pnpm install
# 打包
- name: Build Packages
run: pnpm run build
# 这一步是最重要的。使用changesets/action自动创建 PR 或者发布
- name: Create Release Pull Request or Publish
id: changesets
uses: changesets/action@v1
with:
# 执行更新版本和发布的命令
version: pnpm run version
publish: pnpm exec changeset publish
commit: '[ci] release'
title: '[ci] release'
env:
# 这里需要几个 Token 变量
# GITHUB_TOKEN 是 CI 里自带的默认 token
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
# NPM_TOKEN 需要稍后在 npm 网站生成。
NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
为了方便,我们在项目的package.json
中添加几个脚本:
// package.json
{
"scripts": {
"changeset": "changeset",
"version": "changeset version && pnpm install"
}
}
设置 TOKEN
把以上文件提交之后,我们来设置一下 token。
登录你的 npm 账号,点击头像选择 Access tokens。
点击 Generate New Token。可以选择一键生成也可以更细粒度的控制权限。
生成之后记得复制,关闭页面之后就看不到了。
回到 GitHub,你的仓库,点击 Settings,选择 Secrets and variables。创建一个 NPM_TOKEN。这样 GitHub Action 中就能取到它了。
完整工作流程
本地提交修改
修改你要修改的代码。
运行生成 changeset
文件
pnpm exec changeset
生成 changeset
文件之后,注意不用执行再 version
命令了。
保存,把 changeset
文件和我们的代码修改一并提交。
发起 PR
这里我安装了changeset-bot。它可以自动探测 PR 中是否包含了 changeset
文件并进行评论。你可以点击链接安装它。
作为仓库 owner 你也可以直接 push 到 main 分支,但更多的开源贡献者喜欢用 PR 的方式。
CI 发起 release PR
PR 合并进 main 分支之后,就触发了我们前面设置的 action。
点击 Actions 查看,我们刚才的提交,触发了一个叫做 Release 的工作流。你可以点开查看,它会在 CI 环境里执行我们预设好的脚本。
我们的脚本就是,如果检测到提交携带有 changeset
信息,就会自动发起一个叫做 [ci] release
的 PR。这个 PR 中,CI 自动帮我们做好了 CHANGELOG
的生成,版本号的升级。
当你点击 merge,合并到 main 分支之后,它就会自动地发布版本,同时发布到 npm 仓库和 GitHub release。
未合并期间,所有携带有 changeset
的提交都会更新这个 PR。
发布
点击 merge 发布!恭喜你完成了整个流程。
过一会就能看到 GitHub release 和 npm 包都发布成功了。
总结
可能有人说,好像也是半自动化哦。
其实这是一套开源协作流程。
- 仓库的贡献者,修改代码,生成
changeset
。 - CI 自动归结,生成
CHANGELOG
并 PR。 - 仓库的维护者,点击 merge 自动发布。
你还在手动改版本发布吗?你的开源项目还缺少完善的协作流程吗?来试一下这套流程吧。
结语
GitHub Action 还可以做很多事,比如 lint、format 代码;自动化部署等等。你可以在我的 GitHub 找到更多例子。