介绍
插件功能：通过简单的安装和配置，研发同学可以将GitHub的Branch、commit、PR和飞书项目的工作项进行关联，并可通过merge 事件自动流转节点/状态。
名词解释
- 关联：指将 GitHub 信息与飞书项目信息进行关联，关联成功后，可在需求/缺陷等工作项中看到关联的 branch/commit/PR；
- 流转：在关联的基础上，通过MR的状态变化自动流转工作项的节点/状态，无需人工点击；
- 分端流转：各端（前端/后端...）只流转各自端对应的节点/状态。
安装/升级
操作人：飞书项目空间管理员
安装新插件
在【飞书项目】中，前往空间配置 → 插件管理 → 右上角添加插件；
250px|700px|reset
选择对应的插件「添加插件」；
250px|700px|reset
配置 Webhook
支持配置某个仓库的Webhook，配置好后，该仓库可正常使用本插件，与飞书项目联动；
支持配置某个Organization的Webhook，配置好后，该组织下的所有仓库可正常使用本插件，与飞书项目联动；
- 【飞书项目】在插件中选择「复制 URL」；
250px|700px|reset
- 【GitHub】登录 GitHub 后，点击进入对应的仓库，Tab页 Setting → Webhooks 选项；
content type需要选择为“application/json”
250px|700px|reset
- 将1复制的 URL 粘贴到 GitHub 的 Webhook 中的 URL 选项中，勾选「Pushs」、「Pull requests」后点击下方的「Add webhook」完成 webhook 关联。
250px|700px|reset
插件配置
操作人：【飞书项目】空间管理员
诉求一：只关联不流转
无需再做任何配置，安装插件，配置 Webhook ，即可参照关联方式去做关联。
诉求二：关联且流转
新建规则
前往「空间配置 → 插件 → GitHub 插件」，点击「添加流转规则」按钮进入新建规则弹窗。
250px|700px|reset
选择工作项类型
选择需要流转的工作项类型，如需求 > 业务需求模板；
250px|700px|reset
配置一条仓库&节点映射关系
锁定流转信号来源，多端分别流转看这里：
- 点击「选择仓库」，选择本条驱动规则的需要从哪个 GitHub 仓库触发：
250px|700px|reset
- 任意仓库，无需分端流转：选择「任意仓库」，代表在关联的基础上，任意仓库的MR信号，都可流转工作项需求；
- 安全考虑，统一用特定仓库：输入特定仓库的名称（含namespace），按回车，并选中；配置好后，只有特定仓库来的流转信号，才会驱动流转节点/状态。
- 多端节点/状态，分别驱动流转：首先，确定各端（前端/后端/...）仓库相互独立，不共用；然后，每条映射关系中，只配置某个端的仓库名称（含namespace），一个端有多个仓库的，可注意添加；
- 配置好后，不同的仓库信号将会驱动流转不同的节点/状态；
注意仓库名称要带 namespace。
选择 GitHub 事件
「Pull Request 完成/创建」事件，选择即可；
250px|700px|reset
选择流转的节点/状态
配合上述完成对应节点/状态的配置，如XXX 仓库 的Pull Request完成时，服务端MR 节点完成
如需要一次性流转多个连续串行的节点，可在此处多选；
注意：缺陷类型的工作项，建议不要多选，因为状态流转存在环路，流转结果会不稳定。
250px|700px|reset
选择必填模式
仅限节点流使用，如需求，是否卡点看这里下方。
250px|700px|reset
关联 PR 才能流转工作项
- 开关开启，将为对应流转的节点添加必填字段，仅当关联的 PR merged 后，该字段才能变成「已通过」，节点才可流转通过；
- 使用场景：使开发流程规范化等；
- 缺点：较为生硬，如果没有关联 PR merged 信号流入，该字段值将阻塞节点流转，e.g.某些需求/缺陷不涉及研发仓库修改；
250px|700px|reset
自动流转 + 手动流转
开关关闭，代表模板中不会生成字段，插件将在满足条件时驱动节点/状态流转通过，同时用户也可手动点击流转通过，不会阻塞流转；同时因为没有生成字段，实例无需升级模板也可生效；
使用场景：提高研发/测试同学流转节点的效率，在支持手动流转的基础上，插件帮助自动流转；
缺点：无法通过必填来形成开发规范。
自定义规则
250px|700px|reset
自定义前缀
- 主要用于PR 关联、commit 关联、Branch 关联
- 使用方式参考：【诉求一：只关联不流转】-【在GitHub中通过以下方式关联（任选其一）】
驱动关键字
- 主要用于MR - merged 事件自动流转节点/状态
- 使用方式参考：【诉求二：自动流转】
保存规则
点击「创建」保存规则，规则默认启用，后续可参照自动流转方式进行关联+自动流转。
删除规则
如果修改过程中发现模板已删除的，代表规则已不再生效，建议点击删除按钮，删掉这条规则。
250px|700px|reset
如果修改过程中发现节点/状态已删除的，可能还有存量数据使用这些节点/状态，如果想对存量数据保持作用，则无需修改。
删除插件
如需删除插件，可以点击「删除」按钮，删除后，插件将不再展现，同时相关数据会全部清空，需重新添加并进行重新配置，请谨慎操作。
如果之前开启了必填模式，注意存量工作项中的还会有必填字段，可以通过在详情页升级版本去除。
插件使用
操作人：【飞书项目】用户
诉求一：只关联不流转
插件安装后，配置好Webhook后，研发同学即可通过commit、branch、PR 关联需求/缺陷等工作项，具体操作如下：
工作项详情页，快捷键复制ID
- Windows: Ctrl + Shift + C
- IOS： Cmd + Shift + C
也可通过界面点击获取，如下图：
250px|700px|reset
在GitHub中通过以下方式关联（任选其一）
PR 关联
新建/编辑MR时，在MR的标题、描述中用关联语法进行关联；
- 任何状态都可关联（opened、closed）
- 可在标题、描述中关联
- 支持编辑、修改
250px|700px|reset
commit 关联
commit message 中，用关联语法进行关联；注意这里是一次性设置，无法修改。
250px|700px|reset
命令行关联，单个需求、缺陷等工作项实例进行关联时：
git commit -m "m-需求ID""
选择多个需求、缺陷等工作项实例进行关联时：
git commit -m "m-需求ID,f-缺陷ID""
Branch 关联
新建branch时，用关联语法进行关联；注意这里的关联属于一次性关联，无法修改，同样一个开发分支可能映射多个需求、缺陷，不方便管理。
界面关联：
250px|700px|reset
命令行关联：
git branch m-需求IDD
选择多个需求、缺陷等工作项实例进行关联时：
git branch m-需求ID,f-缺陷IDD
关联语法
m-/M-/f-/F-workitemID ，如 m-439945
- 大小写不限
- 位置不限
- 一次性关联多个时，用‘,’分隔即可
250px|700px|reset
关联效果
完成关联后，飞书项目会收到相应的信号，在对应的需求、缺陷等工作项实例的「GitHub代码分支」标签页展示对应信息；
250px|700px|reset
诉求二：自动流转
配置对应流转规则后，可通过 merged 事件自动流转节点/状态。
使用方式
新建/编辑PR时，在 PR 的标题、描述中填写下方流转语法，即可在该 MR 完成 merged 时，自动流转对应工作项或节点。
resolve m-/M-/f-/F-workitemID ，如 resolve m-439945
- 后续当 PR 状态变更为 merged 时，关联的工作项将根据配置规则自动流转；
- 若关联时 PR 状态已为 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 后自动流转两个工作项。
250px|700px|reset
250px|700px|reset
FAQ
是否支持私有化部署的 GitHub？
支持，只要私有化版本可以和外网通信且支持 HTTPS 即可使用。
为什么配置之后没有生效？
如果是私有化部署，考虑网络环境没有互通，请检查内网环境问题。如果非私有部署，考虑相关服务阻断了链接，请等待相关服务恢复。
为什么 PR 已 merged, 但没有 GitHub 信号
Check list ：
- 规则配置是否完整；
- 关联规则中是否设置为必填；
- 模板中的节点是否存在（有可能被其他管理员修改过）；
- 是否升级了模板（若关联配置是后添加的话，需要在前端升级模板，才能生效）；
- MR 中是否使用流转语法。
- 流转规则是否设置了仓库条件。如有，检查仓库名称是否匹配。注意：仓库名称严格区分大小写。
是否可以配置分端（前端/后端/...）流转？
可以配置多端分别驱动节点/状态流转：
- 确定各端（前端/后端/...）仓库相互独立，不共用；
- 每条映射关系中，只配置某个端的仓库名称（含namespace），一个端有多个仓库的，可逐一添加。
关联 GitHub Tab 何时展示？
- 配置了流转规则的工作项一定会展示 Github tab；
- 未配置流转规则的工作项，如果在仓库端通过命令进行了关联，被关联的工作项实例会展示 GitHub tab。
