GitHub Actions是GitHub推出的一款持续集成服务,与GitHub工作流衔接良好,非常方便。但是,要运行workflow只能通过触发对应的事件(如push
、创建release等),给调试带来困难。而act
提供了一个GitHub Action本地运行环境,让我们可以在本地方便地调试workflow。
0x00 引入
根据介绍,act
的设计目的有两个:
- 模拟GitHub Action的运行环境,让workflow调试摆脱每次修改都需要commit/push到GitHub的繁琐流程
- 替代
makefile
第一个正是我需要的。我最近正在给mui-m3-theme调试下面这个通过yarn
进行构建和发布的workflow:
# npm-publish.yml
name: Node.js Package
on:
release:
types: [created]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: 16
- run: yarn install --immutable
- run: yarn run rollup
- uses: actions/upload-artifact@v3
with:
name: build-result
path: build
publish-npm:
needs: build
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: 16
registry-url: https://registry.npmjs.org/
- uses: actions/download-artifact@v3
with:
name: build-result
path: build
- run: yarn publish --access=public
env:
NODE_AUTH_TOKEN: ${{secrets.npm_token}}
这个workflow有两个job。第一个job用yarn
初始化环境并进行构建,然后将构建产物提交到artifact
。第二个job从artifact
获取构建产物,从secrets中获取NPM_TOKEN
并publish。
0x01 安装
首先,act
是基于Docker的,需要先安装Docker。如何安装Docker在这里不再赘述。
再就是act
本身的安装。作为一个macOS用户,我选择通过Homebrew进行安装:
brew install act
如果你是其它操作系统的用户,可以看看他们的release页面。
安装完执行一下act --version
,如果看到版本号就是成功了。
0x02 基本操作
先进入我们的项目目录。使用act -l
命令就可以看到所有的任务:
Stage Job ID Job name Workflow name Workflow file Events
0 build build Node.js Package npm-publish.yml release
1 publish-npm publish-npm Node.js Package npm-publish.yml release
使用act release -l
可以看到所有release事件会触发的任务,使用-j build
参数则会看到build
这个任务。
使用act
命令可以模拟时间的触发,如果不指定触发哪个事件则会会触发默认的push
事件(但是我这里没有push
事件相关的任务,执行后触发的是release
事件)。act -j
则可运行指定的任务。在第一次运行act
时会询问要使用micro、medium还是large镜像。medium镜像是一个折衷的选择,拥有相对合理的大小(数百MB)和相对合理的兼容性。以下的内容也是基于medium这一档的如果你的硬盘很大,可以选择20GB的large镜像获得最完整的体验
0x03 配置
对于刚才提到的这个publish工作流来说,现在直接运行会出现一些问题。下面来一一解决这些问题。
secrets
对于真实的GitHub Action来说,我们需要把NPM_TOKEN
存在GitHub仓库的secrets里面。而对于act
来说,我们需要把secret通过命令行参数的形式传进去(注意:你的token会被记录在shell历史记录里):
act -s NPM_TOKEN=my_npm_token
或者把secret存在一个secret
文件里,再用--secret-file secret
去指定。你可以把它理解成.env
。
artifact
act
对artifact提供了原生支持,但是需要通过一个命令行参数手动开启,就像这样:
act --artifact-server-path /tmp/artifacts
其中,/tmp/artifacts
是用于存储artifact内容的临时路径。
yarn
我们刚才选择的medium镜像实际上是不包含yarn
的,只能使用npm
。不过,除了使用large镜像和每次运行之前都用npm安装yarn之外还有另外一个方案。这里提供了一些替换用的镜像,其中/linux/ubuntu/js
包含了yarn
、pnpm
等工具,只需要将默认的ubuntu-latest
指定为这个镜像即可:
act -P ubuntu-latest=ghcr.io/catthehacker/ubuntu:js-latest
如果每次都使用这个镜像,则可以在~/.actrc
中进行指定。
0x04 运行
在运行之前,我们可以用act -n
进行一次dry run来确定要运行的任务。执行act
,然后耐心等待就可以啦。日志输出和GitHub Action的debug模式是相同的,如果你不想要输出也可以用-q
开关。
顺带一提,因为我使用的是M1芯片,每次运行的时候都会提示如果遇到问题,可以使用--container-architecture linux/amd64
来调用amd64版本的镜像。这个我就不测试了,估计会很慢)
0x05 使用体验
act
极大地便利了workflow的调试,毕竟保存->act
比git commit
->git push
->去页面点进action->点开日志再调试便利太多了。不过,首次运行可能会有那么点痛苦,毕竟不是真实环境,甚至有些功能还没有得到支持,比如services
。
参考链接: