GitLab是代码托管与研发协作平台，与ONES通过仓库关联、OAuth授权和Webhook事件对接，把提交、合并请求和分支与工作项串起来。本文按GitLab公有/私有与ONES公有云/私有部署的组合区分路线，依据国内版公有云产品手册整理，资料核验日期为2026-10-27，未做目标环境实测，版本兼容与仓库数量约束仍需在目标环境复核。
要点总览（TL;DR）
- 公有GitLab接入由ONES配置中心发起：具备代码集成配置权限后启用代码集成、新增关联仓库、完成OAuth认证并选择仓库，授权重点是取得配置仓库Webhook的权限。
- 私有GitLab接入多出网络与管理员环节：先确认ONES与私有服务网络互通，由GitLab管理员创建Application并填入ONES给出的Redirect URI，按api、read_user、read_repository、write_repository授权后再完成OAuth与Webhook。
- ONES私有部署接入公有GitLab时，手册要求先联系ONES完成基础配置，这一步与接入私有GitLab的流程不同，两条路线不宜交叉拼接。
- 接入完成后两条路线共享同一套关联规则：提交与合并请求用#工作项ID关联，状态流转需显式配置触发器，触发器驱动的状态变化不执行步骤验证和步骤属性校验。
- 上线前需在目标环境复核私有GitLab版本兼容矩阵、单次仓库获取范围与多私有服务关联方式，本文未做目标环境实测。
两条接入路线的同口径差异对照
两条路线的分界首先在GitLab的部署形态：公有GitLab由ONES配置中心发起仓库关联，授权动作集中在ONES侧完成；私有GitLab需要GitLab管理员先在私有服务里创建Application，再回到ONES完成OAuth。准备工作的重心因此不同，公有路线看ONES配置权限，私有路线看网络互通与GitLab管理员配合。
| 比较维度 | 公有GitLab | 私有GitLab |
|---|---|---|
| 前置条件 | 操作者具备代码集成配置权限 | ONES与私有GitLab服务网络互通；GitLab管理员可创建Application |
| 发起位置 | ONES配置中心启用代码集成，新增关联仓库 | 私有GitLab创建Application，填入ONES给出的Redirect URI |
| 授权主体 | ONES侧具备配置权限的操作者 | GitLab管理员创建应用，ONES侧用户完成OAuth认证 |
| 授权范围 | OAuth取得配置仓库Webhook的权限 | api、read_user、read_repository、write_repository |
| Webhook来源 | OAuth授权后由集成配置；权限不足时手工配置Webhook | 完成OAuth认证后配置Webhook |
| ONES部署形态叠加 | ONES为私有部署时，手册要求先联系ONES完成基础配置 | 同样以网络互通为前提，流程与公有路线分开 |
表中每一行的依据都来自国内版公有云产品手册对两条路线的分别描述。需要留意最后一行：ONES私有部署接入公有GitLab时多出的“联系ONES完成基础配置”是公有路线的附加步骤，不能搬到私有GitLab流程里使用，两条路线的步骤也不宜交叉拼接。
公有GitLab接入前的准备与授权顺序
公有GitLab路线的准备动作集中在ONES一侧，可以按下面顺序推进，每一步都有明确的完成状态。
- 确认操作账号具备代码集成配置权限。这是整条链路的前提，缺少该权限时后续步骤无法在配置中心发起。
- 在ONES配置中心启用代码集成。完成标志是代码集成入口处于可用状态。
- 新增关联仓库并发起OAuth认证。OAuth的作用是取得配置仓库Webhook的权限，认证通过后即可在列表中选择目标仓库。
- 核对Webhook是否配置成功。若OAuth取得的权限不足，转为手工配置Webhook，具体仓库权限以代码平台和ONES当前文档为准。
- 确认仓库已集成。此后该仓库的提交、合并请求和分支才可与工作项关联。
这条链路里没有GitLab管理员创建Application的环节，授权动作由ONES侧发起并完成。若在第三步认证后看不到预期仓库，先回到权限核对，而不是直接跳到手工Webhook配置。
私有GitLab接入前的准备与授权顺序
私有GitLab路线多出网络、应用创建和权限核对三个环节，其中应用创建必须由GitLab管理员完成，ONES侧用户无法替代。
- 确认ONES与私有GitLab服务网络互通。这是私有路线独有的前置条件，网络不通时后续授权无法完成。
- 由GitLab管理员在私有GitLab创建Application，把ONES给出的Redirect URI填入。回调地址必须使用当前ONES环境给出的值，不能复制其他租户的回调地址。
- 按api、read_user、read_repository、write_repository配置应用权限，并由实际GitLab管理员逐项核对。
- 在ONES侧完成OAuth认证，随后配置Webhook。私有GitLab的提交、合并请求、分支关联与开发事件状态触发，都以仓库认证和Webhook配置完成为前提。
版本方面，当前所读手册标注私有GitLab 11.10及以上版本，这是手册记录，目标部署的当前兼容矩阵仍需核实。另外，手册描述一个ONES账号认证一个私有GitLab服务，存在多个私有服务时需要由不同ONES用户分别关联，实施前应复核当前版本是否仍适用这一约束。
ONES部署形态如何改变接入路线
把ONES自身形态叠加进来后，路线判断变成两个变量的组合，而不是只看GitLab一侧。
| ONES形态 | GitLab形态 | 路线要点 |
|---|---|---|
| 公有云 | 公有GitLab | 按配置中心启用代码集成、新增关联仓库、OAuth认证、选择仓库的顺序执行 |
| 公有云 | 私有GitLab | 先确认网络互通，由GitLab管理员创建Application，再完成OAuth与Webhook |
| 私有部署 | 公有GitLab | 手册要求先联系ONES完成基础配置，再走公有GitLab的仓库关联流程 |
| 私有部署 | 私有GitLab | 以网络互通为前提，按私有GitLab的Application与OAuth流程执行 |
最容易出错的是第三行：ONES私有部署接入公有GitLab时，“先联系ONES完成基础配置”是这条组合特有的前置动作，它与接入私有GitLab的流程不同，不能互相套用。本文所述流程来自国内版公有云产品手册，私有部署场景按文内条件适用；由于未进行目标环境实测，历史版本信息不作为当前兼容承诺。
接入后的关联规则与运行边界
两条路线在接入完成后共享同一套关联规则，差别主要体现在接入前的准备与授权，接入后的使用方式一致。
- 提交关联：在commit message中使用#工作项ID，一次关联多个工作项时以空格分隔，工作项编号须有效且仓库已关联。
- 合并请求关联：在合并请求标题或描述中写入#工作项ID，可关联多个工作项，前提是源仓库已完成ONES集成。
- 状态流转：可为工作项工作流步骤配置分支创建、合并请求和提交关联等事件触发器，需要显式配置，集成完成本身不会自动改变所有状态。
- 校验差异：触发器驱动的状态变化不执行步骤验证和步骤属性校验，但会执行后置动作，配置触发器时应把这一差异纳入流程设计。
- 仓库获取范围：手册描述一次最多获取100个仓库，这是ONES的获取范围，不是GitLab平台的仓库总上限，超出时可按账号拆分关联。
- 解除关联：移除代码仓关联会停止获取该仓库的新提交数据，历史已获取数据保留。
- 事件推送：GitLab Webhook可把推送、合并请求等事件传递给外部系统，各部署有频率、超时和事件限制，不能保证每次复杂推送都触发。
这些规则决定了接入后的验收方式：提交和合并请求能否正确挂到工作项、触发器是否按预期推进状态、仓库数量是否在获取范围内，都是可以逐项检查的观察点。
按部署形态选择路线与上线前核验
路线选择可以按两步判断：先看GitLab是公有还是私有，再看ONES是公有云还是私有部署。私有GitLab路线先确认网络互通与管理员可创建Application；公有GitLab路线先确认操作账号具备代码集成配置权限；ONES私有部署接入公有GitLab时，把联系ONES完成基础配置列为第一个动作。
上线前建议按以下清单核验，把尚未确认的事项在目标环境落实：
- 私有GitLab版本是否满足手册标注的11.10及以上，并以目标环境当前兼容矩阵为准。
- 仓库数量是否在单次获取范围内，超出时是否已规划按账号拆分关联。
- 多个私有GitLab服务是否已规划由不同ONES用户分别关联。
- Redirect URI是否取自当前ONES环境，未使用其他租户的回调地址。
- Application权限是否由实际GitLab管理员按api、read_user、read_repository、write_repository核对。
- Webhook是否已配置并验证事件可达，权限不足时是否已转为手工配置。
- 工作流触发器是否已显式配置，并确认其不执行步骤验证与步骤属性校验的影响可接受。
完成上述核验后，两条路线都可以进入试运行：选取一个仓库，用一次提交和一次合并请求验证工作项关联，再观察触发器是否按配置推进状态，确认无误后扩展到其余仓库。
常见问题
ONES私有部署接入公有GitLab，为什么不能照搬私有GitLab的配置步骤？
这是两条不同组合下的路线。ONES私有部署接入公有GitLab时，手册要求先联系ONES完成基础配置，再走公有GitLab的仓库关联流程；私有GitLab路线的前提是ONES与私有服务网络互通，并由GitLab管理员在私有服务里创建Application。两者的前置动作和授权主体不同，把私有GitLab的Application配置套到公有GitLab上，或把“联系ONES完成基础配置”搬到私有GitLab流程里，都会让步骤对不上。
私有GitLab的Application由谁创建，Redirect URI填错会怎样？
Application由GitLab管理员在私有GitLab中创建，ONES侧用户无法替代。创建时要把ONES给出的Redirect URI填入，这个地址必须取自当前ONES环境，不能复制其他租户的回调地址；填错会导致OAuth认证无法按预期完成。权限方面，手册列出api、read_user、read_repository、write_repository，需要由实际GitLab管理员逐项核对配置。
公有GitLab接入时OAuth认证通过了，还需要单独配置Webhook吗？
OAuth认证的作用是取得配置仓库Webhook的权限，认证通过后即可在列表中选择目标仓库。若取得的权限不足，则需要转为手工配置Webhook，具体仓库权限以代码平台和ONES当前文档为准。因此认证通过不等于Webhook一定已就绪，接入时应核对Webhook是否配置成功，再确认仓库已集成。
接入完成后，提交和合并请求关联工作项的写法一样吗？状态会自动流转吗？
写法一致：提交在commit message中使用#工作项ID，一次关联多个工作项时以空格分隔；合并请求在标题或描述中写入#工作项ID，可关联多个工作项，前提是仓库已完成ONES集成。状态不会因为集成完成就自动改变，需要为工作项工作流步骤显式配置分支创建、合并请求和提交关联等事件触发器。另外，触发器驱动的状态变化不执行步骤验证和步骤属性校验，但会执行后置动作，配置时应把这一差异纳入流程设计。
有多个私有GitLab服务，或者仓库数量较多时，接入前要做什么规划？
手册描述一个ONES账号认证一个私有GitLab服务，存在多个私有服务时需要由不同ONES用户分别关联，实施前应复核当前版本是否仍适用这一约束。仓库数量方面，手册描述一次最多获取100个仓库，这是ONES的获取范围，不是GitLab平台的仓库总上限，超出时可按账号拆分关联。若后续移除代码仓关联，会停止获取该仓库的新提交数据，历史已获取数据保留。
官方参考资料
- GitHub/公有 GitLab（ONES）
- 私有 GitLab（ONES）
- Webhooks（GitLab）
