act

act

act 是 GitHub Actions 工作流的第二道防线，排在 actionlint 技能之后。 actionlint 是静态检查工具——它可以证明工作流语法正确，且其中的表达式和类型均有效。 act 是动态检查工具——它会在本地的 Docker 中运行工作流，查看它是否能正常工作。

将其作为建议，而非门槛： 当 actionlint 确认暂存的工作流没有问题后， 可以提议通过 act 运行它们并报告实际故障—— 但绝不要因为 act 而阻止提交。 它的本地运行无法涵盖所有情况， 而且本地环境并不稳定。

有疑问时，请询问操作人员

如果有任何不明确之处—— 尤其是无法判断失败源于工作流本身， 还是仅仅源于本地环境时—— 请询问操作人员，不要猜测。 问一个问题，总比把有问题的工作流说成没问题， 或让操作人员误以为失败了，而实际只是本地缺少镜像，要好。 以下每个步骤都适用此原则。

运行时机

• 在 actionlint 确认暂存的工作流文件没有问题后运行—— 不要在廉价的静态检查已否决工作流时浪费 Docker 资源。
• 对于每次修改了工作流的提交，act 都是一项可选建议， 而非必需步骤。 提议运行；如果操作人员拒绝，就跳过——不得阻止提交。

前置条件

运行需要可用的 Docker 和预先配置的镜像。 先检查这两项；如果缺少任何一项， 请告知操作人员、跳过运行并继续提交—— 绝不要因为前置条件而阻止提交。

1. Docker 可访问——docker info 执行成功 （任何提供程序均可：Docker Desktop、colima，或通过 podman info 使用 podman）。 缺少二进制文件或守护进程未运行 → act 无法运行；跳过。
2. 已配置默认运行器镜像。 首次运行时，act 会交互式询问镜像大小； 如果没有 TTY，它会因 fatal EOF 而退出——因此必须提前完成配置。 配置位于 act 的 actrc 文件中 （macOS 上为 ~/.config/act/actrc、~/.actrc 或 ~/Library/Application Support/act/actrc）； 已配置的文件中会有一行默认 -P 配置。 如果尚未配置，请让操作人员运行一次 act 并选择 Medium （约 500MB；Large 约 70GB，Micro 仅支持 node）——不要猜测镜像。 如果到运行时才发现这一点（出现 fatal EOF），请停止并询问。
3. 主机标志。
   • Apple Silicon——提前添加： uname -m → arm64 → --container-architecture linux/amd64。
   • 守护进程套接字绑定挂载失败（colima 中出现过）—— 仅在首次运行显示该问题后再添加： --container-daemon-socket -。

流程

1. 先确认暂存的工作流通过 actionlint 检查 — 使用 actionlint 技能，或直接运行 actionlint。 act 是第二步，不是第一步。

2. 用一句话向操作人员提议运行 — “要通过 act 运行暂存的工作流，检查它们是否确实能运行吗？”。 如果对方拒绝 → 跳过并让提交继续（act 绝不会阻止提交）。

3. 检查上述前置条件， 并确认已安装 act（command -v act）。 如果未安装 act，将安装作为单独的请求 — 这会编辑 mise.toml（见下文），而运行提议并未授权此操作。 任何前置条件不满足 → 告知操作人员，跳过并让提交继续。

4. 对暂存的工作流文件运行 act — 每个暂存的工作流文件分别运行一次 -W。 act 读取工作区，而非索引， 因此先确认文件没有未暂存的修改 （git diff -- <file> 结果为空）； 如果有修改，先重新暂存（git add），再运行：

   mise exec -- act -W .github/workflows/<staged-file> [host-flags]
   

   • 只有 act 不在 PATH 中时，才使用 mise exec -- 。
   • [host-flags] = 适用的第 3 项前置条件标志（架构 / 套接字）。
   • act 会选择事件（push，或该工作流唯一的事件）； 如有需要，可用 <event> 或 -j <job> 缩小范围。
   • 不要预先筛选 job — 让无法运行的 job 显现为环境故障（第 5 步）。
   • 密钥：如果 .secrets 存在，act 会自动读取 （也可传入 --secret-file）；绝不可凭空编造密钥 — 缺少密钥属于环境跳过，而非失败。

5. 查看结果 — 区分两种失败类型， 因为 act 的退出码不会区分。 根据日志标记判断：

   • 成功 — job 以 ✅ / Job succeeded 结束： 工作流确实在本地运行了（在 act 支持的范围内）。
   • 实际工作流失败 — 某个工作流步骤（而非“Set up job”） 因自身逻辑以非零状态退出。 展示该步骤并建议修复，但不要阻止提交。
   • 环境 / 不支持导致的失败 — 无法启动： failed to start container、Error response from daemon、 unable to find image，或没有适用于 macos/windows runner 的镜像、 fatal ... EOF（镜像提示）、缺少密钥、OIDC、套接字、架构问题。 标准工具出现 command not found 也属于此类 — 几乎总是 Medium 镜像缺少该工具，而非工作流的问题； 你无法检查镜像内容，因此默认归为环境问题， 并询问操作人员是否需要进一步处理。 将这些情况报告为“未在本地检查”，并说明原因，而非报告为失败。
   • 无法判断？ 询问操作人员。

6. 无论结果如何，绝不因 act 阻止提交。 运行结束（或跳过）后，提交继续。

act 缺失时的安装方法

使用 mise 安装 — 并注明 Docker 是一项单独的必需依赖； 没有它，act 无法运行。 在 mise.toml 的 [tools] 下：

[tools]
act = "<version>"

通过 mise latest act 获取 <version> （所有版本：mise ls-remote act）— 固定为完整版本，不要用 latest。 原始名称 act 会通过 aqua 解析为 aqua:nektos/act。 绝不要使用 brew、go install 或 curl 管道脚本。 如果无法通过这种方式安装 act，或 Docker 不可用， 告知操作人员并跳过运行。

覆盖范围说明 — act 不是你的 CI

act 运行结果为绿色，只能算冒烟测试，不能证明真实 CI 会通过。 act 不会运行 macos/windows runner、OIDC、 环境或环境范围内的密钥； 它会忽略并发、超时、continue-on-error、 步骤摘要和注释； 缓存和服务也只有部分支持。 应将 act 视为“能否在本地启动”， 并以真实 CI 为准。

不在范围内

• 替代真实 CI（act 是冒烟测试 — 见上文覆盖范围）。
• 提供或编造密钥 / 凭据。
• 强行运行无法在本地运行的工作流 — 报告情况，不要强行处理。

报告

运行后，说明哪些工作流或 job 已运行、 每项的结果 （通过 / 实际失败 / 未在本地检查及原因）， 并说明提交无论如何都不会被阻止。