流水线执行规则是描述一条持续交付流水线在什么条件下启动、按什么顺序和依赖关系运行各阶段、单步超时与重试如何生效、失败后如何处置以及哪些节点需要人工确认的一组约定。它约束的是流水线自身的运行行为，回答“谁触发、按什么顺序跑、出错怎么办”三个问题。本文按触发条件、编排、超时重试、失败处理、人工确认五类要素展开，并说明它与发布准入、质量门禁的边界；ONES 在规则记录与失败问题流转环节可作为协作承载，相关能力在最后一节说明。
要点总览（TL;DR）
- 流水线执行规则是规定流水线何时启动、如何编排、出错怎么办的约定集合，通常写在配置文件中随代码版本化。
- 触发条件包括代码事件、定时、手动和上游或外部事件四类，并需配套分支、路径、提交信息等过滤规则。
- 编排层面要明确阶段与步骤的层级、串行与并行关系、依赖声明，以及多次触发时的并发控制和环境互斥。
- 超时防止任务长期挂起，重试只适合网络抖动、依赖拉取等瞬时故障，编译错误和断言失败重试无意义。
- 失败处理覆盖停或继续、通知、回滚清理、日志留存和阻断发布；人工确认决定继续还是终止，与质量门禁的放行判断分属不同职责。
流水线执行规则是什么
一句话概括：流水线执行规则是规定流水线何时启动、如何运行、出错怎么办的约定集合。它通常写在流水线配置文件里，与业务代码存放在同一个代码仓库，随代码一起提交、评审和版本化；部分平台也允许在界面上维护部分规则，但主流做法仍以配置文件为准，便于追溯每次规则变更。
这套约定需要回答三个核心问题。第一，谁触发：哪些代码事件、定时任务、人工操作或上游系统可以启动这条流水线。第二，按什么顺序跑：阶段与步骤如何分层，哪些串行、哪些并行，哪些阶段必须等待前置结果。第三，失败后怎么办：单步超时多久算失败、是否重试、失败后是停止还是继续、通知谁、是否回滚、哪些节点需要人确认后再往下走。
把这三个问题写清楚，流水线的行为才是可预期的。规则模糊时，同一次提交在不同时间可能得到不同结果，排查问题也无从下手。
执行规则管什么、不管什么
执行规则与发布准入、质量门禁容易混淆，区分方法是看作用对象：前者约束流水线怎么跑，后者判断某次构建能不能发。边界模糊时，问一句“这个问题问的是怎么跑，还是能不能发”，答案就清楚了。
| 事项 | 归属 | 典型内容 |
|---|---|---|
| 触发、编排、超时重试、失败处置、人工确认 | 流水线执行规则 | 推送触发构建、测试与构建并行、单步超时 20 分钟、失败后停止并通知 |
| 某次构建是否达到可发布标准 | 发布准入与质量门禁 | 测试覆盖率阈值、缺陷遗留数量、安全扫描结论、发布审批 |
| 流水线与外部平台的对接配置 | 工具链集成 | 与代码托管、制品库、通知渠道的连接与凭证管理 |
三者会互相引用，但职责不重叠。例如执行规则里可以设置“测试阶段失败即停”，这是运行行为；而“测试通过率低于 95% 不允许发布”属于质量门禁的放行判断。人工确认节点也常被误认为审批：确认节点决定流水线继续还是终止，审批决定这次构建能否进入发布，两者可以相邻，但判断依据不同。
触发条件：流水线在什么情况下启动
触发条件决定流水线的入口。常见方式有四类，选择时主要看反馈时效与资源成本的平衡。
| 触发方式 | 典型场景 | 适用考虑 |
|---|---|---|
| 代码事件触发 | 推送、合并请求、打标签 | 反馈最快，适合日常提交；合并请求触发可在合入前拦住问题，标签触发常用于版本发布 |
| 定时触发 | 夜间构建、定期回归 | 覆盖长时间未变更的分支和依赖升级带来的隐性失效，代价是发现问题偏晚 |
| 手动触发 | 按需执行、失败补跑 | 适合发布前验证和异常恢复，需要明确谁有权触发 |
| 上游流水线或外部事件触发 | 上游完成后接力、制品或接口回调 | 适合多仓库、多服务的串联交付，需关注上游失败时的传递行为 |
触发条件通常还要配套过滤规则，否则每次推送都全量执行会浪费资源。常见过滤维度包括分支（只对主干和发布分支执行完整流水线）、路径（只改文档时不跑构建）、提交信息（跳过标记为文档类的提交）。过滤规则要写清楚例外情况，避免紧急修复被误过滤。
串行、并行与依赖：阶段如何编排
流水线一般分两层：阶段（stage）和步骤（step）。阶段是逻辑分组，如构建、单元测试、集成测试、部署；步骤是阶段内的具体命令。层级关系决定了失败影响的范围——一个步骤失败通常导致所在阶段失败，是否影响后续阶段由规则决定。
串行保证顺序：构建完成才能测试，测试通过才能部署，这类前后依赖必须串行。并行用于压缩总时长：单元测试与静态检查互不依赖，可以同时跑。依赖关系显式声明后，平台才能判断哪些阶段必须等待、哪些可以同时启动，而不是靠人工排列顺序。
同一流水线被多次触发时，还需要并发控制策略，常见有三种：排队等待前一次结束、取消旧任务只保留最新一次、允许并行执行。主干分支通常选择取消旧任务，避免过期构建占用资源；发布分支可能选择排队，保证每次构建都有完整结果。此外，部署类阶段往往占用同一套环境或资源，需要互斥占用，防止两次部署同时操作同一环境造成状态混乱。
超时与重试：单步运行的兜底设置
超时针对单个步骤或整条流水线设置运行上限，防止任务因网络挂起、依赖无响应而长期占用执行资源。超时值应参考该步骤的正常耗时并留出合理余量，设得过短会误杀正常任务，设得过长则失去兜底意义。
重试需要配置次数与间隔。间隔设置的意义在于给瞬时故障恢复时间，固定间隔简单直接，递增间隔适合依赖服务正在恢复的场景。判断是否重试，关键看失败原因是否具有瞬时性：
- 适合重试：网络抖动、依赖包拉取超时、外部接口短暂不可用。
- 不适合重试：编译错误、测试断言失败、配置缺失。这类失败重试多少次结果都一样，只会拉长反馈时间。
重试还要考虑幂等性。重复执行不能产生重复副作用，例如重复创建制品版本、重复发送通知、重复写入外部系统。对非幂等步骤，应把重试范围限制在幂等的前置步骤，或先做清理再重试。
失败处理机制：出错之后怎么走
失败后的第一步是决定停还是继续。失败即停能尽快暴露问题、节省资源，适合构建和核心测试阶段；继续执行后续阶段则适合收集更多诊断信息的场景，例如多个独立测试套件并行时，让其余套件跑完再统一汇总。这个取舍应写进规则，而不是每次临时判断。
失败处置通常包含以下动作：
- 通知：明确通知对象（提交人、值班人员、负责团队）与渠道（即时消息、邮件、工单），避免通知发给无人关注的群组。
- 自动回滚或环境清理：部署阶段失败时，将环境恢复到上一可用版本，释放临时资源，防止半成品状态影响后续验证。
- 记录与日志留存：保留失败阶段的日志、退出码和产物，作为定位依据；日志保留时长应与排查周期匹配。
- 阻断后续发布动作：失败结果传递给发布环节，阻止该次构建继续进入发布流程。
这些动作可以组合。常见做法是核心阶段失败即停并通知，同时触发环境清理；非核心阶段失败则记录并继续，最后统一报告。
人工确认节点：哪些环节需要人把关
人工确认节点让流水线在指定位置暂停，等待人决定继续还是终止。典型位置有三处：生产部署前，确认变更内容和影响范围；高风险变更，如数据库结构修改、权限调整；跨环境推进，如从预发进入生产。
确认的内容是继续或终止，判断依据可以是变更说明、测试报告或值班安排，这与质量门禁的放行判断不同——门禁依据预设标准自动判定，人工确认由人承担责任。设置确认节点时要考虑超时与审批人缺席：确认超时后是自动终止还是自动继续，应有明确规定；审批人不在时要有替补机制，否则流水线会长期挂起。每次确认都应留下记录，包括确认人、时间、决定和理由，便于事后追溯。
一个具体例子：一次提交如何走完流水线
以下为演示情景，用于说明各要素如何衔接，不代表真实项目数据。
开发者向主干分支推送一次提交，触发规则匹配到主干分支，流水线启动。编排上，静态检查与单元测试并行执行，两者都通过后进入构建阶段，构建产物推送到制品库，随后进入集成测试。集成测试中某一步因依赖服务超时失败，该步骤配置了两次重试、间隔 30 秒，第二次重试成功，流水线继续。若重试仍失败，规则规定集成测试阶段失败即停，流水线终止，通知提交人与测试负责人，并清理本次占用的测试环境。
假设全部通过，流水线在部署到生产前遇到人工确认节点，值班人员查看变更说明和测试报告后选择继续，部署执行。整个过程结束后，运行结果与本次提交关联的工作项记录在一起。
这里有两个常见误解。其一，把执行规则当成质量门禁：流水线全部通过只说明运行成功，是否允许发布还要看门禁标准。其二，认为重试能解决所有失败：编译错误和断言失败重试无意义，只会延迟问题暴露。
规则落地时如何被记录和交接
执行规则写在配置文件里只是第一步，团队协作中还需要让变更可评审、结果可追溯、失败可流转。规则变更应走评审流程，说明改动原因和影响范围，并与代码变更一起记录，避免有人随意调整触发条件或超时值导致行为漂移。
流水线运行结果需要与需求、任务、缺陷关联起来，失败后的问题才能进入既有流程而不是停留在聊天记录里。ONES 支持集成 Jenkins、GitLab CI 等第三方流水线工具，集成后自动同步编排的流水线数据，更新执行状态和日志；流水线可与项目关联，在项目、迭代、需求中可视化代码提交、流水线构建、产品发布等 CI/CD 过程，帮助识别阻塞。团队还可以通过工作项拉取代码分支、用代码提交关联业务工作项，使一次失败构建能对应到具体需求和负责人。规则文档、评审记录和失败问题的处理过程可以在同一套工作项与文档中留存，形成从规则变更到问题闭环的交接链条。
常见问题
流水线执行规则和发布准入、质量门禁到底怎么区分？
看作用对象：执行规则约束流水线自身怎么跑，包括触发、编排、超时重试、失败处置和人工确认；发布准入与质量门禁判断某次构建能不能发，依据覆盖率阈值、缺陷遗留数量、安全扫描结论等标准。两者会互相引用，例如执行规则里设置“测试阶段失败即停”属于运行行为，而“测试通过率低于阈值不允许发布”属于放行判断。遇到边界模糊的问题，先问一句“问的是怎么跑，还是能不能发”。
重试次数设得越多是不是越保险？
重试只对瞬时性故障有意义，例如网络抖动、依赖包拉取超时、外部接口短暂不可用。编译错误、测试断言失败、配置缺失这类确定性失败，重试多少次结果都一样，只会拉长反馈时间、占用执行资源。配置重试时还要考虑幂等性：重复执行不能产生重复创建制品版本、重复发送通知、重复写入外部系统等副作用。对非幂等步骤，应把重试范围限制在幂等的前置步骤，或先清理再重试。
人工确认节点和发布审批是一回事吗？
两者相邻但判断依据不同。人工确认节点让流水线在指定位置暂停，由人决定继续还是终止，判断依据可以是变更说明、测试报告或值班安排，责任落在确认人身上。发布审批决定这次构建能否进入发布，通常依据预设的准入标准。设置确认节点时要明确超时后是自动终止还是自动继续，审批人缺席时要有替补机制，否则流水线会长期挂起；每次确认都应记录确认人、时间、决定和理由。
同一分支连续多次提交，流水线应该排队还是取消旧任务？
取决于分支用途。主干分支通常选择取消旧任务、只保留最新一次，避免过期构建占用执行资源，也能让开发者尽快拿到最新提交的反馈。发布分支可能选择排队等待，保证每次构建都有完整结果可供追溯。如果选择允许并行，需要确认并行任务之间不共享环境或制品版本，否则容易出现状态互相覆盖。部署类阶段往往占用同一套环境，应设置互斥占用。
规则改了之后怎么保证团队知道并遵守？
规则变更应走评审流程，说明改动原因和影响范围，并与代码变更一起提交和记录，避免有人随意调整触发条件或超时值导致行为漂移。运行结果要与需求、任务、缺陷关联，失败后的问题进入既有流程而不是停留在聊天记录里。ONES 支持集成 Jenkins、GitLab CI 等第三方流水线工具，集成后自动同步编排的流水线数据，更新执行状态和日志；流水线可与项目关联，在项目、迭代、需求中可视化代码提交、流水线构建、产品发布等 CI/CD 过程。团队还可以通过工作项拉取代码分支、用代码提交关联业务工作项，使一次失败构建对应到具体需求和负责人。
