这份验收清单用于研发平台与 GitLab 对接完成后的上线判定：按连接配置、身份与权限、数据同步、事件与 Webhook、异常与恢复、安全与审计六个阶段逐项核对，每项写明通过标准、所需证据和负责人。身份认证失败、事件丢失、重复写入、权限越界、审计缺失列为阻断项，全部通过并归档证据后才可判定对接上线。文中在验收项跟踪与证据归档环节会提到 ONES 的承载方式，具体版本与认证细节以实施前与厂商确认的结果为准。
要点总览（TL;DR）
- 验收对象是研发平台与 GitLab 之间的连接本身，按连接配置、身份与权限、数据同步、事件与 Webhook、异常与恢复、安全与审计六个阶段逐项核对，构建发布流程不在判定范围内。
- 每项检查都要写明可观察的通过标准、可定位的证据和到岗位的负责人；通过标准尽量写成阈值或可复核状态，避免“已配置”“运行正常”这类无法判定的表述。
- 身份认证失败、事件丢失、重复写入、权限越界、审计缺失五类问题列为阻断项，不通过即不能上线；其余问题约定整改时限，在上线后首次复验中核对。
- 整体完成条件是阻断项全部通过、证据归档到指定位置、四个角色签字确认；配置变更、实例升级、重大故障恢复和非阻断项整改到期都会触发复验。
- 验收项跟踪与证据归档可以借助 ONES 的工作项与文档能力承载，具体接口清单、对接支持的 GitLab 版本与部署形态需在实施前向厂商确认。
谁在什么时点使用这份验收清单
这份清单的验收对象是研发平台与 GitLab 之间的连接本身，包括地址可达、身份认证、数据同步、事件投递、异常恢复和审计留痕。构建发布流程如何编排、流水线如何设计，属于连接建立之后的研发流程管理，不在本清单的判定范围内。把边界先划清，可以避免验收会议被流程讨论带偏。
参与验收的角色按职责分工，不按部门人数分摊。平台管理员负责研发平台侧的配置、日志与同步任务；GitLab 管理员负责实例侧的项目可见性、令牌与 Webhook 配置；安全或审计人员负责凭证存储、权限边界与日志留存；业务验收人从实际使用角度确认需求、任务与代码活动的关联是否符合预期。四个角色各自对自己那部分证据签字，验收结论才站得住。
使用时点有三个：试运行结束、正式切换前做首次完整验收；对接配置发生变更（如更换令牌、调整同步范围、升级实例）后做复验；发生影响连接的故障并恢复后，对相关阶段做定向复验。日常巡检可以复用其中的检查项，但本清单的判定口径面向上线决策，不替代运维手册。
| 角色 | 首次验收（试运行结束、切换前） | 变更后复验 | 故障恢复后复验 |
|---|---|---|---|
| 平台管理员 | 负责 S2、S4、S5、S6 的配置与记录 | 核对变更涉及的连接与同步项 | 核对补同步与数据一致性 |
| GitLab 管理员 | 负责 S3、S5 的实例侧配置与权限 | 核对令牌、可见项目与 Webhook | 核对事件补发与密钥有效性 |
| 安全或审计人员 | 负责 S7 的凭证与日志检查 | 核对变更是否引入新的暴露面 | 核对异常期间日志完整性 |
| 业务验收人 | 负责 S4、S5 的关联结果确认 | 确认变更未影响工作项关联 | 确认恢复后关联结果正确 |
第一阶段：连接配置与网络可达性检查
连接阶段要回答的问题是：研发平台能否稳定访问 GitLab 的指定入口，并且在网络波动后自行恢复。检查从地址与入口开始：核对 GitLab 实例地址、API 访问路径与版本信息，确认研发平台配置的地址与实例实际对外提供的一致，避免因反向代理路径差异导致接口返回异常。
网络层面逐项确认防火墙放行规则、代理配置与超时设置。通过标准写成可观察结果，例如“从研发平台所在网段连续发起 3 次连接测试均成功，单次响应时间低于约定阈值”“代理断开后 5 分钟内自动恢复连接”。TLS 证书检查有效期与信任链，确认证书未临近到期、中间证书完整，避免因证书链缺失造成间歇性失败。
连接失败时的定位方式也要在验收阶段确认：错误码能否在研发平台日志中查到，GitLab 侧是否有对应的访问日志，双方日志能否按时间戳对齐。这一项常被忽略，直到故障发生才发现无从下手。
| 检查项 | 通过标准 | 证据 | 负责人 |
|---|---|---|---|
| 实例地址与 API 入口 | 配置地址与实例实际入口一致，接口探测返回正常 | 配置截图、接口探测结果 | 平台管理员 |
| 网络策略与代理 | 放行规则生效，代理断开后按约定时间恢复 | 防火墙规则导出、恢复测试记录 | 平台管理员 |
| TLS 证书 | 证书在有效期内，信任链完整，无到期告警 | 证书信息截图 | GitLab 管理员 |
| 失败定位方式 | 人为制造一次连接失败，双方日志均可定位到原因 | 日志片段 | 平台管理员 |
第二阶段：身份认证与权限范围检查
认证阶段确认对接使用的身份是谁、能做什么、如何收回。先明确对接账号类型：个人访问令牌、专用机器人账号或 OAuth 应用，不同方式在归属、有效期和审计上的表现不同。无论哪种方式，权限范围都应遵循最小化原则，只授予完成同步与事件接收所必需的读权限，写操作按实际需要单独评估。
令牌的有效期、轮换与吊销要形成可执行的约定。通过标准可以写成“令牌有效期不超过约定周期，轮换后旧令牌在约定时间内失效”“吊销操作在 10 分钟内生效并有记录”。可见项目范围同样要核对：对接账号能看到哪些项目，是否与业务约定的范围一致，是否存在因账号加入过大用户组而意外获得额外项目可见性的情况。
账号归属要落到具体岗位，离职或交接时有明确的处理动作。验收时检查账号的负责人字段是否填写、交接流程是否被记录。这一项看似行政，实际决定了后续权限审计能否追溯。
| 检查项 | 通过标准 | 证据 | 负责人 |
|---|---|---|---|
| 账号类型与权限范围 | 权限清单与业务约定一致，无多余写权限 | 权限配置导出 | GitLab 管理员 |
| 令牌有效期与轮换 | 有效期符合约定，轮换后旧令牌按时失效 | 轮换记录、失效验证截图 | 平台管理员 |
| 可见项目范围 | 可见项目与约定清单逐项一致 | 项目列表截图、比对记录 | GitLab 管理员 |
| 账号归属与交接 | 账号负责人为具体岗位，交接流程有记录 | 账号信息截图 | 安全或审计人员 |
第三阶段：项目、分支与提交数据同步检查
数据同步阶段验证研发平台读取到的 GitLab 项目结构与代码活动是否完整、准确、及时。检查项覆盖项目、分支、标签、提交四类对象，逐项确认同步范围与字段映射。字段映射要落到具体字段，例如提交哈希、作者、提交时间、关联分支分别对应研发平台的哪个字段，映射错误会在后续关联工作项时放大成难以排查的问题。
增量同步与全量同步的触发方式要分别验证：增量同步按什么条件触发、多久执行一次；全量同步在什么情况下手动执行、执行时长是否可接受。同步延迟设定可接受阈值，例如“代码提交后 10 分钟内可在研发平台查询到”，阈值由业务节奏决定，写进清单后作为判定依据。
抽样核对是这一阶段的核心证据。抽取若干项目、若干分支和若干提交，逐条比对两端记录，记录差异并说明处理约定：字段缺失时是补映射还是标记忽略，映射错误由谁修正、何时复验。抽样数量和抽样规则在验收前约定，避免验收时临时决定。
| 检查项 | 通过标准 | 证据 | 负责人 |
|---|---|---|---|
| 项目与分支同步 | 抽样项目与分支两端一致 | 抽样比对记录 | 平台管理员 |
| 提交字段映射 | 抽样提交的关键字段逐项一致 | 字段映射表、比对截图 | 平台管理员 |
| 增量与全量同步 | 两种方式均按约定触发并完成 | 同步任务日志 | 平台管理员 |
| 同步延迟 | 抽样提交在阈值内可查询 | 时间戳记录 | 业务验收人 |
在验收项跟踪环节，团队可以把上述检查项作为工作项录入 ONES，逐项指派负责人并附上比对记录；ONES 支持通过业务需求、研发任务等工作项拉取代码分支，并通过代码提交与工作项关联，验收时可以直接在关联结果中核对同步是否到位。具体配置步骤与字段映射规则以实施时的实际配置为准。
第四阶段：事件与 Webhook 投递检查
事件阶段验证 GitLab 侧的推送、合并请求等事件能可靠送达研发平台，并正确关联到对应工作项。先列出订阅的事件类型清单，逐类确认是否已配置、是否在验收范围内。清单之外的 event 不纳入本次判定，避免范围蔓延。
Webhook 的密钥或签名校验要在验收中实际验证：构造一次带正确签名的投递和一次签名错误的投递，确认前者被接收、后者被拒绝并有日志记录。事件到工作项的关联规则要写成可核对的对应关系，例如“合并请求标题或描述中的工作项编号决定关联对象”，并抽样验证关联结果。
投递失败的重试与补偿机制同样需要证据。通过标准可以写成“模拟接收端不可用 5 分钟后恢复，事件在约定时间内补投成功，无丢失”。抽样事件记录应包含事件类型、投递时间、接收时间、关联工作项和最终状态，作为验收归档材料。
| 检查项 | 通过标准 | 证据 | 负责人 |
|---|---|---|---|
| 订阅事件类型 | 清单内事件全部配置并触发成功 | Webhook 配置截图、触发记录 | GitLab 管理员 |
| 签名校验 | 正确签名被接收，错误签名被拒绝 | 两次投递的日志片段 | 平台管理员 |
| 工作项关联 | 抽样事件全部关联到正确工作项 | 抽样事件记录 | 业务验收人 |
| 失败重试与补偿 | 模拟故障后事件补投成功，无丢失 | 故障演练记录 | 平台管理员 |
第五阶段：异常、重复与恢复检查
前四个阶段走的是正常路径，这一阶段专门演练异常路径。断连场景的验证方法是主动中断网络或停用接收端，观察研发平台的重连行为与补同步结果，确认断连期间产生的数据在恢复后被补齐，且补齐过程有日志可查。
重复投递的幂等处理要实际测试：同一事件重复发送两次，确认研发平台只产生一条有效记录，或重复记录被明确标记。乱序事件的处理约定要写清楚，例如以事件时间戳还是提交顺序为准，冲突时以哪一方为准。故障恢复后的数据一致性核对，选取断连前后的抽样数据比对两端状态，确认没有遗漏或错位。
这一阶段的产出是异常场景演练记录表，每行记录场景、操作步骤、预期结果、实际结果和结论。演练未通过的项目按阻断项或整改项分类处理，不能以“机制已具备”代替实际演练。
| 异常场景 | 通过标准 | 证据 | 负责人 |
|---|---|---|---|
| 断连与重连 | 恢复后自动重连，断连期间数据补齐 | 演练记录、补同步日志 | 平台管理员 |
| 重复事件 | 重复投递不产生重复有效记录 | 重复投递测试记录 | 平台管理员 |
| 乱序事件 | 按约定规则处理，结果与规则一致 | 乱序测试记录 | 平台管理员 |
| 恢复后一致性 | 抽样数据两端一致 | 比对记录 | 业务验收人 |
第六阶段：安全、审计与合规检查
安全阶段确认凭证受控、操作可追溯、敏感内容可见范围符合约定。令牌与密钥的存储方式要核对：是否存放在受控的密钥管理位置，访问权限授予了哪些角色，是否存在明文出现在配置文件或日志中的情况。发现明文暴露按阻断项处理。
操作日志与同步日志的保留范围要明确到具体日志类型和保留时长，例如连接日志、同步任务日志、事件投递日志分别保留多久、谁能查看。私有仓库内容的可见范围单独核对：研发平台中哪些角色能看到代码内容与提交信息，是否与 GitLab 侧的可见性设置一致。
审计证据的导出与留存是验收收尾动作。确认日志可以按时间范围和对象导出，导出文件归档到指定位置，归档记录可被审计人员检索。审计缺失列为阻断项，因为事后追查能力无法在上线后补建。
| 检查项 | 通过标准 | 证据 | 负责人 |
|---|---|---|---|
| 凭证存储 | 无明文暴露，访问权限限于约定角色 | 配置检查记录 | 安全或审计人员 |
| 日志保留范围 | 各类日志按约定保留，可查询 | 日志配置截图 | 平台管理员 |
| 敏感内容可见范围 | 与 GitLab 侧可见性设置一致 | 权限比对记录 | 安全或审计人员 |
| 审计证据导出 | 可按范围导出并归档，归档可检索 | 导出文件与归档记录 | 安全或审计人员 |
通过标准、证据与负责人如何填写
填写规范决定了清单能否被判定，而不是变成一张勾选表。通过标准写成可观察结果或阈值：能给出数字的给数字，例如“连续 3 次重连均成功”“抽样 20 条事件全部关联正确”；不能给数字的写成可复核的状态描述，例如“错误签名投递被拒绝且日志中有对应记录”。避免“已配置”“运行正常”这类无法判定完成与否的表述。
证据类型按检查项选择：配置类用配置导出或截图，行为类用日志片段，结果类用抽样记录，权限类用比对表。证据要能定位到具体时间和对象，截图带时间戳，日志片段标注查询条件。负责人填写到岗位，例如“平台管理员”“GitLab 管理员”，不写“相关同事”或团队名称。
未通过项单独记录，写明现象、影响范围、整改责任人和复验时间。复验时只核对整改项及其关联项，不重复全量验收，但复验结论要回填到原记录，保持证据链连续。
一行示例：检查项“Webhook 签名校验”，通过标准“正确签名投递被接收，错误签名投递被拒绝且日志可查”，证据“两次投递的日志片段（含时间戳与请求标识）”，负责人“平台管理员”，结论“通过”，备注“错误签名日志位于接收服务 access log 第 3 行”。
阻断项与完成条件
阻断项是不通过即不能上线的检查项。本清单列五类：身份认证失败，包括令牌无效、权限不足导致同步中断；事件丢失，包括 Webhook 投递失败后未补投、抽样发现事件缺失；重复写入，同一事件或提交在研发平台产生重复有效记录；权限越界，对接账号可见范围超出约定或存在多余写权限；审计缺失，关键日志无法查询或无法导出归档。
非阻断项按整改时限处理，例如字段映射不完整、同步延迟略高于阈值、日志保留时长待调整，约定整改完成时间并在上线后首次复验中核对。整改时限由业务验收人与平台管理员共同确认，写进验收记录。
整体完成条件是：五类阻断项全部通过，所有检查项的证据已归档到指定位置，验收记录有四个角色的签字确认。满足后判定对接上线。复验触发条件包括对接配置变更、GitLab 实例升级、发生影响连接的重大故障，以及非阻断项整改到期。
| 阻断项 | 判定依据 | 不通过时的处理 |
|---|---|---|
| 身份认证失败 | 认证测试无法通过或同步因权限中断 | 停止上线，修复认证配置后重新验收 S3 |
| 事件丢失 | 抽样或演练发现事件未送达且未补投 | 停止上线，修复投递与补偿机制后复验 S5、S6 |
| 重复写入 | 重复投递产生重复有效记录 | 停止上线，落实幂等处理后复验 S6 |
| 权限越界 | 可见范围或写权限超出约定 | 停止上线，收敛权限后复验 S3、S7 |
| 审计缺失 | 关键日志不可查或不可导出归档 | 停止上线，补齐日志与归档后复验 S7 |
验收记录与证据的归档可以借助 ONES 的文档与工作项能力承载：把每个检查项建成工作项，附上比对记录和日志片段，验收结论随工作项状态流转，复验时按原记录回填。ONES 提供 API 接口用于与企业系统集成，也支持对接 GitLab 等成熟应用，具体接口清单、调用限制以及对接所支持的 GitLab 版本与部署形态，需在实施前向厂商确认后写入验收前提。
常见问题
验收时抽样核对的数量和规则应该提前定还是现场定？
建议在验收前由平台管理员与业务验收人共同约定，并写入验收记录。现场临时决定抽样范围，容易在出现差异时对“样本是否有代表性”产生争议。可操作的约定方式是：按项目类型分层抽取，覆盖活跃项目与低频项目；提交和事件按时间窗口抽取，覆盖正常时段与一次故障前后；抽样数量写成具体数字，例如“抽取 5 个项目、每项目 3 个分支、共 20 条提交”和“抽取 20 条事件”。抽样规则一旦确定，复验时沿用同一规则，便于前后对比。
对接使用的令牌快到期了，但验收还没走完，应该先轮换还是先完成验收？
先完成与令牌相关的验收项，再按约定周期轮换，轮换后对身份认证与数据同步做定向复验。令牌轮换本身会改变对接配置，属于复验触发条件，因此轮换动作要留下记录：新令牌的权限范围、生效时间、旧令牌失效时间，以及轮换后一次成功的同步和一次成功的事件投递。如果令牌在验收期间即将到期，可以在验收记录中注明轮换计划，避免上线后短期内再次触发复验而缺少准备。
Webhook 演练时模拟接收端不可用，补投成功但延迟超过了约定时间，算通过吗？
按清单的判定口径，这一项要看约定的阈值。如果通过标准写的是“恢复后约定时间内补投成功且无丢失”，延迟超出阈值就不算通过，应记录为整改项并写明实际延迟与影响范围；若事件在补投前已确认丢失，则按事件丢失列为阻断项。建议在验收前把“约定时间”写成具体数值，并说明该数值对应的业务容忍度，例如工作项状态更新允许的最大滞后。阈值未事先约定的，不应在演练后临时放宽。
GitLab 实例升级后，需要重新做全量验收吗？
不需要重复全量验收，但要做定向复验。实例升级可能影响 API 行为、Webhook 投递格式和权限模型，复验范围建议覆盖连接配置、身份认证、事件投递和异常恢复四个阶段，数据同步阶段做抽样比对即可。复验结论回填到原验收记录，保持证据链连续。如果升级同时调整了对接账号权限或 Webhook 配置，按配置变更处理，复验范围相应扩大。
验收记录和证据归档在哪里比较合适？
归档位置要满足两个条件：验收参与角色都能按权限查看，审计人员能按时间和对象检索。常见做法是把每个检查项建成工作项，附上比对记录、日志片段和配置导出，验收结论随工作项状态流转，复验时在原记录上回填。ONES 提供文档与工作项能力，可用于承载这类验收项跟踪与证据归档；具体配置方式以实施时的实际环境为准。
