如何在现有CircleCI config.yml中使用auto-cancel-workflow orb

通用使用前提 #

所有自定义Orb的配置逻辑是统一的，不需要单独找对应文档，只要按CircleCI的标准Orb配置规则嵌入现有配置即可。首先要确认你的config.yml顶层版本为2.1，这是Orb功能的最低要求。

第一步：在现有配置顶部声明Orb #

找到你config.yml里已有的version字段，在同级位置新增orbs配置块，按「命名空间/Orb名称@固定版本号」的格式引入目标Orb，示例片段：

version: 2.1
orbs:
  # 给引入的Orb起一个短别名，方便后面配置时直接调用
  cancel-orch: ganezasan/auto-cancel-workflow@3.1.0

注意：版本号要填对应Orb的已发布稳定版本，不要在生产配置中使用动态的volatile版本标记，避免版本自动升级带来非预期行为。

第二步：嵌入现有Workflow实现自动取消逻辑 #

这个Orb的核心能力是，当工作流中任意一个关联任务失败时，自动取消当前工作流内所有未运行、排队中、运行中的冗余任务，和你“测试不通过就自动终止其他任务”的需求完全匹配。
配置时不需要改动你已经写好的原有Job逻辑，只需要在现有Workflow的Job列表里，加入Orb提供的触发取消动作的任务，配好依赖关系即可。

举个常见的改造示例，假设你原来的CI配置是这样的：

# 原有Job定义保持不变
jobs:
  unit-test:
    docker:
      - image: cimg/node:20
    steps:
      - checkout
      - run: npm run test
  build-frontend:
    docker:
      - image: cimg/node:20
    steps:
      - checkout
      - run: npm run build
  deploy-preview:
    docker:
      - image: cimg/aws-cli:2
    steps:
      - checkout
      - run: echo "部署预览环境"

# 原有Workflow配置初始状态
workflows:
  main-pipeline:
    jobs:
      - unit-test
      - build-frontend:
          requires: [unit-test]
      - deploy-preview:
          requires: [build-frontend]

你只需要在Workflow的jobs列表末尾，新增取消任务的配置即可，改造后的片段：

workflows:
  main-pipeline:
    jobs:
      - unit-test
      - build-frontend:
          requires: [unit-test]
      - deploy-preview:
          requires: [build-frontend]
      # 新增Orb提供的自动取消任务
      - cancel-orch/on_fail:
          # 把所有你需要受自动取消逻辑管控的任务，都加到requires列表里
          requires:
            - unit-test
            - build-frontend
            - deploy-preview
          # 必须加这个参数，保证上游任务失败时，取消任务本身依然能触发
          when: always

配置必查要点 #

• 不能省略when: always配置：如果缺少这个参数，一旦上游测试、构建任务失败，取消任务本身就会被跳过，完全触发不了取消动作
• requires列表要覆盖全量受管控的任务：如果漏加某个Job的依赖关系，当自动取消逻辑触发时，漏配的Job会不受限制继续运行
• 提前检查项目权限：确保你的CircleCI项目设置里开启了允许第三方Orb运行的权限，不然Orb拉取会直接失败
• 触发逻辑的适配：如果你希望只有测试类Job失败时才触发取消，构建类Job失败不触发，只要把对应的测试Job加到取消任务的requires列表即可，不需要把所有下游任务都配进去

不生效时的快速排查方向 #

1. 检查Orb的版本号是不是正确引用，没有拼写错误
2. 检查取消任务的when: always参数有没有正确配置
3. 检查工作流的依赖关系有没有配置错误，导致取消任务的运行时机不对

内容的提问来源于stack exchange，提问作者Em Ae