流水线执行记录把一次运行的关键事实固定下来：谁触发、跑了哪条流水线、代码版本与产物是什么、各阶段结果如何、失败怎么处置、是否放行。本文给出一份已填写的示例记录，逐项解释字段取值与写法，并说明如何把它迁移成团队自己的记录模板。示例为演示情景，不对应真实团队数据。
要点总览（TL;DR）
- 流水线执行记录固定一次运行的关键事实：触发人与触发方式、代码版本与构建产物、各阶段结果、失败处置、结论与遗留事项。
- 示例记录覆盖记录头部、代码与产物、阶段结果、失败与处置、结论与放行五部分，可直接对照填写。
- 标识类字段（记录编号、构建号、提交号）保证唯一与可回溯；阶段状态建议统一为成功、失败、跳过、中止并写明判定条件。
- 迁移成团队模板时保留追溯主线的最小字段集，按流水线类型增删字段，并把记录与工作项、代码提交、构建产物建立关联。
- 记录描述运行事实，放行判断仍以发布审批与质量门禁结果为准；多环境并行时可按流水线×环境拆分记录。
这份示例要解决什么记录问题
一次流水线运行结束后，团队通常要回答三个问题：这次运行发生了什么、结果如何、谁处理了异常。口头交接和聊天记录能应付当下，隔几天再复盘或换人接手时，往往说不清当时用的是哪个提交、失败卡在哪个阶段、重跑后是否通过。流水线执行记录的作用，就是把这些问题对应的信息一次性写清楚，让复盘、追溯和交接都有据可查。
本文的示例设定如下：某研发团队维护一条名为“订单服务-主干构建”的流水线，开发人员提交代码后触发运行，编译阶段通过，单元测试阶段失败，修复后重跑通过并部署到测试环境。示例覆盖记录头部、代码与产物、阶段结果、失败与处置、结论与放行五个部分，展示一份记录从触发到收尾的完整形态。
需要说明的是，这份示例不涉及流水线平台与研发工具链的对接配置，也不讨论发布审批与质量门禁规则的设计。它只回答“一次运行该怎么记”，记录本身不能替代审批结论，这一点在后文适用边界中会再次说明。
完整示例：一次构建失败后重跑通过的流水线执行记录
以下是一份已填写的记录，字段前后自洽，可直接对照使用。表中时间为演示取值，不代表任何真实团队的运行数据。
记录头部
| 字段 | 填写内容 |
|---|---|
| 记录编号 | PLR-2024-0612-003 |
| 流水线名称 | 订单服务-主干构建 |
| 触发方式 | 代码提交自动触发 |
| 触发人 | 张明（提交人） |
| 开始时间 | 2024-06-12 14:05:18 |
| 结束时间 | 2024-06-12 14:41:52（含重跑） |
代码与产物
| 字段 | 填写内容 |
|---|---|
| 分支 | main |
| 提交号 | a3f9c21 |
| 构建号 | #1287（首次）、#1288（重跑） |
| 产物标识 | order-service:1.8.0-rc3（镜像标签） |
阶段结果
| 阶段 | 状态 | 耗时 | 说明 |
|---|---|---|---|
| 拉取代码 | 成功 | 12 秒 | 检出提交 a3f9c21 |
| 编译 | 成功 | 3 分 40 秒 | 无告警 |
| 单元测试 | 失败（首次） | 6 分 05 秒 | 2 个用例失败，见失败与处置 |
| 镜像构建 | 跳过（首次） | — | 前置阶段失败，未执行 |
| 部署到测试环境 | 跳过（首次） | — | 前置阶段失败，未执行 |
| 单元测试 | 成功（重跑） | 6 分 12 秒 | 修复后全部通过 |
| 镜像构建 | 成功（重跑） | 4 分 30 秒 | 产出镜像 order-service:1.8.0-rc3 |
| 部署到测试环境 | 成功（重跑） | 2 分 15 秒 | 测试环境已更新 |
失败与处置
失败阶段为单元测试。错误摘要：订单金额计算相关 2 个用例断言失败，实际返回值与预期相差 0.01，怀疑与本次提交中的舍入逻辑改动有关。定位线索：失败用例集中在金额精度处理模块，提交 a3f9c21 修改了该模块的舍入方式。处置动作：提交人回退舍入改动并补充边界用例，形成新提交 b7e2d04。重跑结果：构建号 #1288 基于 b7e2d04 运行，单元测试全部通过，后续阶段正常完成。
结论与放行
本次运行经重跑后可用于后续验证，测试环境已部署 1.8.0-rc3 版本。遗留事项：舍入逻辑的修复方案需在下次迭代评审中确认，补充的边界用例需纳入回归集。放行判断以发布审批与质量门禁结果为准，本记录仅提供运行事实。
逐项解释：每个字段为什么这样填
示例中的字段并非随意罗列，每一类都对应一个具体的追溯需求。理解取值依据，比照抄内容更重要。
标识类字段：保证唯一与可回溯
记录编号、构建号、提交号共同构成追溯链条。记录编号在团队内唯一，便于按编号检索；构建号对应流水线平台的一次具体运行，重跑会产生新构建号，因此示例中同时记录了 #1287 和 #1288；提交号指向确切的代码版本，是复盘时还原现场的依据。三者缺一，追溯就会断链：只有记录编号找不到代码，只有提交号说不清跑的是哪一次。
时间与耗时：先定口径再填数
开始时间取流水线实际启动时刻，结束时间取最后一次运行结束时刻。示例中结束时间标注“含重跑”，是因为首次运行与重跑之间存在人工修复间隔，若直接相减会得到失真的总耗时。阶段耗时取该阶段自身的执行时长，跳过阶段不填耗时，用“—”表示。团队应在模板中写明取数口径，例如是否包含排队等待时间，避免同一字段在不同记录中含义不同。
阶段状态：统一取值约定
示例使用成功、失败、跳过、中止四种取值。成功指阶段正常完成；失败指阶段执行报错或校验未通过；跳过指因前置条件不满足而未执行；中止指运行被人工或系统提前终止。四种状态需要写明判定条件，尤其是“跳过”与“失败”容易混淆：前置阶段失败导致后续未执行，应记跳过而非失败，否则统计失败率时会重复计数。
失败原因与处置：写到可复现的粒度
这一部分最容易写空。示例的写法包含四层信息：现象（哪两个用例、差多少）、定位线索（失败集中在哪个模块、哪次提交改动）、动作（回退并补充用例、形成新提交）、结果（重跑通过）。只写“测试失败已修复”，接手人无法判断问题是否真正解决，也无法在同类问题再现时快速定位。描述粒度以“另一个人能据此复现排查路径”为准。
结论与遗留事项：区分事实与判断
结论字段回答“这次运行的结果能否用于下一步”，示例写的是“可用于后续验证”，范围限定在测试环境验证，没有扩大到生产发布。遗留事项单独列出，把本次未闭环的问题显性化，避免随记录归档而消失。放行结论则明确指向审批与门禁，记录本身不承担放行职责。
从这份示例迁移到团队自己的记录模板
示例是参照，不是标准。迁移时先确定必须保留的字段，再按团队情况增删，最后把示例改造成空白模板并约定维护方式。
必须保留的最小字段集
无论团队规模如何，以下字段建议保留：记录编号、流水线名称、触发方式与触发人、开始与结束时间、分支与提交号、构建号、阶段结果、失败原因与处置、结论。理由是一致的：它们覆盖了“谁、何时、基于什么代码、跑了什么、结果如何、怎么处理”这条追溯主线，缺任何一环，记录在复盘或交接时都会出现断点。
可按流水线类型调整的字段
构建类流水线可强化产物标识与镜像标签；测试类流水线可增加用例总数、通过率与失败用例清单；部署类流水线可增加目标环境、部署版本与回滚标记。调整的原则是让字段服务于该流水线最常被追问的问题，而不是把所有流水线的字段堆进一张表。
记录与工作项、代码提交、构建产物的关联
记录如果孤立存放，检索成本会很高。较实用的做法是把记录与对应的需求或研发任务工作项、代码提交、构建产物建立关联，使读者从需求或提交出发就能找到相关运行记录。ONES 在完成与 Jenkins、GitLab CI 等第三方流水线工具集成后，会自动同步流水线数据并更新执行状态和日志，并可将流水线与项目关联，在项目、迭代、需求中查看代码提交、流水线构建、产品发布等过程。团队可以把记录中的记录编号、构建号与工作项对应起来，形成从需求到运行事实的检索路径。具体同步到哪些字段，需按实际集成情况核验。
保存位置与检索方式
保存位置的选择取决于团队现有工具链：与工作项同处一个协作平台，便于按需求检索；与代码仓库放在一起，便于按提交号检索。无论选哪种，都应保证记录编号可被搜索，且记录不会随流水线日志清理而丢失。检索方式建议至少支持按记录编号、提交号、流水线名称三种入口。
模板维护与字段演进
模板不必一次定型。可在每次复盘后收集“这次记录缺了什么、哪个字段没人填”，按季度调整一次。字段增删时保留历史记录的原有结构，新增字段从下一版模板启用，避免旧记录因模板变更而无法对照。模板版本号可写在记录头部，便于区分不同时期的记录格式。
适用边界：什么情况下这份记录需要调整
示例的价值在于示范写法，读者需要清楚它在哪些条件下需要调整，避免把演示情景当成通用标准。
首先，示例为演示情景，其中的时间、构建号、提交号与人员均为虚构，不代表任何真实团队的实际数据或运行效果。读者参照时应替换为自身流水线的真实取值，不应把示例中的耗时或通过情况当作基准。
其次，多环境、多流水线并行时，单条记录容易混杂。较清晰的做法是按“流水线×环境”拆分记录，再用一个汇总视图关联同一提交在各流水线的运行结果；若团队流水线数量较多，可只对主干流水线和发布流水线做完整记录，其余流水线保留阶段结果与结论字段。
再次，手工触发与自动触发场景的字段侧重点不同。自动触发时，触发人即提交人，重点在提交号与触发规则；手工触发时，应额外记录触发原因与操作人，因为手工运行往往对应补跑、验证或应急场景，缺少原因说明会让后续复盘难以判断这次运行的性质。
记录粒度还应与团队规模和发布频率匹配。发布频率低的团队可以按次完整记录；高频发布的团队若每次都写全量字段，维护成本会超过收益，可改为阶段结果自动采集、失败与处置人工补充的混合方式。
最后，记录不能替代发布审批与质量门禁结论。记录描述的是运行事实，放行与否仍应以审批流程和门禁规则的判定为准。把记录当作放行依据，会让事实描述与决策判断混在一起，两者应分开留存、相互引用。
常见问题
流水线执行记录和流水线日志有什么区别，两者都需要保留吗？
流水线日志是平台自动产生的原始输出，记录每个命令的执行过程和报错细节；流水线执行记录是人工或半自动整理的摘要，回答“这次运行发生了什么、结果如何、谁处理了”。两者用途不同：日志用于排查具体报错，记录用于复盘、追溯和交接。
建议两者都保留，并在记录中写明构建号，便于从记录跳转到对应日志。日志通常有保留期限，记录应独立存放，避免日志清理后失去运行事实。
团队发布频率很高，每次都写完整记录成本太大，有什么折中做法？
可以按流水线重要性分级。主干流水线和发布流水线保留完整字段；其余流水线只记录阶段结果、失败原因与结论，标识类字段由平台自动采集。失败与处置部分仍建议人工补充，因为这部分信息平台通常无法自动生成。
另一种做法是阶段结果自动采集、结论与遗留事项人工填写，把人工投入集中在判断类字段上。具体分级标准按团队的审计要求和复盘频率确定。
记录中的阶段状态，跳过和中止应该怎么区分？
跳过指该阶段因前置条件不满足而未执行，例如前置阶段失败导致后续阶段没有运行；中止指运行被人工或系统提前终止，阶段本身可能已经开始。两者都不算失败，但原因不同。
区分清楚的意义在于统计口径：把跳过计入失败会虚高失败率，把中止计入跳过会掩盖人为干预。团队应在模板中写明各状态的判定条件，并在记录中附一句原因说明。
记录应该保存在哪里，才能既方便检索又不随流水线日志清理而丢失？
常见选择有两类：与工作项同处一个协作平台，便于从需求或任务出发检索相关运行记录；与代码仓库放在一起，便于按提交号检索。选择取决于团队日常从哪个入口找信息。
无论选哪种，都应保证记录编号可被搜索，并至少支持按记录编号、提交号、流水线名称三种入口检索。ONES 在完成与 Jenkins、GitLab CI 等第三方流水线工具集成后，会自动同步流水线数据并更新执行状态和日志，并可将流水线与项目关联，在项目、迭代、需求中查看代码提交、流水线构建、产品发布等过程，可作为记录关联与检索的载体之一。具体同步字段需按实际集成情况核验。
多环境并行发布时，一条流水线执行记录够用吗？
单条记录容易混杂。较清晰的做法是按“流水线×环境”拆分记录，每条记录对应一个环境的一次运行，再用汇总视图关联同一提交在各环境的运行结果。
如果流水线数量较多，可只对主干和发布流水线做完整记录，其余流水线保留阶段结果与结论字段。拆分后仍应保留提交号作为跨记录关联的锚点，便于回答“这个提交在哪些环境跑过、结果如何”。
