actionlint

actionlint

避免明显有问题的 GitHub Actions 工作流进入仓库。 提交涉及工作流文件的更改前， 请对暂存的文件运行 actionlint； 任何非零退出码都会阻止提交，直到问题修复。

它与 vcs-identity-check 和 vcs-commit-msg 一样，都是提交前置条件； 三者彼此独立，因此执行顺序无关紧要。

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

如果有任何不明确之处， 缺少前置条件， 或你不确定该如何继续—— 请停下来询问操作人员，而不要猜测。 提一个问题的代价低于错误提交、 误操作修复， 或花费 token 绕过一个本可通过询问解决的问题。 以下每个步骤都适用此规则。

何时运行（检查门槛）

当暂存的更改包含工作流文件时运行此流程—— .github/workflows/*.yml 或 .github/workflows/*.yaml。 如果没有匹配的暂存文件，则此技能不适用； 请保持静默。

不检查远程地址。 .github/workflows/ 下的工作流文件仅用于 GitHub Actions （包括 GitHub.com 和 GitHub Enterprise）， 因此它们的存在本身就是充分信号—— 检查远程地址是否指向 github.com 只会在 Enterprise（自定义域名） 以及尚无远程地址的本地仓库中造成漏报。

范围仅限工作流文件。 actionlint 不会检查 action.yml / action.yaml （复合操作元数据）， 因此这些文件不在此范围内。

流程

请在仓库根目录运行以下每个步骤 — cd "$(git rev-parse --show-toplevel)" — 因为 git 打印的路径相对于该目录， 而 actionlint 必须从同一目录解析这些路径。

1. 收集已暂存的工作流文件 （新增 / 复制 / 修改 / 重命名 — 删除的文件无需检查）：

   git diff --cached --name-only --diff-filter=ACMR -- .github/workflows \
     | grep -E '\.ya?ml$'
   

   结果为空 → 此门禁不适用； 停止。

2. 确保 actionlint 可用： command -v actionlint。 如果缺少，请通过 mise 技能安装 （参见下方的 安装 actionlint） — 绝不要使用 brew / go install / curl 管道。 如果无法通过该方式安装 actionlint （没有 mise，或项目未使用 mise）， 请告知操作者并停止 — 不要改用其他安装程序。

3. 确认已暂存版本与工作树版本一致。 actionlint 从工作树读取文件，而不是从索引读取， 因此，已暂存的工作流如果带有额外的未暂存修改， 检查的版本就会与提交的版本不同：

   git diff --name-only -- <staged-files…>
   

   有任何输出 → 版本不一致； 停止并要求操作者重新暂存或搁置这些修改， 而不是检查不会被提交的内容。

4. 检查已暂存的文件，将它们作为参数传入， 以免未改动的旧工作流中的无关错误阻止此次提交：

   actionlint <staged-files…>
   

   直接运行 actionlint — 它只会在 shellcheck / pyflakes 位于 PATH 中时自动使用它们， 此门禁无需切换任何选项。 第 3 步通过后，此检查所针对的正是将要提交的内容。

5. 根据退出码采取行动（$?）：

   • 0 — 检查通过； 工作流部分的提交可以继续。
   • 1 — actionlint 在工作流中发现问题， 包括无效 YAML 和错误的工作流结构 （这些问题带有 [syntax-check] 标签） — 这属于「明显有问题」的情况。 显示输出并阻止提交。 不要盲目改写工作流： 如果修复方式不明确，请询问操作者。 修复后，重新暂存文件（git add）并从第 3 步重新运行； 只有退出码为 0 时，提交才可继续。
   • 2 — 命令行参数无效： 这是调用 actionlint 的方式有误，而不是工作流有问题。 修正调用方式（第 4 步）并重新运行。
   • 3 — actionlint 无法读取文件（could not read …）： 通常是路径无法解析 — 请确认命令是在仓库根目录运行的，然后重新运行。

6. 仅在退出码为 0 时放行提交。 此技能是门禁，不负责提交本身 — 退出码为 0 时，工作流检查已通过， 正常提交流程（vcs-identity-check / vcs-commit-msg）会继续。 任何非零退出码都会阻止提交； 不要使用 --no-verify 或以其他方式绕过门禁。

actionlint 缺失时的安装方法

使用 mise 安装。 如果 mise 技能可用，请让它负责具体细节 （版本固定、mise.lock、后端策略） — 这是此处的标准路径。

如果没有该技能但有 mise 二进制文件， 请在 mise.toml 的 [tools] 下自行添加 actionlint：

[tools]
actionlint = "<version>"

通过 mise latest actionlint 获取 <version> （所有版本：mise ls-remote actionlint）— 完整固定版本，不要使用 latest。 原始名称 actionlint 会通过 aqua 解析为 aqua:rhysd/actionlint。 无论哪种方式：绝不要使用 brew、go install 或 curl 管道脚本。

此技能不会安装 shellcheck 或 pyflakes。 actionlint 会在它们位于 PATH 中时自动使用它们 （将检查扩展到 run: shell 和 Python）， 缺少它们不算错误。 如需确定性地关闭这些集成， 请传入空值：actionlint -shellcheck= -pyflakes=。

现有的 actionlint 配置

如果仓库已有 .github/actionlint.yaml（或 .yml）， actionlint 会自动使用它 （自托管运行器标签、配置变量、按路径忽略规则）。 请遵循该配置： 不要覆盖它，也不要对其运行 -init-config。 配置是可选的 — 没有配置时，actionlint 也能正常运行。

可选：通过 pre-commit 钩子强制执行

上述流程可保护 Agent 创建的提交。 若还要检查手动输入的提交，可提供 pre-commit 钩子 （仅在用户同意后安装——提出建议，不要强加）。

actionlint 提供官方的 pre-commit-framework 集成。 在 .pre-commit-config.yaml 中：

- repo: https://github.com/rhysd/actionlint
  rev: <vX.Y.Z>
  hooks:
    - id: actionlint-system

将 rev 设为对应的发布标签—— v 加上 mise latest actionlint 返回的版本 （因此，版本 X.Y.Z → 标签 vX.Y.Z）， 也可在 https://github.com/rhysd/actionlint/releases 查看。

使用 actionlint-system 钩子 ID： 它会运行 PATH 上已有的二进制文件（由 mise 管理） 而不是通过 Go 工具链（actionlint） 或 Docker（actionlint-docker）自行获取。 通过 mise 技能安装 pre-commit 执行器本身 （它是 Python CLI → 使用 pipx 后端）。

不在范围内

• 对 uses: 引用进行 SHA 固定——这是 pinact / Dependabot 的工作，不属于 actionlint。
• CI 集成（单独处理）。

报告

检查后，说明已 lint 的工作流文件、 退出代码、发现的问题（如有）， 以及提交已获准还是被阻止。