流水线执行记录要能回答三个问题：这次跑的是哪个版本、每个阶段结果如何、失败后谁在什么时间做了什么处置。本文给出一份演示情景下的完整填写范例，逐项说明执行标识、触发来源、代码版本、阶段结果、失败处置、产物去向等字段的填写口径，并说明换一条流水线时哪些结构可以保留、哪些内容需要按团队约定调整。
要点总览（TL;DR）
- 流水线执行记录按“单次执行一条记录”组织，核心字段包括执行标识、触发方式与触发人、代码版本、阶段状态与耗时、失败原因与处置、产物版本与部署去向、关联工作项与变更单。
- 示例演示一次构建失败后重跑通过的完整过程：首次执行在单元测试失败，制品打包与部署标记为未执行；重跑沿用同一提交号，通过关联执行字段与首次记录互相指向。
- 填写口径的关键是统一取值：阶段状态固定为成功、失败、未执行、已取消；代码版本以提交号为主、分支名为辅；失败原因写到可定位的任务或用例层级。
- 迁移到自己的流水线时，阶段划分随流水线结构调整，字段结构保持稳定；可先人工填写验证字段是否够用，再把系统可输出的字段改为自动采集。
- 示例适用于单条流水线、顺序阶段的追溯；多环境并行部署、发布准入与质量门禁、外部平台对接、合规审计等场景需要扩展字段或转到相邻主题处理。
示例目标：这份执行记录要解决什么问题
这份示例记录服务于单次流水线执行的追溯。团队在排查一次构建失败、确认某个版本是否已部署到测试环境，或回溯某次变更为何被放行时，通常需要快速回答四个问题：谁触发了这次执行、跑的是哪个代码版本、卡在哪一步、失败后如何处置。记录围绕这四个问题组织字段，让阅读者在一条记录内完成判断，不必再到多个系统之间拼接信息。
记录粒度定位为“单次流水线执行一条记录”。同一分支连续触发多次，就产生多条记录，通过执行标识区分；一次执行内部的多个阶段和任务，作为该条记录的子项呈现，不拆成独立记录。这样既保证追溯时能按执行次数定位，也避免记录数量膨胀到难以查询。
需要说明的是，本文示例为演示情景，其中的项目名称、提交号、人员、时间与产物版本均为示意，用于展示字段结构和填写方式，不代表任何真实客户案例或实测结果。阅读时可以把示例当作一张填写模板：先看整体结构，再对照第三节的口径逐项替换为自己流水线的实际内容。
本文聚焦交付流执行记录本身。流水线与具体平台的对接配置、发布准入与质量门禁规则设计，属于相邻主题，本文不展开，只在适用边界一节说明它们与执行记录的分工。
完整示例：一次构建失败后重跑通过的执行记录
下面是一份字段齐全、前后自洽的示例记录。情景设定为：开发人员向订单服务仓库的 release/2.4 分支提交修复，触发流水线执行；首次执行在单元测试阶段失败，修复后重跑通过，并部署到测试环境。示例中“重跑”作为同一次交付意图下的第二次执行单独记录，两条记录通过关联字段互相指向。
| 字段 | 首次执行（失败） | 重跑执行（通过） |
|---|---|---|
| 执行标识 | PL-20250612-0031 | PL-20250612-0034 |
| 流水线名称 | order-service-cd | order-service-cd |
| 触发方式 | 代码推送自动触发 | 手动重跑 |
| 触发人 | 李××（提交人） | 王××（值班开发） |
| 代码仓库与分支 | order-service / release/2.4 | order-service / release/2.4 |
| 代码版本 | 提交 8f3c2a1 | 提交 8f3c2a1（未变更代码，仅重跑） |
| 关联工作项 | ORD-1873 订单超时重试逻辑修复 | ORD-1873 |
| 关联变更单 | CHG-0452 | CHG-0452 |
| 阶段一：构建 | 成功，耗时 2 分 10 秒 | 成功，耗时 2 分 08 秒 |
| 阶段二：单元测试 | 失败，耗时 3 分 42 秒，失败节点：订单重试用例组 | 成功，耗时 3 分 55 秒 |
| 阶段三：制品打包 | 未执行 | 成功，耗时 1 分 20 秒 |
| 阶段四：部署到测试环境 | 未执行 | 成功，耗时 1 分 05 秒 |
| 失败原因 | 订单重试用例断言超时阈值不匹配，测试代码未同步更新 | — |
| 处置动作 | 补充测试用例阈值配置，提交 4d9e7b2 到同一分支 | 确认修复后手动重跑 |
| 处置人 / 时间 | 李×× / 2025-06-12 14:26 | 王×× / 2025-06-12 14:51 |
| 产物版本号 | 无产物 | order-service-2.4.3-rc1 |
| 部署去向 | — | 测试环境 test-cluster-01 |
| 总耗时 | 5 分 52 秒 | 8 分 28 秒 |
| 执行结论 | 失败，已处置 | 成功 |
| 关联执行 | 后续执行 PL-20250612-0034 | 前序执行 PL-20250612-0031 |
这份记录的关键在于前后自洽：首次执行失败在单元测试，因此制品打包与部署阶段标记为未执行而非失败；重跑执行沿用同一提交号，说明代码未变、失败来自测试配置；产物版本号与部署去向只在成功执行中出现，避免把未产出的制品写成已部署。关联执行字段让两次执行形成一条完整的处置链，阅读者从任一记录都能找到另一次。
逐项解释：每个字段为什么这样填
字段的价值取决于填写口径是否统一。同一团队里，如果一个人把阶段状态写成“挂了”，另一个人写“失败”，查询和统计就无法进行。下表对示例中的关键字段给出填写口径与常见写法，可作为团队约定的起点。
| 字段 | 填写口径 | 常见写法与注意点 |
|---|---|---|
| 执行标识 | 由流水线系统生成、全局唯一的编号，包含日期便于人工检索 | 如 PL-20250612-0031；避免使用“第几次执行”这类会随重跑变化的序号 |
| 触发方式与触发人 | 记录是代码推送、定时、手动还是上游流水线触发；触发人写实际操作者 | 自动触发时触发人为提交人；手动重跑时写重跑操作者，两者区分开才能还原处置过程 |
| 代码版本 | 优先写提交号，需要对外说明时补充标签 | 提交号唯一且不可变，标签可能被移动；同时记录分支名，便于判断版本来源 |
| 阶段状态 | 使用统一取值：成功、失败、未执行、已取消 | “未执行”与“失败”含义不同，前者表示前序阶段未通过而未进入，不能混用 |
| 失败原因 | 写到可定位的层级：哪个阶段、哪个任务或用例、什么现象 | 只写“失败”无法支撑排查；示例写到用例组和断言不匹配，接手人可直接复现 |
| 处置动作与处置人 | 记录失败后做了什么、谁做的、什么时间做的 | 处置与重跑通过“关联执行”字段串联，形成一条可读的处置链 |
| 产物版本号 | 记录本次执行实际产出的制品标识 | 失败执行无产物时明确写“无产物”，避免下游误以为存在可部署包 |
| 部署去向 | 记录制品部署到的环境或集群标识 | 与产物版本号成对出现，回答“这个版本现在在哪里” |
| 关联工作项与变更单 | 填写需求、缺陷或变更单编号 | 让执行记录能反向追溯到业务意图，排查时知道这次改动为什么发生 |
关于版本字段，一个常见疑问是写提交号还是标签。提交号指向确定的代码快照，适合作为追溯主键；标签适合对外发布说明，但标签可能被重新指向，单独使用会削弱可追溯性。示例采用“提交号为主、分支名为辅”的写法，需要发布说明时再补标签。
关于失败原因与处置的分离，二者回答不同问题：失败原因说明系统当时发生了什么，处置动作说明人做了什么干预。把两者写在同一格，重跑后就难以区分“原始故障”和“人为修复”，复盘时容易把处置措施误当成故障原因。
可迁移规律：换一条流水线怎么改这份示例
示例中的字段结构可以迁移，阶段划分需要按实际流水线调整。构建、单元测试、制品打包、部署到测试环境是示例流水线的四个阶段；换成前端项目可能增加静态检查，换成多服务项目可能拆成并行阶段。调整时保留“阶段名称、状态、耗时、失败节点”这组字段，阶段数量随流水线变化，字段结构保持稳定，这样不同流水线的记录仍可用同一套方式查询和对比。
状态取值与失败分类需要团队统一约定。建议在流水线配置或记录模板中固定枚举值，例如成功、失败、未执行、已取消，并为失败补充分类，如代码缺陷、测试用例问题、环境异常、依赖不可用。分类不必一开始就很细，先覆盖团队最常遇到的几类，再按复盘需要扩充。
记录与工作项、变更单的关联方式，决定了追溯能否闭环。常见做法是在提交信息中引用工作项编号，由流水线在触发时自动带入记录；变更单编号则在提交变更申请时登记。ONES 的研发管理与交付过程记录能力可以把流水线执行与需求、缺陷、变更等工作项放在同一处查看，团队在排查某次失败时，从工作项即可看到关联的执行记录与处置过程，减少在多个系统间核对编号的成本。这一衔接适合已经用工作项管理需求与缺陷的团队；若团队的工作项管理在别处，保留编号字段同样能实现基本追溯。
记录保留周期与查询入口也应提前约定。保留周期取决于复盘和审计需要，常见做法是覆盖最近若干个发布周期；查询入口要能让开发和测试按分支、版本、时间或工作项检索，而不是只能按执行标识逐条翻找。
从人工补录过渡到自动采集，可以分两步走：先按本文结构人工填写几条真实执行记录，验证字段是否够用、口径是否清晰；再把能由流水线系统输出的字段（执行标识、触发方式、阶段状态、耗时、产物版本）改为自动写入，人工只补充失败原因、处置动作和关联工作项。这样过渡期记录不会中断，字段口径也在人工阶段先达成一致。
适用边界：哪些情况这份示例不够用
这份示例面向单条流水线、单次执行、顺序阶段的追溯场景。遇到以下情况，需要在示例基础上扩展字段或转到相邻主题处理。
- 多环境、多集群并行部署。示例只有一个部署阶段和一个部署去向。当一次执行同时向多个环境或集群发布时，需要把部署去向拆成多条部署明细，分别记录环境、集群、版本和结果，并补充各明细的完成时间与状态。
- 发布准入与质量门禁。示例只记录执行结果，不判断是否允许发布。涉及发布审批、门禁规则、放行条件的设计，属于发布审批与质量门禁主题，执行记录在其中承担证据角色，规则本身不在本文范围。
- 与外部平台对接。示例不包含流水线与代码托管、制品库、部署平台之间的对接配置，也不涉及具体工具的版本兼容结论。这类内容属于研发工具链集成主题。
- 合规审计场景。示例未考虑记录的不可篡改、留存期限和访问控制要求。审计场景通常需要额外的日志留存策略、操作留痕和权限约束，应在示例字段之外单独设计。
把示例当作字段结构的起点，而不是通用标准，是使用它的合适方式。团队可以先按示例填写一到两条真实记录，检查是否覆盖了日常排查所需的信息，再决定增加哪些字段、固定哪些取值。字段够用、口径一致、能支撑复盘，这份记录就达到了目的。
常见问题
流水线执行记录里，重跑应该单独记一条还是更新原记录？
建议单独记一条，并用关联字段把前后两次执行串起来。重跑意味着一次新的执行过程，触发人、触发时间、各阶段耗时和结果都可能不同，覆盖原记录会丢失首次失败的信息，复盘时就看不到“原始故障”和“人为修复”的区别。
示例中首次执行 PL-20250612-0031 与重跑执行 PL-20250612-0034 各自成条，通过“关联执行”字段互相指向。查询时从任一记录都能找到另一次，处置链保持完整。如果团队希望按交付意图聚合查看，可以在查询或报表层按关联工作项、变更单分组，记录本身仍保持一次执行一条。
代码版本字段写提交号还是写发布标签？
以提交号为主，需要对外说明时补充标签，同时记录分支名。提交号指向确定的代码快照，唯一且不可变，适合作为追溯主键；标签便于阅读，但可能被重新指向，单独使用会削弱可追溯性。
示例采用“提交 8f3c2a1 + release/2.4 分支”的写法，重跑时沿用同一提交号，正好说明代码未变、失败来自测试配置。若团队有发布标签规范，可在提交号之外并列记录标签，两者不冲突。
失败原因和处置动作能不能写在同一个字段里？
建议分开。失败原因说明系统当时发生了什么，处置动作说明人做了什么干预，两者回答不同问题。写在同一格，重跑后就难以区分原始故障和修复措施，复盘时容易把处置当成故障原因。
示例中失败原因写到“订单重试用例断言超时阈值不匹配，测试代码未同步更新”，处置动作写“补充测试用例阈值配置，提交 4d9e7b2 到同一分支”，并记录处置人和时间。接手人据此既能复现问题，也能看到问题是如何被解决的。
团队刚开始记录，字段一次要填全吗？
不必一次填全，但执行标识、代码版本、阶段状态、失败原因与处置这几项建议先固定下来，它们直接支撑日常排查。产物版本、部署去向、关联变更单等字段可以按团队实际流程逐步补齐。
过渡期可以先按示例结构人工填写几条真实执行记录，检查字段是否覆盖了排查所需的信息、口径是否清晰；再把流水线系统能输出的字段（执行标识、触发方式、阶段状态、耗时、产物版本）改为自动写入，人工只补充失败原因、处置动作和关联工作项。这样记录不中断，字段口径也在人工阶段先达成一致。
一次执行同时部署到多个环境，记录怎么调整？
示例只有一个部署阶段和一个部署去向，适用于单环境顺序部署。当一次执行同时向多个环境或集群发布时，把部署去向拆成多条部署明细，每条分别记录环境、集群、版本、结果和完成时间，阶段状态按明细汇总。
如果还涉及发布审批和门禁放行条件，那部分规则属于发布审批与质量门禁主题，执行记录在其中承担证据角色。记录本身只需保证每个环境的部署结果可查、可对应到具体版本。
