GitHub Actions concurrency group 使用表达式时怎样避免误取消

GitHub Actions 的 concurrency 配置最容易出错的地方，不是会不会写 group，而是把“哪些运行属于同一组”和“新运行是否可以取消旧运行”混成了一件事。稳妥的写法是先用工作流名、拉取请求编号或完整 ref 组成隔离键，再单独用表达式决定 release 分支是否允许取消。

官方地址：https://github.com/

Actions 文档：https://docs.github.com/en/actions

不要只写 group: ${{ github.ref_name }}，也不要只用 github.head_ref。前者可能让不同工作流共享同一组，后者可能让不同 PR 的同名源分支互相取消。用 github.workflow 和 PR 编号或 ref 组合组名，再把 release 分支排除在取消条件之外，才能同时做到隔离和可控。

• 组名负责回答“哪些运行互斥”。
• cancel-in-progress 负责回答“新运行能不能取消旧运行”。
• 同组默认只保留一个 pending 运行；不要把这个默认行为误认为所有运行都会自动取消。

第1步：先打开正确的工作流文件

进入仓库的 Code → .github → workflows，打开需要互斥的 CI 或部署 YAML。通常应该在工作流级别配置 concurrency，也就是让它和 on、jobs 处在同一层；如果只想限制某一个 job，再把配置放到 jobs..concurrency。

判断入口是否正确，可以看编辑区是否同时出现 on 和 jobs 两个顶层区域。不要把配置写进某个 step 的 run 文本，也不要在多个 workflow 之间复制同一个固定组名。

第2步：把组名和取消条件分开配置

在 Code → .github/workflows → 目标 YAML → 编辑区的 on 后面加入下面的配置。这个例子把工作流名称和事件身份拼进组名：拉取请求优先使用 PR 编号，push 等事件则回退到完整的 github.ref。

# 工作流级互斥：先隔离运行，再决定是否取消旧运行
concurrency:
  # PR 用编号隔离，push 用完整 ref；工作流名避免跨 workflow 串组
  group: ci-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
  # 普通分支允许取消旧运行，release 分支保留已在运行的任务
  cancel-in-progress: ${{ !contains(github.ref, 'release/') }}

这里有三个关键点。

1. 不要只用分支短名。如果两个 workflow 都使用 main 作为组名，它们可能互相影响。加上 github.workflow 后，组键至少带有工作流边界。
2. PR 不要只用源分支名。不同 PR 可能都叫 feature/login，但它们应当各自拥有独立的并发组。PR 编号比 github.head_ref 更适合作为隔离标识。
3. 取消条件要单独判断。cancel-in-progress 为真时，同组的新运行可以取消旧运行；示例用 ref 中的 release/ 作为保护约定，release 分支返回假值。

如果项目不用 release 分支，也可以把这一行固定为 true；如果只想让普通开发分支取消旧运行，就保留表达式并让分支命名约定保持一致。组名表达式只引用能在该位置使用的上下文，不要把 runner 或 secrets 直接塞进 workflow 级并发键。

第3步：从运行列表确认没有误取消

保存 YAML 后进入 Actions → 目标 workflow → 运行列表，分别观察同一 PR 的连续两次运行、普通分支的连续 push，以及 release 分支的连续 push。打开每条运行的详情页，先看组键预览或运行状态，再判断取消是否符合预期。

1. 同一 PR 的第二次提交应使用同一个 PR 组键；如果开启取消，旧的过时检查可以被标记为取消，新的检查继续执行。
2. 两个不同 PR 即使源分支都叫 feature/login，也应因为 PR 编号不同而分到不同组。
3. release 分支的新运行不应因为 cancel-in-progress 条件为假而取消同组中已经开始的旧运行。

如果看到不相关 workflow 一起变成 cancelled，先回到第2步检查组名是否漏了 github.workflow。如果只有同一个 PR 的旧检查被取消，通常属于预期行为；如果 release 运行也被取消，再检查分支名是否真的包含表达式中的 release/。

一张表记住配置边界

常见问题

为什么要把 workflow 名放进 group？

并发组的名称在仓库范围内比较。把 github.workflow 加进去，可以减少两个不同 workflow 使用相同分支名时互相取消的风险。

能不能直接使用 github.head_ref？

可以表达 PR 的源分支，但它不是 PR 的唯一编号。多个 PR 使用相同源分支名时，单独使用它可能把本应独立的运行放进同一组；更稳妥的是使用 PR 编号并用 github.ref 做非 PR 事件回退。

为什么同组的旧 pending 运行会消失？

并发组默认只保留一个 pending 运行，新排队的运行可能替换同组已有的 pending 运行。这和是否取消正在执行的运行是两件事；后者才由 cancel-in-progress 控制。

release 分支仍然被取消怎么办？

先看实际 ref 是否符合表达式中的 release/ 命名，再确认没有在 job 级别写了另一套 concurrency。工作流级和 job 级规则叠加时，应逐层检查哪一层产生了取消。