CI/CD 工具

GitHub Actions 工作流验证格式化、校验并在 job 与 step 间跳转

粘贴 workflow YAML 即可格式化、浏览 job/step 导航树,并在插入主输入前先预览 matrix 或 cron 片段。

GitHub Actions 工作流验证

workflow YAML

结果

全部处理都在浏览器本地完成,不会发送到 GitHub 或任何服务器。

选项
Matrix 生成器(草稿)

变量

include(可选)

exclude(可选)

点「生成预览」查看 strategy.matrix 片段。

Cron 片段生成器(草稿)

点「生成预览」查看 on.schedule 片段。

等待校验…

workflow YAML 出问题往往是推送之后才发现:某个 job 忘了写 runs-on、permissions 填了不存在的枚举值,或者定时任务悄悄从没触发过。这个 GitHub Actions 工作流验证工具在本地就能拦下这类错误——它检查的是 CI 真正依赖的结构,而不只是 YAML 语法本身是否合法。

当你要在有多个 job 的长 workflow 里快速定位出错的那一个、给不同操作系统和版本组合搭建 matrix、在多个 step 之间理清 env、secrets、vars 引用,或者要写一段 on.schedule 的 cron 表达式并想知道 GitHub Actions 自己到底允许什么写法时,都用得上它。

为什么用这个 GitHub Actions 工作流验证工具

不用在通用 YAML 校验器、matrix 生成器和一个根本不认识 GitHub Actions 的 cron 工具之间来回切换。

格式化、结构校验与 job/step 导航放在同一个工作台

粘贴 workflow 后会自动格式化 YAML,检查 job id 和 step id 的命名规则,确认每个 job 都写了 runs-on 或 uses 二选一,校验 permissions 的枚举取值(id-token 只能是 write 或 none),并标出 branches 与 branches-ignore 同时出现这类互斥写法;随后生成一棵可点击的 job/step 导航树,点一下就能让编辑器跳到对应行。

格式化后的 GitHub Actions workflow YAML 旁边是可点击的 job 与 step 导航树,并高亮了一处结构校验错误

看清 env、secrets、github 引用会在哪里报错

引用清单会列出 workflow 里每一处 ${{ env.X }}、${{ secrets.X }}、${{ vars.X }}、${{ github.X }} 表达式,标注所在的 job 和 step,并标出三处官方文档写明的真实报错位置:env 不能用在 step 的 id 或 uses 上;secrets 不能直接写进 if 条件;github 不能用在 uses 里。

env、secrets、vars、github 表达式引用清单,其中三条被标注出 GitHub Actions 实际会报错的位置

Cron 构建器天生懂 GitHub Actions 自己的限制

Cron 面板生成标准 5 字段表达式,并直接套用 GitHub 官方文档对 schedule 触发器的限制:最短 5 分钟一次、默认 UTC 时区、可选 IANA timezone、不支持 @daily 这类别名,以及公开仓库连续 60 天无活动会被自动禁用。

Cron 构建器界面展示 GitHub Actions 的 5 分钟最短间隔、默认 UTC 时区与不支持的别名提示

三件第一次用很容易漏掉的事

工具台在背后做的事,比工具栏上看到的按钮要多。

01

粘贴 workflow 或加载示例

把从编辑器复制的 workflow YAML 粘贴进来,或者直接加载内置示例——示例里已经包含一个定时触发器、一个带 strategy.matrix 的 job,以及 env/secrets/github 三类引用,一次就能看到全部五项能力。自动校验默认开启,停止输入 350ms 后就会重新解析,全程不上传任何内容。

  • 点击导航树里任意一个 job 或 step 名称,编辑器会立刻跳到对应行——workflow 里 job 一多,这一步才真正省时间。
02

把 matrix 和 cron 面板当草稿,不会自动改写主输入

在 matrix 变量表或 cron 字段里怎么改,都不会直接影响你的 workflow,只是生成一份预览。只有点击「插入」,内容才会真的写进 strategy.matrix 或 on.schedule;在此之前,这份草稿片段也可以单独复制走。

  • 版本号要加引号写成 node-version: "3.10"——不加引号的话,YAML 会把 3.10 解析成数字 3.1,末尾的 0 悄悄就丢了。
  • fail-fast 默认是 true,max-parallel 默认留空(不限制),和 GitHub Actions 官方默认值一致。
03

先看风险标记,再相信一个「无错误」的结果

env/secrets/vars/github 引用清单标出的是 GitHub Actions 文档写明的真实报错位置,不是通用 linter 猜出来的。关闭自动校验后按 Ctrl/Cmd+Enter 手动重新校验;校验后继续编辑,复制和下载按钮会保持禁用,直到重新校验通过,避免导出一份已经过期的结果。

  • 引用清单上方的筛选器可以只看 env、secrets、vars 或 github 中的一类,表达式一多时更容易审查。

工具台背后真正在做的事

五项能力互相配合,而不是五个各自独立的标签页。

格式化 YAML,缩进可选 2 或 4 空格

用统一的 2 空格或 4 空格重新排版整份 workflow,这样提交到 PR 里的 diff 只显示真正改动的那几行,而不是整份文件被重新排版。

按真实 workflow 规则做结构校验

job id 和 step id 会按官方命名规则检查,每个 job 都会确认写了 runs-on 或 uses 二选一,permissions 的取值会对照真实枚举校验,同一个触发器里 branches 和 branches-ignore 这类互斥过滤器同时出现也会被标出。

可点击的 job/step 导航树

导航树按 workflow 真实的 job 和 step 结构生成,点一下条目,编辑器就滚动到对应那一行,不用自己数缩进层级去找。

Matrix 生成器支持 include、exclude 和 fail-fast

搭建 os/版本号这类变量表,添加 include 或 exclude 组合,设置 fail-fast 和 max-parallel,预览生成的 strategy.matrix,再插入到你选定的那个 job 里。

env/secrets/vars/github 引用清单

自动提取 workflow 里所有引用 env、secrets、vars、github 的 ${{ }} 表达式,按 job 和 step 分类列出,并支持只看某一类引用。

只服务 GitHub Actions 的 Cron 片段生成器

从常用预设或自定义表达式生成 5 字段 cron,预览即将写入的 on.schedule 片段再插入;GitHub 自己的调度限制会自动套用,不用你自己记。

这个工具校验什么,又故意不做什么

知道边界在哪,比堆一长串功能清单更重要。

不连接 GitHub,也不执行任何 workflow
这个 GitHub Actions 工作流验证工具是纯本地的文本解析器:不调用 GitHub API,不 fork 或 push 仓库,也不会触发或运行任何 workflow——它只在你的设备上格式化并校验你粘贴的文本。
不做表达式求值
${{ github.sha }} 或 ${{ steps.build.outputs.version }} 这类表达式只会被提取列出,不会被解析成真实运行时的值。要测试表达式真实的求值行为,需要一套独立的表达式引擎,那是另一个专门的工具——这里不会用 JavaScript eval 去假装模拟它。
schema 校验是精简子集,不等价于 actionlint
结构校验覆盖的是 schemastore.org 公开 schema 里不依赖外部元数据的那部分规则:job/step id、runs-on/uses、permissions、过滤器互斥。它不检查 action 的输入参数类型、Marketplace action 的版本,也不维护一份实时更新的 runner 标签白名单——那类元数据一旦离线缓存就会过期。
不画依赖关系图
job/step 导航树展示的是结构,不是 needs 依赖关系渲染出来的 DAG 图。如果需要看可视化的依赖关系图,这是另一种展示形式,这个工具目前不做。
调度限制照官方文档写,但不保证一定生效
cron 构建器套用的是 GitHub 公开的规则——最短 5 分钟、默认 UTC、不支持 @daily 这类别名——但没法保证可选的 timezone 字段一定被采纳,也没法保证到点必然触发;官方文档写明高负载时可能延迟,公开仓库连续 60 天无活动还会被自动禁用。

关于 GitHub Actions 工作流验证的常见问题

答案都对照官方文档写,不是猜的。

GitHub Actions 的定时任务时区设置到底是不是北京时间,需不需要自己减 8 小时?

GitHub Actions 的 schedule 默认按 UTC 计算,北京时间要减 8 小时换算;2024 年后官方新增了可选的 timezone 字段(IANA 时区名),理论上可以直接写 Asia/Shanghai 而不用手动换算。但这个字段在社区讨论里有真实反馈没有按预期生效,本工具只保证生成的片段符合已发布语法,不保证 GitHub 调度侧一定按时区触发。

为什么 GitHub Actions 的定时任务不按设定的时间触发?

几个真实原因:workflow 文件不在默认分支上;仓库长期无活动,GitHub 在 60 天后自动禁用了定时任务;或者表达式的间隔小于官方规定的 5 分钟最短限制。官方文档也提到高负载时段(尤其是整点前后)触发会延迟——这个工具只做语法层校验,不能承诺精确到点触发。

GitHub Actions 报错 you have an error in your yaml syntax,但看不出第几行,怎么定位?

把 workflow 粘贴进这个 GitHub Actions 工作流验证工具,它会给出具体的 job 或 step 名称以及行列号,而不是 GitHub 那句笼统的报错。停止输入 350 毫秒后会自动重新校验,标记位置随内容实时更新。

reusable workflow 的 with 里用 env.xxx 为什么会报 Unrecognized named-value?

因为 with 块里本来就不能使用 env 上下文,这是官方文档写明的三处限制之一(env 同样不能用在 step 的 id 或 uses 上),引用清单会直接把这类引用标出来。正确做法是把值放到 job 级或 workflow 级的 env 里,或者显式作为 input 传给被复用的 workflow。

GitHub Actions 的 secrets 怎么在 if 条件里用,为什么直接写不识别?

secrets 不能直接出现在 if 条件表达式里,这是官方文档明确的限制。正确写法是先把 secrets 赋值给 job 级或 step 级的 env 变量,再在 if 条件里判断这个 env 值。这是引用清单会对每一处 secrets.* 引用标注的三个风险位置之一。

GitHub Actions matrix 版本号写 3.10,结果变成 3.1,是怎么回事?

这是 YAML 解析的固有行为:不加引号的 3.10 会被当成数字 3.1,末尾的 0 悄悄丢掉了,跟 GitHub Actions 本身没关系。matrix 生成器会识别这类版本号形态的值,插入生成的 strategy.matrix 时自动加上引号。

发现某个 workflow 被判错了?

现在就用 GitHub Actions 工作流验证工具

把 workflow 粘贴进这个 GitHub Actions 工作流验证工具,看 job/step 导航树和引用清单实时更新,需要时再生成 matrix 或 cron 草稿。

所有处理都留在你的浏览器里——不上传任何内容,也不会触发任何 workflow。

全部解析都在浏览器本地完成。