GitHub 是代码托管与协作开发平台，与 ONES 通过原生代码集成把提交、合并请求和分支关联到工作项。本文针对国内版公有云手册描述的场景：一次最多获取 100 个仓库，多账号仓库总量超出时如何按账号分批关联，以及移除关联后的数据行为。私有部署版接入 GitHub 前需先联系 ONES 完成基础配置；具体部署版本与仓库权限请在实施前核对。
要点总览（TL;DR）
- ONES 手册中的“一次最多获取 100 个仓库”是 ONES 侧的获取范围，不是 GitHub 的仓库总上限；仓库总量超出时按 GitHub 账号拆分批次。
- 每个 GitHub 账号单独完成一次 OAuth 认证并选择该账号下的仓库，单批控制在 100 个以内，逐账号重复即可覆盖全部仓库。
- 移除某个仓库关联后，ONES 停止获取该仓库的新提交数据，此前已获取的历史数据保留；解绑只影响增量，不删除存量。
- 私有部署版接入 GitHub 前需先联系 ONES 完成基础配置，这一步与公有云启用流程不同。
100个仓库上限到底限制的是什么
这个 100 是 ONES 代码集成在单次获取仓库时的范围限制，属于 ONES 侧的配置边界。GitHub 平台本身可以承载远多于此的仓库数量，因此当组织在多个 GitHub 账号下拥有大量仓库时，需要规划的是“ONES 每次能纳入多少仓库”，而非 GitHub 账号的容量。
手册给出的处理方式是可按账号拆分关联：同一个 GitHub 账号下的仓库归入同一批次，每个批次控制在 100 个以内；账号数量多、单账号仓库也多时，就形成多个批次依次完成。这样每个批次都对应一次独立的 OAuth 认证与仓库选择，ONES 侧的获取范围就不会被单次上限卡住。
触发分批规划的条件很直接：把所有待接入仓库按 GitHub 账号归组后，任一账号的仓库数接近或超过 100，或者账号总数较多、需要分阶段推进。此时先做批次清单，再逐批配置，比一次性尝试全部接入更可控。
实施前需要满足两个前提：目标仓库已完成授权并具备可配置的 Webhook，执行人拥有代码集成配置权限。OAuth 的作用是取得配置仓库 Webhook 的权限；当 OAuth 授权范围不足时，需要在 GitHub 侧手工配置 Webhook。私有部署版还需先联系 ONES 完成基础配置，这一步与公有云的启用流程不同，不能直接套用。
按GitHub账号拆分关联的操作步骤
分批关联的核心思路是“一个账号一次认证、一次选仓”。每完成一个账号，就形成一个可核对的批次，再进入下一个账号。以下步骤按单批次描述，重复执行即可覆盖全部账号。
单批次操作流程
- 启用代码集成。在 ONES 配置中心启用代码集成。输入是具备配置权限的账号，动作是开启集成入口，输出是可用的代码集成配置页。
- 新增关联仓库。在代码集成配置中发起新增关联仓库，进入 GitHub 授权环节。此时确定本批次对应的 GitHub 账号，避免中途切换账号导致仓库列表混淆。
- 完成 OAuth 认证。使用该 GitHub 账号完成 OAuth 认证，授予配置仓库 Webhook 所需的权限。认证完成后，页面会列出该账号下可选择的仓库。
- 选择本批次仓库。在该账号的仓库列表中勾选本批次要接入的仓库，数量控制在 100 个以内，确认后保存关联。
- 处理授权不足。如果 OAuth 未能取得配置 Webhook 的权限，转到 GitHub 仓库设置中手工配置 Webhook，再回到 ONES 完成关联确认。
- 记录批次并重复。把本批次的账号、仓库清单、完成时间记入批次表，然后换下一个 GitHub 账号，从第 2 步重复。
每批的完成标志是：所选仓库在 ONES 中显示为已关联，且该仓库产生的新提交能够按规则关联到工作项。只看到“已关联”状态还不够，需要用一次真实提交验证数据链路是否打通。
批次清单建议字段
批次清单不需要复杂工具，一张表即可支撑后续核对与交接。建议包含：批次编号、GitHub 账号、本批仓库数、仓库名称清单、OAuth 是否完成、Webhook 配置方式（OAuth 自动或手工）、完成时间、验证人。仓库数一列用于确认每批不超过 100，Webhook 配置方式一列用于排查后续数据未进入的问题。
批次规划与角色分工
分批关联涉及配置权限和仓库归属两类信息，通常不在同一个人手上。把角色分清，可以避免“配置的人不知道哪些仓库该接、知道的人没有配置权限”的来回沟通。
| 角色 | 职责 | 交付物 |
|---|---|---|
| 代码集成配置负责人 | 执行启用集成、OAuth 认证、选择仓库、手工配置 Webhook | 已关联的仓库批次、配置记录 |
| 仓库归属确认人 | 按 GitHub 账号梳理仓库清单，确认哪些仓库需要接入、哪些已下线 | 按账号分组的仓库清单与优先级 |
| 验证人 | 用真实提交和合并请求验证关联是否生效 | 批次验收记录 |
批次排序可以按两个依据组合：先按 GitHub 账号分组，保证同一账号的仓库在同一批次内完成认证；组内再按业务优先级排序，把核心产品、活跃开发中的仓库放在前面。这样即使后续批次延后，关键仓库的提交与工作项关联已经可用。
私有部署版在启动第一批之前，需要先确认已联系 ONES 完成基础配置。这项前置工作通常有等待时间，应排在批次计划的最前面，避免配置负责人到位后无法开始。
移除仓库关联后新提交与历史数据怎么处理
移除某个代码仓库的关联后，ONES 停止获取该仓库的新提交数据，此前已经获取的历史数据保留。这意味着解绑是一个“停止增量、保留存量”的动作：仓库后续的提交不再进入 ONES，但已经关联到工作项的提交记录、合并请求记录仍然可以查看。
这个行为只描述移除仓库关联本身，不应外推为删除仓库相关的其他资源。如果团队需要清理历史关联，应作为独立的数据处理事项评估，不能假定解绑会自动完成。
仓库下线或迁移时，建议按以下顺序处理：先确认该仓库历史上关联的工作项是否仍需留存追溯，再决定是否移除关联；移除后核对没有新数据进入，同时抽查若干历史工作项，确认原有提交关联仍可查看。对于只是暂时不活跃、未来可能恢复的仓库，也可以保留关联，避免恢复时重新走认证与选仓流程。
完成检查清单
全部批次完成后，按以下条目逐项核对，每一条都能给出明确的是或否，便于交接和复盘。
- 每个 GitHub 账号对应的批次，仓库数均不超过 100。
- 每个批次的 OAuth 认证已完成；授权不足的仓库已手工配置 Webhook 并有记录。
- 抽查仓库的提交信息中包含 #工作项ID，且能在对应工作项上看到关联记录；一次关联多个工作项时以空格分隔的写法同样有效。
- 抽查合并请求，在标题或描述中写入 #工作项ID 后，工作项上出现对应关联。
- 已解绑的仓库没有新提交数据进入 ONES，历史关联记录仍可查询。
- 私有部署环境下，已确认联系 ONES 完成基础配置后再执行接入。
- 批次清单已归档，包含账号、仓库清单、配置方式与验证人。
如果希望代码事件进一步推动工作项状态，可以在工作项工作流步骤上配置分支创建、合并请求、提交关联等事件触发器。这类触发器需要显式配置，集成本身不会自动改变所有状态；同时手册说明触发器驱动的状态变化不执行步骤验证和步骤属性校验，但会执行后置动作，配置时应把这一差异纳入流程设计。
常见问题
OAuth 认证时提示权限不足，无法自动配置 Webhook 怎么办？
OAuth 的作用是取得配置仓库 Webhook 的权限。当授权范围不足时，可以转到 GitHub 仓库设置中手工配置 Webhook，再回到 ONES 完成关联确认。手工配置的仓库要在批次清单里单独标注配置方式，后续排查数据未进入的问题时，这一列能快速定位是自动还是手工配置的仓库。
同一个 GitHub 账号下仓库超过 100 个，能拆成多批关联吗？
可以按批次推进，但要注意 OAuth 认证与仓库选择是绑定在同一次关联动作里的。实践上把同一账号的仓库分成若干组，每组不超过 100 个，逐组完成认证与选仓，并在批次清单中记录账号、组别和仓库清单，避免重复或遗漏。手册描述的是单次获取范围，具体分批方式以目标部署版本的当前文档为准。
解绑仓库后，之前已经关联到工作项的提交记录还能查到吗？
可以。移除代码仓关联会停止获取该仓库的新提交数据，历史已获取的数据保留。已经关联到工作项的提交记录、合并请求记录仍然可以查看。这个行为只描述移除仓库关联本身，不涉及删除其他资源；如需清理历史关联，应作为独立的数据处理事项评估。
分批关联完成后，怎么确认某个仓库的数据链路真的通了？
只看“已关联”状态不够。用一次真实提交验证：提交信息中包含 #工作项ID，检查对应工作项上是否出现关联记录；一次关联多个工作项时以空格分隔。合并请求则在标题或描述中写入 #工作项ID，确认工作项上出现关联。两项都通过，才算该仓库的数据链路可用。
代码事件能自动推动工作项状态吗？
可以为工作项工作流步骤配置分支创建、合并请求和提交关联等事件触发器，但这需要显式配置，集成本身不会自动改变所有状态。另外手册说明触发器驱动的状态变化不执行步骤验证和步骤属性校验，但会执行后置动作，设计流程时应把这一差异考虑进去。
官方参考资料
- GitHub/公有 GitLab（ONES）
