GitHub 是代码托管与协作开发平台，与 ONES 通过代码集成把提交、合并请求和分支关联到工作项。本文面向私有部署版 ONES 接入 GitHub 的前置准备，手册要求先联系 ONES 完成基础配置；目标部署版本与仓库权限仍需在实施前确认，本文未做目标环境实测。
要点总览（TL;DR）
- 私有部署版 ONES 接入 GitHub 前，手册要求先联系 ONES 完成基础配置，清单的第一件事就是确认基础配置由谁完成、以什么形式交付。
- 与实施方确认四类事项：部署与基础配置、ONES 侧代码集成配置权限与 GitHub 仓库授权、提交与合并请求的关联规则及事件触发器、接入后的回调验收。
- GitHub 侧通过 OAuth 取得配置仓库 Webhook 的权限，权限不足时需安排手工配置 Webhook，提前定好执行人和目标仓库。
- 集成完成后状态不会自动全部改变，事件触发器要逐条显式配置；触发器驱动的状态变化不执行步骤验证和步骤属性校验。
- 阻断项清零才算准备完成：基础配置未确认、无代码集成配置权限、Webhook 权限无法取得且未安排手工配置、版本与手册不一致未澄清。
这份清单由谁在什么时点使用
这份清单用于接入实施启动前和配置完成后的验收两个时点。它解决的是“谁去问、问什么、拿到什么算通过”，具体检查项放在后续四个阶段。私有部署版 ONES 接入 GitHub 时，手册明确要求先联系 ONES 完成基础配置，因此清单的第一使用人是负责发起对接的项目管理员或代码集成配置人，由他带着问题与 ONES 实施方逐项确认。
私有部署的接入流程与接入私有 GitLab 的流程不同，不能把私有 GitLab 的 Application 配置步骤直接搬过来。清单只覆盖私有部署版 ONES 接入 GitHub 这一条件，公有云版的完整操作教程、GitHub Actions 等 CI/CD 流水线配置不在本文范围内。
| 角色 | 在清单中的职责 | 主要确认时点 |
|---|---|---|
| ONES 项目管理员 | 提出接入需求，确认工作项关联规则与状态流转预期 | 实施启动前 |
| 代码集成配置人 | 执行 ONES 侧配置，核对权限与仓库范围 | 实施启动前、配置完成后 |
| GitHub 仓库管理员 | 提供仓库授权，必要时手工配置 Webhook | 实施启动前、授权阶段 |
| ONES 实施方 | 完成私有部署基础配置，答复版本与升级相关问题 | 实施启动前、验收时 |
第一阶段：部署与基础配置确认项
这一阶段只处理私有部署特有的前置问题，不涉及仓库授权。核心判断是：基础配置是否已由 ONES 实施方完成并有明确交付形式，配置中心代码集成入口在目标环境中是否可用。手册描述的启用路径是在配置中心启用代码集成、新增关联仓库、完成 OAuth 认证后选择仓库，这一路径需要代码集成配置权限，私有部署环境是否同样具备该入口，应由实施方在目标环境中确认。
| 检查项 | 通过标准 | 证据 | 负责人 |
|---|---|---|---|
| 目标部署版本与当前手册描述的差异 | 实施方书面说明版本差异及对代码集成的影响 | 版本说明或邮件确认 | ONES 实施方 |
| 基础配置完成范围与交付形式 | 明确由实施方完成哪些配置、以何种形式交付 | 配置交付记录 | ONES 实施方 |
| 配置中心代码集成入口可用 | 目标环境中能看到并进入代码集成配置 | 配置界面确认记录 | 代码集成配置人 |
| 后续升级或变更时配置是否需重做 | 实施方给出升级影响说明与操作建议 | 升级说明 | ONES 实施方 |
第二阶段：账号权限与仓库授权确认项
这一阶段确认两边的权限是否到位。ONES 侧需要代码集成配置权限；GitHub 侧通过 OAuth 认证取得配置仓库 Webhook 的权限。权限不足时需要手工配置 Webhook，因此要提前约定由谁执行、在哪个仓库执行。GitHub 提供仓库 Webhook 的创建和管理接口，以 HTTP POST 推送订阅事件，管理接口需要对应仓库的 Webhooks 权限，这一点可作为与仓库管理员沟通的依据。
仓库范围也要提前定清楚。手册描述一次最多获取 100 个仓库，可按账号拆分关联，这是 ONES 侧的获取范围，并非 GitHub 平台的仓库总量限制。接入前应列出需要接入的仓库清单及其账号归属，超过单次范围时按账号拆分安排。
| 检查项 | 通过标准 | 证据 | 负责人 |
|---|---|---|---|
| ONES 侧代码集成配置权限 | 配置人账号可进入并操作代码集成配置 | 权限确认记录 | 代码集成配置人 |
| GitHub 侧 OAuth 授权 | 认证完成，具备配置仓库 Webhook 的权限 | 授权结果记录 | GitHub 仓库管理员 |
| 权限不足时的手工 Webhook 安排 | 明确执行人、目标仓库与配置方式 | 手工配置记录 | GitHub 仓库管理员 |
| 仓库清单与账号归属 | 清单完整，超过 100 个时已按账号拆分 | 仓库清单 | 代码集成配置人 |
第三阶段：关联规则与状态触发器的确认项
关联规则决定提交和合并请求能否被识别到工作项。提交信息中使用 #工作项ID，一次关联多个工作项时以空格分隔；合并请求在标题或描述中写入 #工作项ID，同样可关联多个工作项。这两条规则需要提前告知开发人员，并确认工作项编号有效、源仓库已完成集成。
状态流转依赖显式配置。可为工作项工作流步骤配置分支创建、合并请求和提交关联等事件触发器，集成完成后不会自动改变所有状态，需要逐条确认哪些步骤挂哪些触发器。这里有一处校验差异需要写入风险提示：触发器驱动的状态变化不执行步骤验证和步骤属性校验，但会执行后置动作。对于依赖必填属性或步骤校验来控制质量的流程，应评估这一差异是否可接受。
| 检查项 | 通过标准 | 证据 | 负责人 |
|---|---|---|---|
| 提交关联规则 | 开发人员知晓 #工作项ID 写法与多工作项空格分隔 | 规则通知记录 | ONES 项目管理员 |
| 合并请求关联规则 | 标题或描述写入 #工作项ID 的约定已确认 | 规则通知记录 | ONES 项目管理员 |
| 事件触发器配置清单 | 逐条列出工作流步骤与对应触发器 | 触发器配置记录 | 代码集成配置人 |
| 校验差异风险确认 | 相关流程负责人已知悉不执行步骤验证与属性校验 | 风险确认记录 | ONES 项目管理员 |
第四阶段：回调与验收确认项
验收要能逐项判断通过，而不是凭感觉认为“接好了”。仓库关联后，提交与合并请求应能关联到对应工作项；已配置的事件触发器应按预期改变工作项状态。Webhook 投递异常时，需要事先约定排查责任方，并保留手工配置 Webhook 的回退路径。另外确认移除仓库关联后的行为：停止获取该仓库的新提交数据，历史已获取数据保留。
| 验收项 | 通过标准 | 证据 | 负责人 |
|---|---|---|---|
| 提交关联工作项 | 带 #工作项ID 的提交出现在对应工作项下 | 关联记录截图 | 代码集成配置人 |
| 合并请求关联工作项 | 标题或描述含 #工作项ID 的合并请求完成关联 | 关联记录截图 | 代码集成配置人 |
| 事件触发器生效 | 触发后工作项状态按配置变化 | 触发器配置与状态记录 | ONES 项目管理员 |
| Webhook 异常处理路径 | 排查责任方与手工配置回退方式已明确 | 处理约定记录 | GitHub 仓库管理员 |
| 移除关联后的数据行为 | 确认停止获取新提交、历史数据保留 | 行为确认记录 | 代码集成配置人 |
阻断项与完成条件
以下情况未解决时，不应进入接入实施：基础配置未由 ONES 实施方确认完成；配置人不具备代码集成配置权限；仓库 Webhook 权限无法取得且未安排手工配置；目标部署版本与手册描述不一致且未澄清。前三项直接决定能否完成关联，第四项影响后续操作步骤是否适用。
整体完成条件是四个阶段的检查项全部有证据并通过，阻断项清零，并由项目管理员与实施方共同确认验收结果。目标部署版本与仓库权限属于实施前仍需确认的遗留缺口，应在启动会上明确责任人和确认时间，不能以“应该没问题”代替书面结论。
| 阻断项 | 放行条件 |
|---|---|
| 基础配置未确认 | 实施方给出完成确认与交付记录 |
| 无代码集成配置权限 | 权限已授予并验证可操作 |
| Webhook 权限无法取得 | 手工配置方案已落实执行人 |
| 版本与手册不一致 | 差异已澄清并形成书面说明 |
常见问题
私有部署版 ONES 接入 GitHub，为什么不能照搬私有 GitLab 的 Application 配置步骤？
手册对私有部署版 ONES 接入 GitHub 或公有 GitLab 的要求是先联系 ONES 完成基础配置，并明确提示不要与接入私有 GitLab 的流程混用。私有 GitLab 的 Application 配置属于另一条接入路径，其步骤、授权方式和前置条件与 GitHub 接入并不对应。把私有 GitLab 的步骤套到 GitHub 上，容易出现授权对象错位、Webhook 配置位置不对的问题。稳妥做法是以实施方针对目标环境给出的配置说明为准，清单中只记录需要确认的问题和通过标准。
OAuth 授权完成后，是否一定不需要再手工配置 Webhook？
不一定。手册的描述是 OAuth 用于取得配置仓库 Webhook 的权限，权限不足时需手工配置 Webhook。也就是说 OAuth 是取得权限的途径，能否覆盖全部待接入仓库取决于授权结果和具体仓库权限。准备阶段应把“权限不足时由谁手工配置、在哪些仓库配置”写成明确安排，并在验收时确认 Webhook 投递正常。具体仓库权限以代码平台和 ONES 当前文档为准。
接入仓库数量较多时，100 个仓库的限制该怎么处理？
手册描述一次最多获取 100 个仓库，可按账号拆分关联。这是 ONES 侧的仓库获取范围，并非 GitHub 平台的仓库总量上限。准备阶段先列出需要接入的仓库清单和账号归属，超过单次范围时按账号拆分，分批完成关联。清单里应写清每批对应的账号和仓库，避免实施时临时清点。
触发器自动改变工作项状态时，会不会跳过必填属性校验？
手册说明触发器驱动的状态变化不执行步骤验证和步骤属性校验，但会执行后置动作。对于依赖必填属性或步骤校验来控制质量的流程，这一差异需要在配置触发器前评估：哪些步骤适合挂代码开发事件触发器，哪些步骤应保留人工流转。确认结果应形成风险确认记录，由流程负责人知悉后再配置。
验收时怎样判断提交和合并请求真的关联到了工作项？
用实际提交和合并请求做验证：提交信息中带 #工作项ID，合并请求在标题或描述中写入 #工作项ID，然后到对应工作项下查看是否出现关联记录。多个工作项一次关联时以空格分隔，可一并验证。除关联记录外，还要确认已配置的事件触发器按预期改变了工作项状态，并保留关联记录截图和触发器配置记录作为验收证据。
官方参考资料
- GitHub/公有 GitLab（ONES）
- Repository webhooks REST API（GitHub）
