CircleCI 是持续集成与交付服务，可在工作流或任务完成时向配置地址发送 JSON Webhook。本文讨论的方案是自建接收服务：接收 CircleCI 构建事件，完成签名校验与字段映射后，调用 ONES 开放平台 REST API v2 建单或更新工作项。这条路线属于方案推导，尚未端到端实现；所读 ONES 国内版流水线集成手册目前只列 Jenkins，因此不能称为原生 CircleCI 集成。落地前需按目标部署核实 API 版本、凭据类型与作用范围、创建工作项的具体端点及事件去重键。
要点总览（TL;DR）
- 可落地路线是自建接收服务：CircleCI 在工作流或任务完成时推送 JSON Webhook，接收端校验签名、去重并映射字段，再调用 ONES 开放平台 REST API v2 建单或更新工作项。
- 这条路线属于方案推导，尚未端到端实现；所读 ONES 国内版流水线集成手册只列 Jenkins，不能称为原生 CircleCI 集成。
- 开工前要核实三件事：目标租户支持的 API 版本与创建工作项端点、使用个人 OAuth 凭据还是组织凭据（组织凭据文档标注 ONES 6.2.18+）、令牌刷新与 Scope 变更后的重新授权。
- 验收要覆盖正常与失败两条路径：重复事件不重复建单、写入失败可重试或人工补偿、Token 失效能单独告警，并保留事件日志与请求响应作为证据。
CircleCI 与 ONES 之间要传什么、往哪个方向传
先固定系统边界：CircleCI 是事件源，接收服务是中间层，ONES 工作项是写入目标。数据方向为单向，即 CircleCI 事件 → 接收服务 → ONES 工作项。接收服务承担三件事：校验事件来源、把构建结果映射为字段、调用 ONES API 完成写入。三者职责分开，才能避免把“Webhook 接收成功”误当成“工作项已更新”。
| 环节 | 角色 | 输入 | 输出 | 职责边界 |
|---|---|---|---|---|
| 事件源 | CircleCI 项目 Webhook | 工作流或任务完成 | JSON 事件推送 | 由项目管理员配置事件和接收端 |
| 中间层 | 自建接收服务 | CircleCI 事件 | 规范化后的工作项写入请求 | 签名校验、去重、字段映射、调用 ONES |
| 写入目标 | ONES 工作项 | 接收服务发起的 API 请求 | 新建或更新的工作项 | 按目标部署的接口契约执行 |
需要明确的是，这条路线属于自建方案。所读国内版流水线集成手册仅列 Jenkins，手册中可查看 Jenkins 流水线状态、运行步骤和日志，并关联项目及迭代，前提是先关联 Jenkins 服务并授予查看权限。这一事实说明国内版原生流水线集成当前覆盖的是 Jenkins，不能据此推断其他平台永久无法对接，也不能把本文方案称为 ONES 原生 CircleCI 集成。
接入前提：凭据、版本与权限边界
开工前需要把版本、凭据和权限三项条件核实清楚，任何一项不满足都会让后续联调停在鉴权或接口层。
API 版本与端点
ONES 开放平台提供 REST API v2，用于应用开发和系统集成，前提是目标租户支持对应 API 版本。文档使用 Bearer Token，接口路径示例为 /openapi/v2/，但这不是创建工作项的完整接口地址。国内开放平台入口与 COM 工作流引用的文档体系不能仅凭名称视为同一套接口契约，具体 HTTP 路径、参数及返回值必须按目标部署文档验证。创建工作项的端点在本文中属于待核验项。
凭据类型与作用范围
开放平台文档区分个人 OAuth 凭据和组织凭据，二者代表的身份及作用范围不同。组织凭据能力在文档中标为 ONES 6.2.18 及以上，实施前需确认实际版本、管理角色及授权范围。接收服务以什么身份写入工作项，会直接影响工作项的创建人、可见范围和操作记录，建议在方案评审阶段就确定，不要等到联调时再改。
令牌生命周期
个人 Token 刷新会产生新的访问和刷新令牌，旧令牌失效，自行实现的连接器需保存并使用新令牌。改变凭据 Scope 不会自动改变已发出的 Token，需重新授权使新范围生效。这两条意味着接收服务需要具备令牌存储与更新能力，并且不能只改配置就假定权限已经扩大。
- 确认目标租户支持的 API 版本，并取得对应部署的接口文档。
- 确定使用个人凭据还是组织凭据，记录身份与作用范围。
- 核对 ONES 版本是否满足组织凭据的 6.2.18+ 条件。
- 为接收服务设计令牌保存、刷新与失效告警机制。
- 在目标部署文档中确认创建工作项与更新工作项的端点、必填字段。
接收服务与字段映射怎么设计
接收端的处理顺序建议固定为：签名验证 → 解析事件类型与构建状态 → 去重判断 → 字段映射 → 调用 ONES API → 记录结果。顺序固定后，每一步的失败都能定位到具体环节，不会出现“事件收到了但工作项没变”的模糊状态。
接收端处理流程
- 接收 CircleCI 推送的 JSON 事件，先做签名验证，验证不通过直接拒绝并记录。
- 解析事件类型，区分工作流完成与任务完成，提取构建状态。
- 按事件去重键判断是否已处理过同一构建，已处理则跳过写入。
- 把构建结果映射为目标工作项字段。
- 调用 ONES API 建单或更新，记录请求与响应。
字段映射草案
下表是映射草案，字段名与取值规则需在验证阶段按实际事件载荷和 ONES 工作项字段配置确认。
| 构建信息 | 建议映射到工作项 | 待确认项 |
|---|---|---|
| 项目或仓库标识 | 工作项所属项目或自定义字段 | 与 ONES 项目标识的对应关系 |
| 分支 | 自定义字段 | 字段类型与可选值 |
| 构建编号 | 标题或自定义字段 | 是否作为去重键的一部分 |
| 构建状态 | 状态字段或自定义字段 | 成功、失败等状态与 ONES 取值的对应 |
| 完成时间 | 日期时间字段 | 时区与格式 |
| 构建链接 | 链接字段或描述 | 字段长度与可点击形式 |
建单还是更新已有工作项，取决于能否从事件中稳定定位目标工作项。如果事件里只有仓库和分支信息，通常需要接收服务维护一张“构建标识—工作项”的对应关系；如果团队约定每个分支固定对应一个工作项，则可以在映射表中直接配置。这一点需在验证阶段确认，不能先假定可以自动匹配。调用 ONES API 建单或更新任务属方案推导，尚未端到端实现。
重复事件、失败重试与异常处理
CircleCI 官方文档提供签名验证及重试说明，接收端需考虑重复事件。核心原则是把“接收成功”和“写入成功”分开记录：接收服务返回 2xx 只代表事件已被收下，工作项是否更新要看 ONES API 的响应。
| 异常类型 | 典型表现 | 处置方式 |
|---|---|---|
| 重复事件 | 同一构建的事件被多次投递 | 按去重键做幂等判断，已处理则跳过写入 |
| 鉴权失败 | Token 失效或 Scope 变更后仍用旧授权 | 单独告警，刷新令牌或重新授权后重放 |
| 写入失败 | 接口报错、字段校验不通过 | 进入重试队列，超过次数转人工补偿 |
| 字段缺失 | 事件载荷缺少映射所需字段 | 记录原始事件，标记为待补数据，不写入残缺工作项 |
去重键的设计需要保留可稳定识别同一构建的标识，例如项目标识与构建编号的组合。具体用哪些字段组成去重键，属于资料核验缺口，需在验证阶段结合事件载荷确定。写入失败进入重试或人工补偿队列时，应保留原始事件便于重放，避免为了重试而要求 CircleCI 重新推送。Token 失效或 Scope 变更导致的鉴权失败要与业务写入失败分开告警，因为两者的处理人不同。
如何验证这条链路真的跑通
验收要覆盖正常路径和失败路径，并以记录作为证据，不能只看一次成功截图。
- 用测试项目触发一次工作流完成事件，确认接收端收到事件且签名校验通过。
- 核对 ONES 工作项字段与构建结果一致，记录请求与响应。
- 重复投递同一事件，验证不产生重复工作项。
- 模拟写入失败，验证重试队列与人工补偿路径可用。
- 模拟 Token 失效，验证鉴权失败告警能触达负责人。
- 模拟字段缺失的事件，验证系统不会写入残缺工作项。
证据记录建议包含：事件接收日志、签名校验结果、发给 ONES 的请求与响应、生成或更新的工作项记录、重试与告警记录。闭环测试与 CN 创建/更新工作项接口仍属资料缺口，验收前需补齐目标部署的接口文档并完成一次完整联调，才能把这条链路标记为可用。
常见问题
CircleCI 的 Webhook 接收成功，是否就代表 ONES 工作项已经更新？
不代表。接收服务返回 2xx 只说明事件已被收下，工作项是否变化要看调用 ONES API 的响应。方案上应把接收状态与写入状态分开记录，写入失败进入重试或人工补偿队列，并保留原始事件便于重放。
接收服务用个人凭据还是组织凭据写入工作项，会影响什么？
两者代表的身份与作用范围不同，会直接影响工作项的创建人、可见范围和操作记录。组织凭据能力在文档中标为 ONES 6.2.18 及以上，实施前需确认实际版本、管理角色与授权范围。建议在方案评审阶段就确定写入身份，避免联调时再改。
令牌刷新或调整 Scope 后，接收服务需要做什么？
个人 Token 刷新会产生新的访问和刷新令牌，旧令牌失效，自行实现的连接器需保存并使用新令牌。改变凭据 Scope 不会自动改变已发出的 Token，需重新授权使新范围生效。因此接收服务要具备令牌存储与更新能力，不能只改配置就假定权限已经扩大。
事件去重键应该怎么定？
去重键需要能稳定识别同一次构建，例如项目标识与构建编号的组合，具体字段要结合 CircleCI 实际事件载荷确定。这部分属于资料核验缺口，需在验证阶段确认后再固化到接收服务中，避免同一构建重复建单。
ONES 国内版目前是否已有 CircleCI 的原生流水线集成？
所读国内版流水线集成手册仅列 Jenkins，手册中可查看 Jenkins 流水线状态、运行步骤和日志，并关联项目及迭代，前提是先关联 Jenkins 服务并授予查看权限。这一事实说明原生流水线集成当前覆盖 Jenkins，不能据此推断其他平台永久无法对接，也不能把本文方案称为原生 CircleCI 集成。
官方参考资料
- ONES Open API v2（ONES）
- Open API Authentication And Authorization（ONES）
- Outbound webhooks（CircleCI）
- 流水线集成（ONES）
