CI/CD / 系统课时

按分支和标签触发工作流

按分支和标签触发工作流

并不是每次 push 都应该运行同一条流水线。通过 branches、tags 以及对应的排除规则,可以把测试限定在开发分支,把发布流程限定在版本标签。本篇直接用一份 workflow 配置说明匹配规则及最容易踩错的边界。

学习目标

  • 能使用 branches 和 tags 限定 push 的触发范围
  • 能正确使用排除规则处理分支或标签例外
  • 能根据实际 push 的 ref 验证工作流是否应该触发

分支和标签是两类过滤条件

push 可以针对分支和标签分别配置过滤器。分支过滤的是类似 main、release/v2 的分支名,标签过滤的是类似 v2.1.0 的 tag 名;模式支持 glob 语法,因此可以覆盖一组命名一致的 ref。

下面的配置让工作流在 main、release/** 分支以及 v* 标签被推送时触发:

yaml
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 应对应主分支。

预期结果

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

yaml
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 内部额外判断更容易维护。

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

目录与阅读设置

阅读设置

17

记录一个想法

按分支和标签触发工作流

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

登录哪都通