CI/CD / 系统课时
按分支和标签触发工作流
按分支和标签触发工作流
并不是每次 push 都应该运行同一条流水线。通过 branches、tags 以及对应的排除规则,可以把测试限定在开发分支,把发布流程限定在版本标签。本篇直接用一份 workflow 配置说明匹配规则及最容易踩错的边界。
学习目标
- 能使用
branches和tags限定push的触发范围 - 能正确使用排除规则处理分支或标签例外
- 能根据实际 push 的 ref 验证工作流是否应该触发
分支和标签是两类过滤条件
push 可以针对分支和标签分别配置过滤器。分支过滤的是类似 main、release/v2 的分支名,标签过滤的是类似 v2.1.0 的 tag 名;模式支持 glob 语法,因此可以覆盖一组命名一致的 ref。
下面的配置让工作流在 main、release/** 分支以及 v* 标签被推送时触发:
name: filtered-push
on:
push:
branches:
- main
- 'release/**'
tags:
- 'v*'
jobs:
inspect:
runs-on: ubuntu-latest
steps:
- name: Show ref
run: echo "ref=${GITHUB_REF}"这是 workflow 配置示例。保存到 .github/workflows/filtered-push.yml 后,可通过向匹配的分支或标签执行真实 push 来验证。
例如推送 main 后,步骤输出中的 commit SHA 等动态信息可能不同,但 ref 应对应主分支。
预期结果
ref=refs/heads/main如果推送标签 v2.1.0,对应值应为 refs/tags/v2.1.0。因此排查过滤规则时,不要只看自己以为推送了什么,而要确认实际 ref 类型和名称。
排除某些匹配对象
如果需求是“匹配一大类,但排除其中少数对象”,可以使用 branches-ignore 或 tags-ignore。需要注意,同一个事件下不能同时使用 branches 与 branches-ignore 来过滤分支;标签的 tags 与 tags-ignore 也遵循同样限制。
当需要在包含规则中表达例外时,可以在 branches 或 tags 中使用以 ! 开头的否定模式,并同时保留至少一个肯定模式。例如允许所有 release/**,但排除 release/experimental/**:
on:
push:
branches:
- 'release/**'
- '!release/experimental/**'这是片段示例,需要放在完整 workflow 的顶层配置中。release/v2 会匹配肯定模式,而 release/experimental/test 会被后面的否定模式排除。模式顺序有意义:后续匹配可以改变前面模式产生的结果。
验证时分别向两个测试分支推送一次提交,前者应创建 workflow run,后者不应因该 push 创建 run。
避免把分支 push 和标签 push 混在一起
当 push 同时配置了分支过滤器和标签过滤器时,两类 ref 分别按自己的规则判断,并不是要求一次 push 同时满足“分支条件”和“标签条件”。推送 main 时检查 branches,推送 v2.1.0 标签时检查 tags。
反过来,如果只配置 branches 而没有配置 tags,标签 push 不会触发该 workflow;只配置 tags 时,分支 push 也不会触发。这一点很适合把普通持续集成和基于版本标签的发布流程分开。
用最小测试矩阵验证规则
修改过滤条件后,不要只测试一个成功案例。至少选择一个应触发的分支、一个应排除的分支,以及配置标签规则时的一个匹配标签。每次 push 后到 Actions 页面确认是否产生新的 run,并核对 run 关联的 ref。
对于发布流水线,尤其要谨慎使用过宽的 '*' 或 '**' 模式。触发范围本身就是部署边界的一部分:先让规则精确覆盖预期分支和标签,再逐步扩大范围,比依赖 job 内部额外判断更容易维护。