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