Agent Skills
返回列表
💻

Actionlint 工作流检查

开发编程 更新于 2026.08.29

将以下提示词粘贴到你的 AI 对话框中：

请根据 https://skillhub.cn/install/skillhub.md，安装 @user_3c6cb52e/lint-github-actions-workflows-before-ci-runs-with-actionlint 到当前 AI 助手。

技能介绍

先说清楚要解决的问题

GitHub Actions 的 YAML 有一个很危险的特性：语法正确不代表语义正确。run: 里的命令写错了、with: 传了 action 根本没定义的 input、steps.<id>.outputs 引用了不存在的输出，这些错误不会在本地暴露，只有真正 push 之后 CI 才会告诉你，而代价是已经浪费了一轮流水线。

更麻烦的是表达式层面。${{ matrix.platform }}-node-${{ hashFiles('**/package-lock.json') }} 这类写法在文件里看起来完全正常，但 matrix 没有定义对应 key、或 actions/setup-node@v4 已经改名了 input，问题要等到 runner 解析时才出现。

这个技能做了什么

核心思路是把校验左移到 CI 之前：拿到 actionlint 二进制和仓库里的工作流文件，直接在本地跑静态检查，让问题在 commit 阶段就被拦住。

能力集中在三类检查上：

  • Workflow 语法校验：YAML 结构、on / jobs / steps 的层级是否符合 schema
  • Actions 用法检查：核对 with: 传入的 input 是否在 action 声明的可用列表里，以及 steps.<id>.outputs 的引用是否真实存在
  • 脚本静态分析：对 run: 里的内容做集成检查，借助 shellcheck 和 pyflakes 覆盖 shell 与 Python 脚本的常见错误

一个真实报错的例子可以说明这类检查的价值：

test.yaml:17:11: input "node_version" is not defined in action "actions/setup-node@v4".
available inputs are "always-auth", "architecture", "cache", ...

也就是说，有人把 node-version 写成了 node_version，actionlint 直接给出了期望的 input 列表，而不是等 CI 阶段拿到一个含糊的运行失败。

适用边界与注意点

这个技能的定位是静态检查，不是运行时验证。它能保证你写的工作流在语法和 schema 层面自洽，但无法保证 action 的实际行为、权限配置是否够用、或者某个 job 在真实环境里能否成功。

几个实际使用时需要留意的点：

  • 检查质量取决于 actionlint 的版本，上游更新后建议定期重新跑一遍，避免漏掉新 action 的 input 变更
  • 对第三方 action 的 input 校验依赖其元数据，如果 action 本身声明不规范，检查结果也不可靠
  • shellcheck / pyflakes 集成只覆盖脚本层面，不会模拟环境变量或 runner 行为
  • 它不替代 CI 里的 --actionlint 集成步骤，更适合作为提交前的本地预检

总的来说，这是一个在 push 之前给工作流做一次"快速体检"的工具，把本该花在排队等 CI 上的时间提前消化在本地。

使用场景

  • 本地提交前检查 GitHub Actions 工作流语法、表达式和 shell 脚本，确认未破坏 CI 配置后再 push。
  • 修改 YAML 结构或表达式后，验证 jobs、steps、with、outputs 引用是否正确，避免 CI 阶段报错。
  • 对第三方 action 的 input 参数、cache 配置和 script 行为进行静态核对，排查 input 未定义或输出不匹配。
  • 排查 run 脚本中 shell 语法和 Python 语法错误，减少因 shellcheck、pyflakes 类问题导致的 CI 失败。

适合人员

  • 后端或 DevOps 工程师，经常编写 GitHub Actions CI 流程，希望提交前确认语法和引用正确。
  • 前端工程师，需要维护 Node.js 构建或发布工作流，担心 matrix、cache 或 setup-node 参数配置出错。
  • 开源贡献者或企业内部项目 PR 提交者，修改 workflow 后希望本地快速自检，减少 CI 排队后的失败成本。
  • 自动化工具或 CI 模板维护者，希望批量校验仓库中的 workflow 文件，保持多项目 CI 配置一致。