GitHub 是代码托管与协作开发平台，它与 ONES 通过代码集成，把代码提交、合并请求和代码分支关联到工作项，让代码活动回到需求与任务的上下文中。本文按国内版公有云产品手册说明关联写法与入口选择；私有部署接入 GitHub 前需先联系 ONES 完成基础配置，具体部署版本与仓库权限仍需在实施前确认。
要点总览（TL;DR）
- GitHub 提交在 commit message 中写 #工作项ID，合并请求在标题或描述中写 #工作项ID，多个工作项用空格分隔。
- 入口按开发阶段分工：提交对应编码留痕，合并请求对应评审与合入汇总，两者可以同时使用。
- 关联生效的前提是仓库已完成 ONES 代码集成，并通过 OAuth 取得配置 Webhook 的权限；权限不足时需手工配置 Webhook。
- 私有部署接入 GitHub 前需先联系 ONES 完成基础配置，该流程与接入私有 GitLab 不同。
关联入口怎么选：提交与合并请求的分工
开发团队可以把两个入口按开发阶段分工使用：日常编码时在提交信息里写工作项编号，形成细粒度的代码留痕；进入评审与合入环节时，在合并请求的标题或描述里写工作项编号，把一次评审所覆盖的工作项集中挂到合并请求上。两者可以同时使用，同一批代码既在提交层面留下记录，也在合并请求层面形成汇总关联。
选择入口的判断依据是“这次关联要回答什么问题”。如果想知道某个工作项对应哪些具体改动，提交层面的关联更直接；如果想知道某个工作项是在哪次评审中合入的、评审范围包含哪些工作项，合并请求层面的关联更合适。团队不必在两者之间做取舍，而应约定各自在什么阶段由谁写入。
| 入口 | 写入位置 | 关联对象 | 适用阶段 | 多工作项写法 |
|---|---|---|---|---|
| 代码提交 | commit message | 本次提交与工作项 | 编码与提交阶段 | 多个 #工作项ID 之间以空格分隔 |
| 合并请求 | 合并请求标题或描述 | 本次合并请求与工作项 | 评审与合入阶段 | 多个 #工作项ID 之间以空格分隔 |
这张表只解决“在哪里写”。关联能否生效，还取决于仓库是否已经集成到 ONES，这属于下一节的前置条件。
关联前的准备：仓库集成与授权
关联生效的前提是源仓库已完成 ONES 代码集成。按国内版公有云产品手册的流程，在配置中心启用代码集成，新增关联仓库，完成 OAuth 认证后选择仓库。这一步需要代码集成配置权限，执行人通常是项目管理员或负责研发工具链的成员。
OAuth 认证的作用是取得配置仓库 Webhook 的权限。如果当前账号权限不足，无法通过 OAuth 完成 Webhook 配置，就需要在代码平台侧手工配置 Webhook。GitHub 提供仓库 Webhook 的创建和管理接口，以 HTTP POST 推送订阅事件，管理这些接口需要对应仓库的 Webhooks 权限。实际可用的权限范围以代码平台和 ONES 当前文档为准。
仓库数量上，手册描述一次最多获取 100 个仓库，这是 ONES 侧的获取范围，并非 GitHub 平台的仓库总数上限。仓库较多的团队可以按账号拆分关联，分批完成。
部署形态不同，准备动作也不同：
- 公有云部署：按配置中心的代码集成流程操作，完成 OAuth 认证并选择仓库。
- 私有部署：接入 GitHub 前需先联系 ONES 完成基础配置，再按对应流程关联仓库；这一流程与接入私有 GitLab 的流程不同，不要混用。
准备阶段的完成标志是：目标仓库出现在 ONES 的关联仓库列表中，且 Webhook 已配置成功。此时再开始写关联标记，才能被正确识别。
写法示例：单工作项与多工作项关联
关联的锚点是工作项编号。提交在 commit message 中写 #工作项ID，合并请求在标题或描述中写 #工作项ID。工作项编号必须有效，且所在仓库已关联到 ONES，否则标记不会被识别为关联。
单工作项的提交信息示例：
fix: 修正登录态过期后的跳转逻辑 #12345一次提交涉及多个工作项时，用空格分隔编号：
feat: 补充导出字段与权限校验 #12345 #12346合并请求标题示例：
feat: 订单导出支持自定义字段 #12345合并请求描述中也可以写关联标记，适合把评审范围一次说清：
本合并请求完成以下工作项：
- 导出字段配置 #12345
- 导出权限校验 #12346
验证方式：本地构造两类角色分别导出，检查字段与权限是否符合预期。写法上有两点容易出错：编号写成任务标题或需求名称不会被识别；多个编号之间用逗号或顿号分隔也不符合“空格分隔”的规则。团队可以把提交信息模板放进仓库的提交规范或合并请求模板，减少手工遗漏。
团队落地约定与完成检查
把写法固化为约定，关键是明确“谁在什么阶段写、由谁检查”。一种可执行的分工是：开发人员在每次提交时写本次改动对应的工作项编号；提交合并请求的人在标题或描述中写本次评审覆盖的工作项编号；评审人合入前检查合并请求中的关联标记是否齐全、编号是否有效。团队规模较小时，评审人检查即可；协作方较多时，可以再指定一名成员定期抽查关联完整度。
团队约定条目可以这样写：
- 提交信息格式：类型前缀 + 简述 + 空格 +
#工作项ID，多个编号以空格分隔。 - 合并请求要求：标题或描述至少包含一个有效工作项编号，覆盖本次评审的全部工作项。
- 责任人：提交人负责提交层关联，合并请求发起人负责评审层关联，评审人负责合入前核对。
- 例外处理：紧急修复也需补写关联标记，可在合并后补充说明中补齐。
关联失败时，按以下顺序排查常见原因：
- 工作项编号无效，或编号不属于当前项目。
- 仓库尚未关联到 ONES，或关联后 Webhook 未配置成功。
- 标记写法不符合规则，例如缺少
#、多个编号未用空格分隔。
如果团队调整仓库范围，移除代码仓关联会停止获取该仓库的新提交数据，历史已获取的数据会保留。这一行为只针对移除仓库关联，不涉及其他资源的删除。
完成检查清单：
- 目标仓库已在 ONES 代码集成中完成关联，Webhook 配置成功。
- 提交信息与合并请求模板中已加入关联标记写法。
- 团队已明确提交人、合并请求发起人、评审人的关联职责。
- 抽取最近若干次提交与合并请求，确认工作项页面能看到对应代码记录。
- 私有部署环境已确认完成 ONES 侧基础配置，且未与私有 GitLab 接入流程混用。
需要说明的是，上述流程依据国内版公有云产品手册整理，未在目标环境实测；实施前请确认部署版本与仓库权限，再按团队实际流程落地。
常见问题
提交和合并请求都写了工作项编号，会不会重复关联同一个工作项？
两个入口关联的是不同对象：提交关联的是本次提交与工作项，合并请求关联的是本次合并请求与工作项。同一个工作项既可能被某次提交关联，也可能被包含它的合并请求关联，这属于两个层面的记录，可以并存。团队按阶段分工写入即可，不需要为了去重而只保留其中一个入口。
OAuth 认证时权限不足，关联还能做吗？
可以继续推进，但需要换一种方式配置 Webhook。OAuth 的作用是取得配置仓库 Webhook 的权限；当前账号权限不足、无法通过 OAuth 完成配置时，需要在代码平台侧手工配置 Webhook。GitHub 提供仓库 Webhook 的创建和管理接口，管理这些接口需要对应仓库的 Webhooks 权限。具体可用的权限范围以代码平台和 ONES 当前文档为准。
仓库很多，一次关联不完怎么办？
手册描述一次最多获取 100 个仓库，这是 ONES 侧的获取范围，并非 GitHub 平台的仓库总数上限。仓库数量超过这个范围时，可以按账号拆分关联，分批完成。分批关联不影响已关联仓库的提交与合并请求关联，新加入的仓库在完成关联并配置好 Webhook 后再开始写关联标记即可。
调整仓库范围、移除某个仓库关联后，之前的代码记录会消失吗？
移除代码仓关联会停止获取该仓库的新提交数据，历史已获取的数据会保留。这一行为只针对移除仓库关联，不涉及其他资源的删除。如果只是暂时停止同步，移除关联可以达到目的；如果之后需要继续获取新数据，需要重新完成关联与 Webhook 配置。
私有部署环境下，关联写法与公有云一样吗？
关联写法本身一致，差异在准备阶段。使用私有部署版 ONES 接入 GitHub 或公有 GitLab 时，手册要求先联系 ONES 完成基础配置，再按对应流程关联仓库。这一流程与接入私有 GitLab 的流程不同，不要混用。实施前还需确认目标部署版本与仓库权限，本文依据国内版公有云产品手册整理，未在目标环境实测。
官方参考资料
- GitHub/公有 GitLab（ONES）
- Repository webhooks REST API（GitHub）
