act体验:一个GitHub Action本地调试工具

GitHub Actions是GitHub推出的一款持续集成服务,与GitHub工作流衔接良好,非常方便。但是,要运行workflow只能通过触发对应的事件(如push、创建release等),给调试带来困难。而act提供了一个GitHub Action本地运行环境,让我们可以在本地方便地调试workflow。

0x00 引入

根据介绍,act的设计目的有两个:

  1. 模拟GitHub Action的运行环境,让workflow调试摆脱每次修改都需要commit/push到GitHub的繁琐流程
  2. 替代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包含了yarnpnpm等工具,只需要将默认的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的调试,毕竟保存->actgit commit->git push->去页面点进action->点开日志再调试便利太多了。不过,首次运行可能会有那么点痛苦,毕竟不是真实环境,甚至有些功能还没有得到支持,比如services


参考链接:

  1. nektos/act: Run your GitHub Actions locally
  2. Can't use yarn · Issue #280 · nektos/act
  3. ACTIONS_RUNTIME_URL, ACTIONS_RUNTIME_TOKEN and ACTIONS_CACHE_URL environment variables are missing. · Issue #329 · nektos/act

本文链接:

https://www.direcore.xyz/archives/39/
1 + 5 =
快来做第一个评论的人吧~