act

act：在本地跑通 GitHub Actions

act 是一个用 Go 编写的命令行工具，目标是让你在本地执行 .github/workflows/ 中定义的 GitHub Actions 工作流。它的口号是「Think globally, act locally」——把 CI 从云端搬到本机。

为什么需要它

修改 workflow 文件时，通常只能提交并推送后等待 GitHub 返回结果，反馈周期长。act 提供两个核心价值：

• 快速反馈：在本地直接运行 workflow，环境变量与文件系统尽量对齐 GitHub 托管 Runner。
• 本地任务运行器：把 GitHub Actions 当作 Makefile 的替代品，复用已有 workflow 完成本地任务编排。

工作原理

1. 读取 .github/workflows/ 下的工作流定义；
2. 解析需要执行的 action 及其依赖关系，确定执行顺序；
3. 通过 Docker API 拉取或构建所需镜像；
4. 为每个 action 启动容器执行，并注入与 GitHub 一致的环境变量。

因此 Docker 是必需的前置条件。

使用方式概览

安装后，在仓库根目录直接运行即可触发默认事件：

# 运行默认工作流
act

# 指定触发事件
act push

# 列出可用工作流
act -l

具体参数与配置项请参考官方用户指南（nektosact.com）。

从源码构建

项目使用 Go 开发，仓库提供 Makefile：

make test       # 需要 Docker 的单元测试
make test-fast  # 不依赖 Docker 的快速测试
make install    # 构建并安装

生态与扩展

社区提供了 VS Code 扩展「GitHub Local Actions」，可在编辑器内直接调用 act 运行和测试工作流，无需切换终端。

适用建议

act 适合需要频繁调整 CI 配置的开发者与团队，也适合把 GitHub Actions 用作本地自动化脚本的场景。需要注意它与真实 Runner 仍有差异，涉及密钥、缓存或特殊系统能力的步骤建议以线上结果为准。