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