介绍
插件功能：通过简单的安装和配置，研发同学可以将 Gerrit 的 change 和飞书项目的工作项进行关联，并可通过merge 事件自动流转节点/状态。
名词解释
- 关联：指将 Gerrit 信息与飞书项目信息进行关联，关联成功后，可在需求/缺陷等工作项中看到关联的 changes 信息；
- 流转：在关联的基础上，通过 change 的状态变化自动流转工作项的节点/状态，无需人工点击；
- 分端流转：各端（前端/后端...）只流转各自端对应的节点/状态。
安装/升级
操作人：飞书项目空间管理员
安装新插件
在飞书项目中，前往空间配置 → 插件管理 → 右上角添加插件；
250px|700px|reset
选择对应的插件「添加插件」；
250px|700px|reset
配置 Webhook
- 在插件中选择「复制 URL」；
250px|700px|reset
- Gerrit 支持按 Project 和全局两种 webhook 配置方式。
250px|700px|reset
确认插件安装后，可以通过以下方式进行配置：
- 按 Project 可通过 api 进行添加，gerrit 相关API文档可以在 {$gerrit_host}/plugins/webhooks/Documentation/rest-api-config.md 路径下找到
- 全局配置方式需要在 gerrit 部署目录的/etc 子路径下的 gerrit.config 文件进行配置，相关帮助文档在{$gerrit_host}/plugins/webhooks/Documentation/index.html
250px|700px|reset
升级已有插件
如果已经安装插件，点击「更新」升级旧插件即可。
250px|700px|reset
插件配置
操作人：飞书项目空间管理员
诉求一：只关联不流转
无需再做任何配置，安装插件（注意非字节租户还需配置 Webhook ）即可生效。用户可参照【只关联不流转】进行关联。
诉求二：关联且流转
新建规则
前往空间配置 → 插件 → Gerrit 插件→ 配置 ，点击「添加流转规则」按钮进入新建规则弹窗。
250px|700px|reset
选择工作项类型
选择需要流转的工作项类型，如需求 → 技术专项；
250px|700px|reset
配置一条仓库&节点映射关系
锁定流转信号来源，多端分别流转看这里：
- 点击「选择仓库」，选择本条驱动规则的需要从哪个 Gerrit 仓库触发：
- 任意仓库，无需分端流转：选择「任意仓库」，代表在关联的基础上，任意仓库的change信号，都可流转工作项需求；
- 安全考虑，统一用特定仓库：输入特定仓库的名称，按回车，并选中；配置好后，只有特定仓库来的流转信号，才会驱动流转节点/状态。
- 多端节点/状态，分别驱动流转：首先，确定各端（前端/后端/...）仓库相互独立，不共用；然后，每条映射关系中，只配置某个端的仓库名称（含namespace），一个端有多个仓库的，可逐一添加；
- 配置好后，不同的仓库信号将会驱动流转不同的节点/状态；
仓库名称可以在Gerrit 仓库管理页面进行查看
url 路径一般为：{$gerrit_host}/{$user_name}/repos
250px|700px|reset
选择 Gerrit 事件
目前仅有「Change Merged 」这一种事件，选择即可。
250px|700px|reset
选择流转的节点/状态
配合上述3.1完成对应节点/状态的配置，如XXX 仓库 的Change Mergerd完成时，服务端change 节点完成
如需要一次性流转多个连续串行的节点，可在此处选择多个节点。
注意：建议状态流工作项不要多选，因为状态流转存在环路，流转结果会不稳定。
250px|700px|reset
选择必填模式
此功能仅限节点流工作项使用。
状态流工作项无法设置必填模式，Gerrit 信号流入后驱动状态自动流转，同时也可以手动流转。
Gerrit 信号驱动节点流转
打开必填模式后，将为该节点增设必填字段，只有 Gerrit 信号流入后节点才可流转。
- 使用场景：通过 Gerrit 信号自动流转节点，规范开发流程。
- 缺点：灵活性较低，若无 Gerrit 信号流入，该字段值将阻塞节点流转。例如：某些需求/缺陷不涉及研发仓库修改，节点/状态将无法流转。
250px|700px|reset
手动流转 + Gerrit 信号驱动节点流转
打开必填模式后，节点中不会添加字段，Gerrit 信号流入后节点自动流转；同时用户也可手动点击流转。
- 使用场景：通过自动流转提高研发/测试同学流转节点的效率，同时可以手动流转，不阻塞流程。
- 缺点：可以手动流转，无法通过 Gerrit 信号规范开发流程。
250px|700px|reset
自定义规则
250px|700px|reset
自定义前缀
- 主要用于commit 关联
- 使用方式参考：【诉求一：只关联不流转】-【在 Gerrit 中关联】
驱动关键字
- 主要用于MR - merged 事件自动流转节点/状态
- 使用方式参考：【诉求二：自动流转】
保存规则
点击「创建」保存规则即可生效。用户可参照【关联且流转】进行关联，实现节点自动流转。
删除规则
如果修改过程中发现模板已删除的，代表规则已不再生效，建议点击删除按钮，删掉这条规则。
250px|700px|reset
如果修改过程中发现节点/状态已删除，可能还有存量数据使用这些节点/状态，如果想对存量数据保持作用，则无需修改。
删除插件
如需删除插件，可以点击「删除」按钮，删除后，插件将不再展现，同时相关数据会全部清空，需重新添加并进行重新配置，请谨慎操作。
250px|700px|reset
如果之前开启了必填模式，注意存量工作项中的还会有必填字段，可以通过在详情页升级版本去除。
250px|700px|reset
插件使用
操作人：飞书项目用户
诉求一：只关联不流转
研发同学可通过commit、branch、change 关联需求/缺陷等工作项，具体操作如下：
在飞书项目中复制工作项 ID
在飞书项目需求/缺陷的详情页中，通过快捷键复制工作项ID；
- Windows: Ctrl + Shift + C
- IOS：Cmd + Shift + C
也可在需求/缺陷的详情页，点击右上角“···”，复制工作项ID。
250px|700px|reset
在 Gerrit 中关联
commit 关联
在 change 的 commit message 中，用关联语法进行关联；注意这里是一次性设置，无法修改。
250px|700px|reset
命令行关联，单个需求、缺陷等工作项实例进行关联时：
git commit -m "m-工作项ID""
选择多个需求、缺陷等工作项实例进行关联时：
git commit -m "m-工作项ID,f-工作项ID""
关联语法
m-/M-/f-/F-workitemID ，如 m-439945
- 大小写不限
- 位置不限
- 一次性关联多个时，用‘,’分隔即可
关联效果
完成关联后，飞书项目会收到相应的信号，在对应的需求、缺陷等工作项实例的「Gerrit 」标签页展示对应信息。
250px|700px|reset
诉求二：自动流转
研发同学可通过 merged 事件自动流转节点/状态。
在飞书项目中复制工作项 ID
在飞书项目需求/缺陷的详情页中，通过快捷键复制工作项ID；
- Windows: Ctrl + Shift + C
- IOS：Cmd + Shift + C
也可在需求/缺陷的详情页，点击右上角“···”，复制工作项ID。
250px|700px|reset
在 Gerrit 中关联
新建/编辑 change message 时，在 message 中填写下方流转语法，即可在该 change 完成 merged 时，自动流转对应工作项或节点。
resolve m-/M-/f-/F-workitemID ，如 resolve m-439945
250px|700px|reset
- 后续当 change 状态变更为 merged 时，关联的工作项将根据配置规则自动流转；
- 若关联时 change 状态已为 merged，则在关联成功的瞬间触发流转；
- 如果测试信号没有变绿，可以先流转节点为进行中状态。
除 resolve 之外，还支持以下词：
- Close：Close, Closes, Closed, Closing, close, closes, closed, closing
- Fix：Fix, Fixes, Fixed, Fixing, fix, fixes, fixed, fixing
- Resolve：Resolve, Resolves, Resolved, Resolving, resolve, resolves, resolved, resolving
以上关键词不区分大小写：
- 整个流转结构体，在标题、描述中的位置不限，即resolve m-439945可放在标题/描述中的任意位置
- 一次性流转多个时，用‘,’分隔即可，如resolve m-439945, m-439946，即可实现 merged 后自动流转两个工作项
关联效果
完成关联后，飞书项目会收到相应的信号，在对应的需求、缺陷等工作项实例的「Gerrit 」标签页展示对应信息。
该 change 完成 merged 时，飞书项目会收到相应的信号，需求、缺陷等工作项实例的节点/状态将自动流转。
250px|700px|reset
FAQ
是否支持私有化部署的 Gerrit？
支持，只要私有化版本可以和外网通信且支持 HTTPS 即可使用。
为什么配置之后没有生效？
如果是私有化部署，考虑网络环境没有互通，请检查内网环境问题。如果非私有部署，考虑相关服务阻断了链接，请等待相关服务恢复。
为什么 change 已 merged, 但在飞书项目的节点/状态上没有收到 Gerrit 信号？
可以依次检查以下内容：
- 规则配置是否完整；
- 关联规则中是否设置为必填；
- 模板中的节点是否存在（有可能被其他管理员修改过）；
- 是否升级了模板（若关联配置是后添加的话，需要在前端升级模板，才能生效）；
- Change commit message 中是否使用流转语法。
- 流转规则是否设置了仓库条件。如有，检查仓库名称是否匹配。注意：仓库名称严格区分大小写。
是否可以配置分端（前端/后端/...）流转？
可以配置多端分别驱动节点/状态流转：
- 确定各端（前端/后端/...）仓库相互独立，不共用；
- 每条映射关系中，只配置某个端的仓库名称（含namespace），一个端有多个仓库的，可逐一添加。
关联 Gerrit Tab 何时展示？
- 配置了流转规则的工作项一定会展示 gerrit tab；
- 未配置流转规则的工作项，如果在仓库端通过命令进行了关联，被关联的工作项实例会展示 gerrit tab。
