# GitHub/公有GitLab

URL: https://docs.ones.cn/ones-project/ones-devops/code-integration/github-and-public-gitlab

通过代码关联集成 GitHub/公有GitLab，将代码提交和 Project 模块结合使用。

## 1.仓库集成配置

### 1.1 新建关联代码仓

> 如果你使用的是 ONES 私有部署版，请联系客服。ONES 的技术人员将为你准备基础配置，以便于能正常关联 GitHub/GitLab 代码仓。

启用「代码集成」应用后，前往配置中心-代码集成配置进行代码仓库的关联，点击「新建关联代码仓」以关联当前团队所需 GitHub/GitLab 代码仓。

![GitHub/公有GitLab 配图 1](https://docs.ones.cn/assets/images/642f9f8ba0ca8cde-45dafaf7f202bbff039063a848534b97.png)

通过 OAuth 的方式认证 GitHub/GitLab，以便系统能获取自动配置代码仓 Webhook 的权限。

- 如果未认证过 GitHub/GitLab，请点击「新建认证」按钮；在打开的 GitHub/GitLab 平台的界面中确认授权认证 ONES；授权认证 ONES 成功后，系统会引导你回到 ONES 系统。
- 如果你已认证过 GitHub/GitLab，但想修改认证帐号，请在浏览器的无痕模式下点击弹窗中的「重新认证」，登录新帐号并重新认证后，系统会引导你回到 ONES 系统。
![GitHub/公有GitLab 配图 2](https://docs.ones.cn/assets/images/7c152353b5aecb5f-81acd45f469e5f52a373615e3b663084.png)

![GitHub/公有GitLab 配图 3](https://docs.ones.cn/assets/images/dd7a858e69fead07-2b9f94b4b656758831dc8ae9ae52d580.png)

OAuth 认证成功后，你需要选择代码仓并完成新建关联代码仓。

> 目前系统最多能获取到 GitHub/GitLab 的 100 个代码仓。如果希望关联 100 以上个代码仓，你需要将代码仓划分到不同的 GitHub/GitLab 帐号中进行关联。

> 操作关联的用户在 GitHub 中至少具有「Owner」权限、在 GitLab 中至少具有「Maintainor」权限，否则系统无权限自动配置代码仓的 Webhook，你需要手工配置。

![GitHub/公有GitLab 配图 4](https://docs.ones.cn/assets/images/886a64868ed78be6-8e278db969e295eea0455d5200558709.png)

新建关联代码仓后，系统会自动在代码仓中配置 Webhook。你可以在代码仓详情中检查 Webhook 的配置状态。

![GitHub/公有GitLab 配图 5](https://docs.ones.cn/assets/images/0f0e6999fa0669de-a9fd8a69f059062aeff6c4716e604295.png)

![GitHub/公有GitLab 配图 6](https://docs.ones.cn/assets/images/330043218f96de62-168fd9b320a4b1eef8906c01eaa041b8.png)

### 1.2 重置 Webhook

Webhook 用于允许 ONES 监听代码平台上的特定提交事件。新建关联代码仓后，你可以通过以下方式重新配置 Webhook。

- 系统自动重置 Webhook

如果 Webhook 失效或被人为删除，你可以点击「重置 Webhook」按钮，系统会自动重置代码仓中的 Webhook。
- 手工配置 Webhook

点击「手工配置 Webhook」按钮，你可以查看当前代码仓的 Webhook 的配置信息，再进入 Git 平台中手工添加 Webhook。
![GitHub/公有GitLab 配图 7](https://docs.ones.cn/assets/images/f4434d4c6594b7f1-0ea1c458914af62baf9e0a4735d56582.png)

![GitHub/公有GitLab 配图 8](https://docs.ones.cn/assets/images/4dde2adc33508d1e-3f6cb1c04759c78a0cd45b74595dad93.png)

### 1.3 移除关联代码仓

如果不需要再获取某代码仓的代码提交数据，你可以移除关联此代码仓。 移除关联代码仓不影响历史已获取的代码提交数据。

![GitHub/公有GitLab 配图 9](https://docs.ones.cn/assets/images/772b9317fce561dd-1aa87454fd27ba6223c9224da2da4a68.png)

### 2.代码提交关联工作项

团队成员可以在代码提交 (commit message) 的时候通过输入包含工作项 ID 的方式和工作项进行关联。 目前一次代码提交支持与多个工作项同时进行绑定，请在多个工作项 ID 之间添加空格作为分隔，例如"#1 工作项一 #2 工作项二"。

![GitHub/公有GitLab 配图 10](https://docs.ones.cn/assets/images/97d257c7898331b0-7addb9d70c172dda9c71600e26719e39.png)

工作项自动关联代码提交及其触发的持续集成数据，以便代码提交数据与项目管理结合。你可以在工作项详情的"代码关联"栏位查看代码关联结果。

![GitHub/公有GitLab 配图 11](https://docs.ones.cn/assets/images/22a09364ff15b666-a7960eec5cb775722080a4141343ea0c.png)

迭代支持汇总需求已关联的代码提交数据，迭代负责人可以据此跟进开发进展。

![GitHub/公有GitLab 配图 12](https://docs.ones.cn/assets/images/149f9e6db5e2ac9e-b4f6580ecbbbe2f5c8a56c9ccde6ef32.png)

迭代概览下将汇总统计当前迭代的代码提交情况，帮助迭代负责人评估开发贡献量。 目前支持统计和分析代码提交次数、代码提交次数趋势、代码提交影响行数的情况。

![GitHub/公有GitLab 配图 13](https://docs.ones.cn/assets/images/d0bc684cd54fddbd-97aef695762935726f6c9f9acabc3bab.png)

## 3.合并请求关联工作项

> 想要将「合并请求」记录与工作项绑定，需要先确保，提交「合并请求」的仓库已经集成到ONES系统，如何集成代码仓库参考第一章。

ONES 提供了两种方式实现「合并请求」与工作项的关联：

- 在外部系统提交「合并请求」，需要在提交信息的"标题"或者"描述"中按要求填入ONES工作项ID。
- ONES 工作项提供发起新建「合并请求」的入口，在ONES系统快速触发新建「合并请求」。

### 3.1 在外部系统提交「合并请求」

在外部系统提交「合并请求」申请，将要关联的工作项ID ,按"#id" 格式写入到"标题"或"描述"。

> 一条「合并请求」申请可以支持关联多个工作项，例如一次合并需同时关联多条需求和研发任务，不同的工作项ID之间需用空格分开。

![GitHub/公有GitLab 配图 14](https://docs.ones.cn/assets/images/1437718a74c9d6a4-6f553785a13562deae8b86d95a0b825c.png)

### 3.2 在ONES工作项发起新建「合并请求」

为便于快速关联代码「合并请求」到ONES系统，ONES支持在工作项详情页直接发起新建「合并请求」。

在工作项详情 -> 代码关联标签下，提供一个「新建合并请求」的入口。

![GitHub/公有GitLab 配图 15](https://docs.ones.cn/assets/images/1d65fb3528abba69-7a870a60cf0fa04e45bfa52dc808da52.png)

点击【新建合并请求】，弹出选择代码仓库、源分支、目标分支弹窗，按指引选择要提交代码合并的仓库、分支信息。

> 可选仓库列表来源「配置中心-代码集成关联」

> 仓库和分支均支持搜索，源分支与目标分支不能是同一分支

![GitHub/公有GitLab 配图 16](https://docs.ones.cn/assets/images/56515b33754d54a1-b3cb705d31075ffd69e400842f58f6b4.png)

配置好仓库与分支，点击【前往仓库】，将会跳转到代码托管平台的申请合并请求的页面，填写标题、描述、评审人等信息完成合并请求的提交。

> 跳转到第三方时，会将工作项的ID和标题自动填写到描述信息中，如果删除 #ID ，则无法关联到工作项。如果需要关联更多其他工作项，也可以手动填入其他 #ID，多ID之间同样空格分开。

![GitHub/公有GitLab 配图 17](https://docs.ones.cn/assets/images/f61b0216e1c44be3-1efa34fe36371607b7270aa3bb495c94.png)

### 3.3 查看合并请求关联信息

合并请求关联后，会记录以下字段信息，并支持点击跳转仓库的合并请求详情页。

- 标题
- 仓库名/源分支 -> 目标分支
- 新建/更新时间
- 评审人
- 合并请求状态（待合并、合并完成、拒绝/关闭）
![GitHub/公有GitLab 配图 18](https://docs.ones.cn/assets/images/cee87535d2982448-952c440d9817bbe6274a36e6182105ff.png)

## 4.代码分支关联工作项

> 新建代码分支是编码开发流程中的重要环节，通过关联分支，不仅可以与工作流联动，还能记录开发事件，打通业务管理与开发实践。

目前支持用户在 ONES 的工作项内快速新建代码分支，将分支信息与工作项关联。

1.仓库分支与ONES工作项关联的前提，需要将该仓库集成到ONES系统（如何集成代码仓库请参考第一章节）

2.工作项详情-> 代码关联标签下，增加【代码分支】模块，并提供「新建分支」的操作入口。

![GitHub/公有GitLab 配图 19](https://docs.ones.cn/assets/images/0c45a7af2355701f-44896d2e2a7c7365d038937a5d66b22e.png)

3.点击「新建分支」按钮，弹出新建分支窗口

- 填写新建分支的名称（分支名长度限制50个字符）
- 选择新建分支的仓库以及源分支
- 点击确认即可新建分支
![GitHub/公有GitLab 配图 20](https://docs.ones.cn/assets/images/bcb4257a6e2456d8-1efdf507141f78549ebeb543c94c2953.png)

4.新建分支后，工作项会记录该分支信息，点击分支即可跳转到外部仓库管理工具，查看分支详情。

5.记录的分支信息字段如下：

- 代码仓库/分支名称
- 创建人
- 创建时间
![GitHub/公有GitLab 配图 21](https://docs.ones.cn/assets/images/f4febd2f9b07f0ea-0792d430d100e594525cade3ca47872a.png)

## 5.代码开发事件自动触发工作项状态流转

### 5.1 触发器说明

当开发人员执行代码提交、创建代码分支、创建合并请求等操作时，触发器会自动将其关联的工作项的状态进行流转，而不需要开发人员手动去更改工作项状态，提高开发人员工作效率。

支持的代码开发事件触发器如下：

| 触发器名称 | 触发器定义 | 支持的工具 |
| --- | --- | --- |
| 新建代码分支 | 当工作项关联的代码分支被新建成功时，自动触发工作项状态变更 | GitHub、公有GitLab、私有GitLab、私有Bitbucket |
| 新建合并请求 | 当工作项关联的代码合并请求被新建成功时，自动触发工作项状态变更 | GitHub、公有GitLab、私有GitLab、私有Bitbucket |
| 合并请求通过 | 当工作项关联的合并请求状态变更为通过时，自动触发工作项状态变更 | GitHub、公有GitLab、私有GitLab、私有Bitbucket |
| 合并请求被关闭 | 当工作项关联的合并请求状态变更为失败或者被关闭时，自动触发工作项状态变更 | GitHub、公有GitLab、私有GitLab、私有Bitbucket |
| 关联代码提交 | 当代码提交信息与工作项关联成功时，自动触发工作项状态变更 | GitHub、公有GitLab、私有GitLab、私有Bitbucket、SVN |

### 5.2 配置工作流触发器

安装「代码集成」应用并在「配置中心」-「代码集成配置」中关联代码仓库后，可以在「项目设置」-「工作项类型」-「工作项工作流」-「编辑步骤」配置中找到「触发器」功能，选择并添加触发器。

- 每个工作流的步骤可配置多个触发器，触发任意一个，状态变更会自动执行；
- 被触发器自动化执行的状态变更会忽略「步骤验证」和「步骤属性」的校验，但「后置动作」会被正常执行。
![GitHub/公有GitLab 配图 22](https://docs.ones.cn/assets/images/c397c134bf4848fe-ec0b3a488ac3fdc9baa1234cfcdcd58d.png)

### 5.3 触发器常见问题

1. 无法添加触发器的原因是什么？

- 未安装「代码集成」应用时，无法添加代码开发事件的触发器；
- 如果当前步骤已经添加了某个触发器，则不能重复添加；
- 同一个工作项类型，如果状态A到状态B的步骤已经配置了某个触发器，则状态A到其他状态的步骤不能重复添加该触发器，是为了防止当某个触发事件发生时，系统无法判断应该从状态A流转到哪个状态。
2. 配置触发器后，工作项状态没有流转到预期的目标状态，可能的原因是什么？

- 代码仓是否已关联ONES系统，在未关联的代码仓库中操作无法关联到ONES工作项，从而无法触发工作项状态变更
- 如果流转到目标状态后刚好满足某个流程自动化规则的触发条件，会导致工作项状态进一步流转到其他状态