act

在本地运行 GitHub Actions

补充说明

act 读取 .github/workflows，用 Docker 在本地模拟 GitHub Actions Runner。它适合快速验证工作流，但不能完全复现 GitHub 托管 Runner 的环境和所有 action。

常用示例

act -l
act push
act pull_request
act -j test
act -W .github/workflows/ci.yml
act -P ubuntu-latest=catthehacker/ubuntu:act-latest
act -s GITHUB_TOKEN="$GITHUB_TOKEN"
act --env-file .env
act --reuse
act --container-architecture linux/amd64

易错点与排错

• 需要 Docker；没有 Docker 或无法拉取镜像时直接失败。
• 本地镜像和 GitHub 托管 Runner 的系统环境不同；依赖预装软件的工作流可能失败。
• secrets 不会自动读取；用 -s 或 --env-file 显式传入，注意不要提交。
• 事件负载和 github.event 结构与真实事件有差异；依赖 payload 的逻辑要回归验证。
• 某些官方 action 和服务容器在本地不可用；以 GitHub 上的结果为准。
• Apple Silicon 上跑 amd64 镜像需要模拟，速度和兼容性都会受影响。
• --reuse 会复用容器，可能残留上一次的文件和进程；排查脏状态时去掉它。
• act 版本落后会不识别新语法；升级后再判断是不是工作流本身的问题。

相关命令

• github-actions — 工作流配置
• gh — 触发和查看真实运行
• docker — 本地容器运行时