GitHub 是代码托管与协作开发平台，通过仓库 Webhook 把提交、合并请求和分支事件推送给 ONES，由 ONES 侧完成与工作项的关联。接入前需要准备两类条件：ONES 侧具备代码集成配置权限的账号，以及 GitHub 仓库可用的 Webhook 授权。本文依据国内版公有云产品手册与 GitHub REST API 文档整理，私有部署版 ONES 的前置条件不同，且未在目标环境实测，具体版本与仓库权限仍需在实施前核对。
要点总览（TL;DR）
- 接入前先确认三件事：ONES 侧具备代码集成配置权限的账号、目标 GitHub 仓库可用的 Webhook 授权、以及部署形态对应的前置条件。
- OAuth 认证的作用是取得配置仓库 Webhook 的权限，它不替代 GitHub 仓库自身的访问控制；权限不足时改为在 GitHub 仓库手工配置 Webhook。
- 设置顺序为：配置中心启用代码集成、新增关联仓库并完成 OAuth、选择目标仓库；仓库选定后提交、合并请求和分支才具备关联工作项的前提。
- 使用私有部署版 ONES 接入 GitHub 时，手册要求先联系 ONES 完成基础配置，且不要与接入私有 GitLab 的流程混用。
- 验收以可观察证据为准：仓库出现在已关联列表、Webhook 已就位、带 #工作项ID 的提交与合并请求能在工作项上看到关联记录。
GitHub 与 ONES 的对接方向：哪些数据会流向哪里
先把方向定清楚，后面的授权准备才不会做偏。GitHub 在这条链路里是事件来源：仓库中发生提交、合并请求、分支创建等动作后，GitHub 通过仓库 Webhook 以 HTTP POST 方式把订阅的事件推送出去。GitHub 提供仓库 Webhook 的创建和管理接口，管理这些接口需要对应仓库的 Webhooks 权限。
ONES 是接收方和关联方。仓库集成完成后，GitHub 与公有 GitLab 的代码提交、合并请求和代码分支可以与 ONES 工作项建立关联。关联关系落在工作项上，研发人员在 ONES 里查看某个需求或任务时，能看到对应的代码提交与合并请求记录。若在工作流步骤上显式配置了分支创建、合并请求、提交关联等事件触发器，代码事件还可以驱动工作项状态变化；这类触发器需要单独配置，集成完成本身不会自动改变所有状态。
| 环节 | 承担方 | 动作或对象 | 前提 |
|---|---|---|---|
| 事件产生 | GitHub 仓库 | 提交、合并请求、分支 | 仓库存在且开发者正常推送 |
| 事件推送 | GitHub Webhook | HTTP POST 推送订阅事件 | Webhook 已创建并指向正确地址 |
| 接收与关联 | ONES | 代码提交、合并请求、代码分支关联到工作项 | 仓库已集成到 ONES |
| 状态联动（可选） | ONES 工作流 | 事件触发器驱动状态变化 | 已显式配置触发器 |
这条链路是单向的事件流入：GitHub 推送代码事件，ONES 接收并关联，不会把 ONES 的工作项数据反向写回 GitHub 仓库。把授权理解成“两边互相同步”会在准备阶段多配不必要的权限。本文流程以国内版公有云产品手册为准；使用私有部署版 ONES 时，前置配置要求不同，见下一节。
权限和前提：ONES 配置权限、OAuth 授权与仓库 Webhook 权限
接入前的权限准备可以拆成四项，各自解决不同问题，缺一项都会卡在某个具体环节。
ONES 侧：代码集成配置权限
操作账号需要具备代码集成配置权限，才能在配置中心启用代码集成并新增关联仓库。这项权限决定“能不能进入配置入口”，与 GitHub 仓库本身的访问权限是两回事。建议在动手前确认由谁持有该权限，避免配置到一半换人。
OAuth 认证：取得配置仓库 Webhook 的权限
OAuth 认证的用途是取得配置仓库 Webhook 的权限，让 ONES 能够在所选仓库上完成 Webhook 配置。它解决的是“配置 Webhook 这一步的授权”，不替代 GitHub 仓库自身的访问控制，也不改变仓库成员能看到什么代码。具体仓库权限以代码平台和 ONES 当前文档为准。
GitHub 侧：仓库 Webhooks 权限
如果走手工配置路径，操作者需要在 GitHub 仓库上具备管理 Webhook 的权限。GitHub 的仓库 Webhook 管理接口要求对应仓库的 Webhooks 权限，手工在仓库设置中创建 Webhook 时同样受仓库角色约束。事件订阅范围也要一并确认，只订阅业务需要的事件类型，减少无关推送。
部署形态：私有部署版的前置配置
使用私有部署版 ONES 接入 GitHub 或公有 GitLab 时，手册要求先联系 ONES 完成基础配置，再按公有云流程操作。这条前置不要与接入私有 GitLab 的流程混用，两者准备动作不同。
| 准备项 | 归属 | 用途 | 缺失时的后果 |
|---|---|---|---|
| 代码集成配置权限 | ONES 账号 | 启用代码集成、新增关联仓库 | 无法进入配置流程 |
| OAuth 认证 | ONES 配置过程 | 取得配置仓库 Webhook 的权限 | 自动配置 Webhook 失败，需改手工配置 |
| 仓库 Webhooks 权限 | GitHub 仓库 | 创建和管理仓库 Webhook | 手工配置路径无法完成 |
| 私有部署基础配置 | ONES 服务方 | 私有部署接入的前置条件 | 接入流程无法按公有云步骤推进 |
写具体操作教程前，仍需确认目标部署版本及仓库权限的实际状态。这部分属于资料核验缺口，准备阶段可以先把上述四项逐条打勾，再进入设置。
本阶段设置：启用代码集成、完成 OAuth 并选定仓库
权限确认后，设置动作按固定顺序推进，每一步都有明确的完成标志。
- 启用代码集成。在 ONES 配置中心找到代码集成并启用。完成标志：配置入口处于已启用状态，可以新增关联仓库。
- 新增关联仓库并发起 OAuth 认证。在新增仓库流程中完成 OAuth 认证，取得配置仓库 Webhook 的权限。完成标志：认证流程走完，系统可以读取账号下的仓库列表。
- 选择目标仓库。认证完成后从列表中选择要关联的仓库。手册描述一次最多获取 100 个仓库，这是 ONES 侧的获取范围，不是 GitHub 平台的仓库总上限；仓库较多时可按账号拆分关联。完成标志：目标仓库出现在已关联列表中。
- 确认关联前提成立。仓库选定后，提交、合并请求和分支才具备与工作项关联的前提。完成标志：可以在测试仓库中做一次带工作项编号的提交。
关联写法在准备阶段就应同步给开发人员，避免接入完成后才发现提交信息格式不统一。提交关联在 commit message 中使用 #工作项ID，一次关联多个工作项时以空格分隔；合并请求则在标题或描述中写入 #工作项ID，同样可关联多个工作项。工作项编号须有效，且源仓库已完成 ONES 集成，关联才会生效。
本阶段止于仓库关联完成。状态触发器属于后续配置，需要为具体工作流步骤单独设置，不在授权与 Webhook 准备范围内展开。
异常与重复处理：Webhook 权限不足、重复关联与解除关联
准备阶段常见的偏差集中在授权路径和关联边界上，按下表判断并处置。
| 现象 | 判断依据 | 处置动作 | 仍需确认 |
|---|---|---|---|
| OAuth 认证后无法自动配置 Webhook | 账号对目标仓库缺少配置 Webhook 的权限 | 改为在 GitHub 仓库手工配置 Webhook | 手工配置的地址与事件订阅范围是否与 ONES 要求一致 |
| 手工配置后收不到事件 | Webhook 未创建、地址错误或事件类型未订阅 | 核对仓库 Webhooks 权限与订阅事件范围 | 推送记录中是否有失败响应 |
| 同一工作项被多次写入 #工作项ID | 多次提交或合并请求指向同一工作项 | 以当前文档说明为准处理 | 重复关联的展示与去重细则，资料未给出，需在目标环境确认 |
| 需要停止某仓库的数据获取 | 仓库不再参与该项目的研发协作 | 移除代码仓关联 | 移除后该仓库新提交不再获取，历史已获取数据保留 |
| 触发器驱动状态变化后校验未执行 | 状态由代码事件触发器触发 | 验收时单独检查后置动作结果 | 触发器驱动的状态变化不执行步骤验证和步骤属性校验，但会执行后置动作 |
OAuth 自动配置与手工配置是两条适用条件不同的路径：前者依赖账号在目标仓库上的授权范围，后者由操作者自行在 GitHub 侧创建 Webhook，需要自行核对权限与事件订阅。两条路径选一条走通即可，不必同时保留。
解除关联只影响后续数据获取。移除代码仓关联会停止获取该仓库的新提交数据，历史已获取数据保留，因此不必担心解除后工作项上的历史代码记录消失。这条结论只描述移除仓库关联，不外推到删除仓库或其他资源。
可验证结果：接入准备完成的验收项
授权与 Webhook 是否真正就绪，用可观察的证据判断，逐项核对如下。
- 代码集成已启用。证据位置：ONES 配置中心的代码集成配置页。未通过时回到权限确认，检查操作账号是否具备代码集成配置权限。
- 目标仓库在已关联列表中。证据位置：代码集成的已关联仓库列表。未通过时检查 OAuth 认证是否完成、仓库是否在获取范围内。
- Webhook 已就位。证据位置：ONES 侧配置结果，或 GitHub 仓库设置中的 Webhook 列表。自动配置未成功时，确认手工 Webhook 已存在并指向正确地址。
- 提交关联可见。证据位置：工作项的代码提交关联记录。做一次带 #工作项ID 的提交，确认工作项上出现对应记录。
- 合并请求关联可见。证据位置：工作项的合并请求关联记录。在合并请求标题或描述中写入 #工作项ID，确认关联出现。
- 状态触发器符合预期（如已配置）。证据位置：工作项状态变化记录与后置动作结果。核对时留意触发器驱动的状态变化不执行步骤验证和步骤属性校验。
验收中未通过的项记录为待确认，并注明是权限、地址还是事件订阅的问题，不要直接判定为产品不支持。准备阶段完成后，开发人员按 #工作项ID 的写法提交代码，ONES 侧即可在工作项上持续积累代码提交、合并请求与分支的关联记录，为后续的评审与状态流转提供依据。
常见问题
OAuth 认证完成后仍然无法自动配置 Webhook，应该怎么处理？
先判断是不是账号对目标仓库缺少配置 Webhook 的权限。OAuth 认证的用途是取得配置仓库 Webhook 的权限，具体仓库权限以代码平台和 ONES 当前文档为准。权限不足时，改为在 GitHub 仓库手工配置 Webhook，由操作者自行核对仓库 Webhooks 权限与事件订阅范围。两条路径选一条走通即可，不必同时保留。
手工配置 Webhook 后收不到事件，排查顺序是什么？
按三个方向依次核对：Webhook 是否已在仓库中创建、目标地址是否与 ONES 要求一致、事件类型是否已订阅。GitHub 通过仓库 Webhook 以 HTTP POST 推送订阅事件，管理接口需要对应仓库的 Webhooks 权限，因此还要确认操作账号在仓库上的角色是否允许管理 Webhook。核对时可以查看推送记录中是否有失败响应。
私有部署版 ONES 接入 GitHub，准备阶段和公有云有什么不同？
手册要求使用私有部署版 ONES 接入 GitHub 或公有 GitLab 时，先联系 ONES 完成基础配置，再按公有云流程操作。这条前置不要与接入私有 GitLab 的流程混用，两者准备动作不同。具体到目标部署版本和仓库权限的实际状态，仍需在实施前确认。
解除某个仓库的关联后，工作项上已有的代码记录会消失吗？
不会。移除代码仓关联会停止获取该仓库的新提交数据，历史已获取数据保留。这条结论只描述移除仓库关联，不外推到删除仓库或其他资源。如果只是某个仓库不再参与该项目的研发协作，移除关联即可。
配置了代码事件触发器后，工作项状态变化为什么没有走步骤校验？
手册说明触发器驱动的状态变化不执行步骤验证和步骤属性校验，但会执行后置动作。这类触发器需要为具体工作流步骤显式配置，集成完成本身不会自动改变所有状态。验收时把状态变化记录与后置动作结果分开核对，就能判断是否符合预期。
官方参考资料
- GitHub/公有 GitLab（ONES）
- Repository webhooks REST API（GitHub）
