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包含了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。

参考链接：

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

本文链接：