CI/CD / 系统课时
工作流没有触发先检查什么
工作流没有触发先检查什么
工作流没有出现在 Actions 运行记录里时,问题通常发生在 Runner 启动之前。最有效的排查方式不是反复修改 YAML,而是沿着“工作流文件是否有效 → 事件是否匹配 → 分支与路径过滤是否通过 → 仓库状态是否允许触发”的顺序逐层缩小范围。
学习目标
- 区分“没有触发”和“已经触发但执行失败”
- 按事件、分支、路径和文件位置检查触发条件
- 用最小化工作流验证仓库的事件触发链路
先确认故障发生在哪一层
如果 Actions 页面已经出现一次 workflow run,只是 Job 或 Step 失败,那么触发器已经工作,不属于“没有触发”。真正的未触发表现是对应事件发生后,没有产生预期的运行记录。
排查时先确认工作流文件位于 .github/workflows/,扩展名为 .yml 或 .yaml,并检查 YAML 与 GitHub Actions 工作流语法。文件放在仓库其他目录,即使内容正确,也不会作为工作流被发现。
find .github/workflows -maxdepth 1 -type f -print预期输出
.github/workflows/ci.yml实际文件名可能不同;重点是目标文件确实位于 .github/workflows/ 这一层级。
对照实际发生的事件
工作流的 on 决定哪些仓库事件可以创建运行。例如下面的工作流只监听推送到 main 的事件,以及目标分支为 main 的 Pull Request:
name: CI
on:
push:
branches:
- main
pull_request:
branches:
- main
jobs:
verify:
runs-on: ubuntu-latest
steps:
- name: Confirm trigger
run: echo "workflow triggered"这是配置文件示例。提交后,可分别向 main 推送提交或创建以 main 为目标分支的 Pull Request,再到 Actions 页面检查是否产生运行记录。
检查分支和路径过滤是否同时成立
当事件下同时配置分支与路径过滤时,不能只检查其中一个条件。例如工作流要求推送到 main,同时只关心 src/**:
on:
push:
branches:
- main
paths:
- "src/**"这是片段示例,需要放在完整工作流的顶层。它的生效行为是:推送必须同时匹配 main 和 src/** 才会触发。只修改 README.md,即使推送到了 main,也不会创建这次运行。
遇到复杂过滤条件时,可以暂时建立一个不带分支和路径过滤的最小工作流。若最小版本能够触发,再逐项恢复过滤条件,比同时猜测多个规则更容易定位问题。

再看仓库状态和事件来源
如果配置本身能匹配,还要检查事件发生时 GitHub 实际使用的工作流版本以及仓库设置。尤其是刚新增或修改工作流时,应确认文件已经提交并推送到预期仓库和分支,而不是只存在于本地工作区。
对于来自 fork 的 Pull Request、由其他自动化产生的事件以及仓库 Actions 权限受限的场景,还要结合仓库的 Actions 设置和事件类型检查限制。不要为了让工作流“先跑起来”就直接扩大令牌或仓库权限;触发问题与运行时权限问题应分开处理。
用最小工作流建立基准
当原工作流包含大量过滤规则时,可以创建一个临时诊断工作流,只监听目标事件并输出事件名称:
name: Trigger diagnostic
on:
push:
jobs:
diagnose:
runs-on: ubuntu-latest
steps:
- name: Show event
run: echo "event=${{ github.event_name }} ref=${{ github.ref }}"这是完整的诊断工作流。推送一次提交后,预期在 Actions 页面产生 Trigger diagnostic 运行;Step 日志类似:
event=push ref=refs/heads/<BRANCH><BRANCH> 是实际推送分支。如果这个最小工作流能运行,说明基本事件链路正常,应回到原工作流逐项检查 branches、paths 等过滤条件;如果仍完全没有运行记录,则优先检查文件位置、提交状态和仓库 Actions 设置。