act

act 读取 .github/workflows/，在本地执行工作流，常用 Docker 容器承载 Linux job。它适合调试脚本和依赖安装问题，不能代替 GitHub 上的权限、事件和运行环境验证。

安装与运行条件

Windows 可使用 scoop install act 或 winget install nektos.act，macOS 可用 brew install act。包名与版本以所用包源为准。

通常的容器执行需要可用 Docker 服务与匹配的 runner 镜像。列出任务与 dry run 不等于执行容器；act 也有直接在宿主运行的模式，因此“任何 act 命令都必须先启动 Docker”并不准确。选择宿主模式时，工作流命令会直接影响本地环境。

常用命令

在目标仓库中执行：

act -l
act -n
act push
act pull_request
act push -j build-and-test
act push -W .github/workflows/ci.yml

• -l 列出所选事件的 job；用 act -h 核对当前版本参数。
• -n 不实际执行步骤，不能验证脚本、依赖或运行时成功。
• -j 使用 YAML 中的 job ID，不是显示用的 name。
• -W 指定工作流文件或目录，示例文件需在目标仓库存在。
• 不指定事件时通常选择 push，仅存在其他单一事件等情况会影响默认选择。为可重复调试，宜显式指定事件。

需要特定事件字段时，可通过 -e event.json 提供事件数据；写 pull_request 本身不会自动获得某个真实 PR 的完整上下文。

配置与 secrets

.secrets 是默认 secrets 文件名，也可以指定：

act push --secret-file local.secrets --env-file local.env

将实际文件加入 .gitignore。act -s MY_SECRET 可从已有环境变量读取或交互输入，避免把值直接写进命令历史。GitHub 仓库中的 secrets 不会自动下载到本地。

与托管环境的差别

• runner 镜像可能缺少 GitHub 托管机上的工具，CPU 架构、网络和操作系统也可能不同。
• 部分 GitHub 上下文、权限、审批与服务行为不能完整模拟。
• 当前 act 支持本地缓存服务器，有 --no-cache-server 等设置；缓存是否可用取决于版本、action 和配置，不能笼统说 actions/cache 一定被跳过。
• 工作流中的发布、上传或部署命令在本地也可能产生真实外部效果；运行前应检查所选 job，使用适合测试的输入和权限。

可先用 actionlint 做静态检查，再选定 job 本地执行。后续在 GitHub 验证时仍需遵循项目发布和远端同步策略，本地通过不保证托管运行通过。

[!info] related notes

• actionlint
• GitHub Actions
• 手动触发 workflow

来源

• nektos/act
• act 使用文档