CI/CD / 系统课时

工作流没有触发先检查什么

工作流没有触发先检查什么

工作流没有出现在 Actions 运行记录里时,问题通常发生在 Runner 启动之前。最有效的排查方式不是反复修改 YAML,而是沿着“工作流文件是否有效 → 事件是否匹配 → 分支与路径过滤是否通过 → 仓库状态是否允许触发”的顺序逐层缩小范围。

学习目标

  • 区分“没有触发”和“已经触发但执行失败”
  • 按事件、分支、路径和文件位置检查触发条件
  • 用最小化工作流验证仓库的事件触发链路

先确认故障发生在哪一层

如果 Actions 页面已经出现一次 workflow run,只是 Job 或 Step 失败,那么触发器已经工作,不属于“没有触发”。真正的未触发表现是对应事件发生后,没有产生预期的运行记录。

排查时先确认工作流文件位于 .github/workflows/,扩展名为 .yml 或 .yaml,并检查 YAML 与 GitHub Actions 工作流语法。文件放在仓库其他目录,即使内容正确,也不会作为工作流被发现。

bash
find .github/workflows -maxdepth 1 -type f -print

预期输出

text
.github/workflows/ci.yml

实际文件名可能不同;重点是目标文件确实位于 .github/workflows/ 这一层级。

对照实际发生的事件

工作流的 on 决定哪些仓库事件可以创建运行。例如下面的工作流只监听推送到 main 的事件,以及目标分支为 main 的 Pull Request:

yaml
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/**:

yaml
on:
  push:
    branches:
      - main
    paths:
      - "src/**"

这是片段示例,需要放在完整工作流的顶层。它的生效行为是:推送必须同时匹配 main 和 src/** 才会触发。只修改 README.md,即使推送到了 main,也不会创建这次运行。

遇到复杂过滤条件时,可以暂时建立一个不带分支和路径过滤的最小工作流。若最小版本能够触发,再逐项恢复过滤条件,比同时猜测多个规则更容易定位问题。

工作流未触发的排查链路

再看仓库状态和事件来源

如果配置本身能匹配,还要检查事件发生时 GitHub 实际使用的工作流版本以及仓库设置。尤其是刚新增或修改工作流时,应确认文件已经提交并推送到预期仓库和分支,而不是只存在于本地工作区。

对于来自 fork 的 Pull Request、由其他自动化产生的事件以及仓库 Actions 权限受限的场景,还要结合仓库的 Actions 设置和事件类型检查限制。不要为了让工作流“先跑起来”就直接扩大令牌或仓库权限;触发问题与运行时权限问题应分开处理。

用最小工作流建立基准

当原工作流包含大量过滤规则时,可以创建一个临时诊断工作流,只监听目标事件并输出事件名称:

yaml
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 日志类似:

text
event=push ref=refs/heads/<BRANCH>

<BRANCH> 是实际推送分支。如果这个最小工作流能运行,说明基本事件链路正常,应回到原工作流逐项检查 branches、paths 等过滤条件;如果仍完全没有运行记录,则优先检查文件位置、提交状态和仓库 Actions 设置。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

工作流没有触发先检查什么

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通