blog.dopana

返回

你是否曾经为了测试一个不按预期工作的workflow而不得不将代码推送到GitHub?或者每次小改动后都要等待几分钟让CI重新运行?🤔

在这篇文章中,我将介绍act - 一个工具,让你可以在本地机器上直接运行GitHub Actions,而不是等待GitHub远程处理它们。

为什么要在本地运行GitHub Actions?#

想象一下你正在修复CI/CD workflow。当前的过程通常是:

  1. 编辑workflow文件
  2. 提交并推送代码
  3. 等待GitHub Actions运行(可能需要几分钟)
  4. 看到错误发生
  5. 回到步骤1

这就像每次想要修复文档中的一句话都要给同事发邮件,而不是直接编辑它。非常耗时且低效。

act通过以下方式解决这个问题:

  • 快速反馈 - 在你的机器上立即运行workflow,无需推送
  • 本地任务运行器 - 用GitHub Actions替换Makefile,利用现有的workflow结构
  • 减少依赖 - 当actions和镜像被缓存时,无需互联网连接

Act如何工作?#

将GitHub Actions想象成一个工厂。当你推送代码时,GitHub会:

  1. 从.github/workflows/读取workflow文件
  2. 确定需要运行哪些actions
  3. 相应地拉取或构建Docker镜像
  4. 在容器中运行每个action
  5. 配置环境变量和文件系统以匹配GitHub

act在你的机器上而不是GitHub的服务器上做完全相同的事情:

你运行act读取workflow文件确定要运行的actionsDocker API拉取/构建镜像运行容器配置环境和文件系统执行workflow

安装Act#

前提条件#

act需要Docker在容器中运行workflow。如果不需要容器隔离(例如,在你的机器上直接运行windows/macOS作业),可以跳过Docker。

  • macOS: 安装Docker Desktop for Mac
  • Windows: 安装Docker Desktop for Windows
  • Linux: 安装Docker Engine

快速安装#

方法1: Homebrew(macOS & Linux)

Homebrew
brew install act
bash

方法2: Bash脚本(所有平台)

curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash
bash

方法3: GitHub CLI扩展

gh extension install https://github.com/nektos/gh-act
bash

方法4: 直接下载

从GitHub releases ↗下载并添加到PATH。

[!TIP] 验证安装:

act --version
bash

Act基本使用#

运行默认workflow#

默认情况下,act使用事件push运行所有workflow:

运行所有workflow
act
bash

使用特定事件运行#

模拟pull_request事件
act pull_request

act schedule

act workflow_dispatch
bash

列出workflow#

列出pull_request的workflow
act -l pull_request
bash

运行特定workflow#

act -W .github/workflows/checks.yml
bash

运行特定作业#

只运行名为test的作业
act -j test
bash

配置密钥和变量#

使用密钥#

GitHub在服务器上运行workflow时自动提供GITHUB_TOKEN。在本地运行时,你需要提供它:

act -s MY_SECRET=my-value

# 方法2: 使用环境变量(推荐)
act -s MY_SECRET

# 方法3: 从GitHub CLI自动获取令牌
act -s GITHUB_TOKEN="$(gh auth token)"

# 方法4: 从文件加载
act --secret-file .secrets
bash

[!WARNING] 在终端中输入敏感数据时,可能会保存到shell历史记录中。出于安全考虑,使用方法2或3。

使用仓库变量#

传递变量
act --var VARIABLE=some-value

act --var-file .env
bash

.env文件格式#

格式匹配Ruby dotenv:

MY_ENV='value'
PRIV_KEY="---...\nrandom text\n...---"
JSON="{\n\"name\": \"value\"\n}"
SOME_VAR=SOME_VALUE
bash

本地运行时跳过作业和步骤#

跳过作业#

使用自定义事件属性:

workflow.yml
on: push
jobs:
  deploy:
    if: ${{ !github.event.act }} # 本地运行时跳过
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploy step"
yaml

创建event.json:

event.json
{
  "act": true
}
json

运行:

act -e event.json
bash

跳过步骤#

act提供环境变量ACT:

workflow.yml
- name: Notify Slack
  if: ${{ !env.ACT }} # 本地运行时跳过
  run: |
    curl -X POST $SLACK_WEBHOOK
yaml

矩阵和高级功能#

运行矩阵子集#

如果workflow有多个值的矩阵:

workflow.yml
strategy:
  matrix:
    node: [14, 16, 18]
    os: [ubuntu-latest, macos-latest]
yaml

只运行node 18:

act push --matrix node:18
bash

只运行node 18和ubuntu:

act push --matrix node:18 --matrix os:ubuntu-latest
bash

Action离线模式#

缓存时加速并离线运行:

启用离线模式
act --action-offline-mode
bash

好处:

  • 不拉取现有镜像
  • 缓存时可以离线工作
  • 避免GitHub速率限制
  • 连接不佳时节省时间

.actrc配置文件#

为了避免每次都输入标志,创建.actrc:

.actrc
--container-architecture=linux/amd64
--action-offline-mode
-e event.json
bash

问题和限制#

Apple Silicon(M1/M2/M3)#

如果使用Apple M系列芯片,可能会遇到架构问题:

act --container-architecture linux/amd64
bash

运行器镜像#

act使用与GitHub运行器不同的Docker镜像。某些工具可能无法工作:

  • ubuntu-latest → node:16-buster-slim(轻量)或catthehacker/ubuntu:act-latest(中等)
  • 对于与GitHub完全匹配的环境,使用nektos/act-environments-ubuntu:18.04

不支持的功能#

某些GitHub Actions功能不受支持:

  • Docker上下文
  • 某些复杂的矩阵配置
  • 某些GitHub Actions特定功能

实际示例#

简单workflow#

.github/workflows/test.yml
name: Test
on: push
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '18'
      - name: Install
        run: npm install
      - name: Test
        run: npm test
yaml

本地运行:

act
bash

使用密钥的workflow#

.github/workflows/deploy.yml
name: Deploy
on: push
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to production
        run: |
          curl -X POST ${{ secrets.DEPLOY_URL }}
yaml

本地运行:

act -s DEPLOY_URL
bash

与GitHub Actions的比较#

功能GitHub Actionsact(本地)
反馈速度慢(必须推送)快(立即运行)
资源成本GitHub账户配额你的本地机器
环境精确几乎精确
离线不可可以(离线模式)
矩阵测试耗时快(运行子集)
密钥在GitHub上管理手动传递

结论#

act对于任何使用GitHub Actions的开发者来说都是无价的工具。它有助于:

  • 加速开发和workflow调试
  • 减少对GitHub基础设施的依赖
  • 推送前测试workflow
  • 将GitHub Actions用作本地任务运行器

[!TIP] 最佳实践:特别是在修改复杂的workflow结构时,推送前始终使用act测试workflow。

参考文献#