玩转 GitHub Actions,简化 npm 发布流程

阅读数:1811 2019 年 9 月 27 日 18:52

玩转GitHub Actions,简化npm发布流程

Github 最近添加了一项名为 Github Actions 的新功能,为我们带来了一套强大的工作流系统,可以处理各种各样的任务。我们在发布 Node.js 包时可以使用 Actions 自动运行测试,然后自动将程序包发布到 npm 上。下面就来看看如何使用 Github Actions 来为我们的生活带来便利。

目前 Github Actions 尚处于公开测试阶段,并且仅向注册者开放。你可以点击这里注册并阅读文档。

Github Actions 的基本理念是在事件上触发动作。每个 Action 都是使用 YAML 文件编写的步骤集合,内容可以非常复杂。本文的示例中我们将创建一个由 push 事件触发的 Action,每当将新的提交推送到存储库时创建一个 Action。这个脚本将运行我们的单元测试,然后尝试运行 npm publish。

在帐户中启用 Actions 功能后,你将在每个存储库中找到一个 Actions 标签。

玩转GitHub Actions,简化npm发布流程

可用的文档有很多,其中的内容将来可能用得上。不过这里我们就直接开工,先来创建一个工作流。预设工作流列表里有一个是适用 Node.js 的,点击它后就有了一个起点。

在本教程中,我使用了自己做的一个名为 Globfs 的包。你可以好好研究一下这个包,更全面地了解我的工作。

我做了很多修改,所以不用管原生提供的 Actions 脚本预设,看下面就行:

复制代码
name: Build and test Globfs
on: [push]
jobs:
build:
runs-on: ubuntu-latest
strategy:
matrix:
node-version: [12.x]
steps:
- uses: actions/checkout@v1
- name: Use Node.js ${{ matrix.node-version }}
uses: actions/setup-node@v1
with:
node-version: ${{ matrix.node-version }}
- name: npm install and npm test
run: |
npm run setup-test
npm run test
{1} - name: npm publish
run: |
npm config set //registry.npmjs.org/:_authToken=$NODE_AUTH_TOKEN
npm run trypublish
{1} env:
CI: true
NODE_AUTH_TOKEN: ${{ secrets.NPM_AUTH_TOKEN }}

当你创建这个脚本时,Github 将自动将其添加到你的存储库中,路径为.github/workflows/workflow-name.yml。我这里把它命名为 push.yml,因为它处理的是 push 事件。

探索 push.yml Action 脚本

这里的 name 字段只是给出了别人看得懂的名称,因此请随意填写自己喜欢的名字。而 on 字段要声明将在其上触发的事件,本例中 Action 在 push 事件上触发。

事件触发时将执行 jobs 字段。这里的 job 是在一个名为 ubuntu-latest 的 Docker 容器上运行的,完美适应我们的需求。

下面的 steps 字段是已执行步骤的列表。第一步 actions/checkout@v1 只是签出工作区。

顺便提一嘴,Github Actions 允许我们复用现有的 Actions。本例中我们将复用 Github 工作区中的 action/checkout 中定义的 Action,你会发现它签出了 Git 存储库。

下一步将设置 Node.js。使用 strategy/matrix 字段,我们可以设置要在其上运行 Action 的一系列 Node.js 版本。本例中我们只想在 Node.js 12 上运行,因为这是这个包支持的版本。运行 actions/setup-node 会设置对应的 Node.js 运行时。

下一步是 npm install 和 npm test,用于测试软件包。为了支持这里的工作,我在顶级 package.json 中添加了以下脚本:

复制代码
"scripts": {
"setup-test": "cd test && npm run setup",
"test": "cd test && npm run test"
}

每一步只是进入 test 目录,并运行那里对应的脚本。在 test 目录中我加了这个 package.json:

复制代码
{
"name": "globfs-test",
"version": "1.0.0",
"description": "Test suite for globfs",
"main": "index.js",
"scripts": {
"test": "mocha ./index",
"setup": "npm install && cd .. && npm install"
},
"author": "",
"license": "ISC",
"dependencies": {
"chai": "^4.1.2",
"mocha": "^5.2.0"
}
}

显然 test 脚本需要 index.js 中的测试套件。我使用 Mocha 和 Chai 断言库创建了一套,你需要的话可以在 Globfs 存储库中查阅。重要的是让 test 脚本可靠地执行测试套件,并且如果测试失败,它应该能可靠地显示错误状态。

如果测试失败,则 Action 脚本也将失败,Github 将通过电子邮件将错误日志发送给我们。如果测试脚本成功完成就一切顺利,Action 脚本将继续到下一个阶段。

Action 脚本的最后一步,即 npm publish,就是要发布我们的程序包。从理论上讲这只是运行一下 npm publish 而已,但是也有一些需要注意的事项。例如,如果你在已经发布的软件包目录上运行 npm publish,则 npm 服务器将抛出一个错误,告诉你无法在现有软件包上发布新包。

我的策略是如果测试成功则始终运行 npm publish。如果 package.json 中的版本字符串已更改,则一切正常,npm publish 会顺利将包推送到存储库。如果版本号未更改则将引发错误,任务应该会失败。但是由于我们不在乎 npm publish 命令是否成功执行,因此可以使用远古时代的一种奇怪的 shell 脚本技巧来避免失败。

我在顶级 package.json 中添加了以下脚本:

复制代码
"scripts": {
...
"trypublish": "npm publish || true"
},

使用 trypublish 时我们尝试运行 npm publish,然后如果失败就使用||true 跳过错误。看看这 shell 脚本技巧多厉害,这可是上世纪 70 年代流传下来的出色发明。

但仔细看看 push.yml 中的 npm publish 阶段,还有一些内容涉及到了 npm config 命令,这又是什么意思呢?

为了发布到 npm,我们需要一个授权令牌。要使它正常工作需要走过一段漫长的旅程,希望我能帮你省一些麻烦。

设置用于身份验证的 npm 令牌

设置用于身份验证的 npm 令牌,以从 Github Actions 流程脚本发布到 npm。假设你要在 npm publish 时进行身份验证,我们只需将 npm 令牌放在环境变量中一切就能照常运行了。根据 npm 博客 的说法,验证 npm 的规范方法是将下面这一行添加到~/.npmrc 中。

复制代码
//registry.npmjs.org/:_authToken=00000000-0000 -0000 -0000 -000000000000

但这在上面的 Action 脚本中很不方便。博客文章说,我们可以这样做:

复制代码
$ export NPM_TOKEN="00000000-0000-0000-0000-000000000000"

但是我发现没有有效的环境变量。在 action/setup-node 操作的文档中的这种写法也没用:

复制代码
- run: npm publish
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_AUTH_TOKEN }}

我花了几个小时寻求帮助,期间我发现也有不少人在研究这个问题上浪费了很多时间。但是看过足够多的资料后,我开发了一个可行的解决方案。

让我们一次创建一个步骤,从创建一个 npm 令牌开始。

玩转GitHub Actions,简化npm发布流程

登录 npmjs.com 后,你会在帐户菜单中找到这个选项。这将带你到一个页面,你可以在其中创建(和撤消)令牌。

只需单击创建新令牌(Create New Token)按钮。它会问几个问题,然后带你到显示新令牌的页面。确保将此令牌复制到安全的地方,因为到宇宙终结为止,你只有机会见到它这一次了。

玩转GitHub Actions,简化npm发布流程

下一步是转到 Github 存储库的设置(Settings)选项卡,并添加包含你已获得的令牌的密钥。一旦创建完成后,你将永远无法使用 Github 检查此密钥的内容。

然后在 Github Actions 脚本中,我们用以下方式访问此密钥,将其添加到环境中:

复制代码
env:
NPM_TOKEN: ${{ secrets.NPM_AUTH_TOKEN }}

但这还不够,和有关身份验证令牌的 npm 文档 说的不一样。无论我使用什么环境变量,npm publish 都无法识别该令牌。只有添加下面这行命令后它才起作用:

复制代码
npm config set //registry.npmjs.org/:_authToken=$NPM_TOKEN

这个配置必须同样添加到.npmrc 文件中。该命令在 Github 处理该作业的 Docker 容器中运行。

完成此操作后,npm publish 命令将按预期正常工作。

小结

Github Actions 还在发展初期。Github Actions 的宣传很美好,但是实际的工作做起来要麻烦的多。其实有些磕磕绊绊是可以改进的,这样能省掉很多麻烦。

这种自动化流程能帮助开发人员优雅地工作。要是测试 Node.js 程序包并将其发布到 npm 存储库的过程都没法自动,你的生活得有多悲催。你需要针对每个发行版在终端中键入所需的命令。如果你忘记了命令或忘了参数怎么办?如果你忘记发布新版本该怎么办?可能会发生各种各样的错误。自动化所有这些流程无疑要可靠得多,这样你就可以重复执行流程了。

可以肯定的是——过去,Gitlab 在这一方面一直比 Github 占优。因为 Gitlab 长期以来一直拥有 CI/CD 子系统。使用该系统,你可以将一个 YAML 文件添加到描述 CI/CD 工作流程的存储库中,然后就获得了自动化便利。如今 Github Actions 功能更加灵活,Gitlab 需要好好赶上来了。

原文链接
https://itnext.io/simplify-your-npm-publish-workflow-using-github-actions-691249bc7e59

评论

发布