准时下班的秘密：集成 GitLab && JIRA 实现自动化工作流

佛罗伦萨 - 圣母百花圣殿（图）

前言

GitLab 和 Jira 是平时开发过程中使用非常高频的代码管理系统（开发人员）和项目管理系统（项目管理），通过两套系统的协作完成平常大多数的功能开发，但是两套系统在没有集成情况下是完全两套独立的系统，不仅信息没有互通，而且开发人员需要反复的登陆两套不同的系统，进行一些重复的操作才能保证功能流的正常流转，不仅效率低下，浪费时间和人力，而且因为人本身的不可靠属性，所以导致状态的流转并不能非常的及时和准确，这种重复和机械的动作恰恰是自动化所擅长的地方，今天我介绍一下如何集成 GitLab 和 Jira 的工作流，提高团队的开发体验，提升大家的开发效率，可以把腾出的精力和时间都放在更有价值的事情上

1. GitLab 如何开启 JIRA 的入口？
2. GitLab 如何打通 JIRA 的信息流？
3. GitLab 如何自动化 JIRA 的工作流（workflow）？
4. GitLab 如何批量触发 JIRA 的工作量 ？

GitLab 如何开启 JIRA 的入口？

GitLab 需要一个专属的 JIRA 账号，并且拥有相应的权限，用于在 JIRA issues 添加注释和操作系统，具体如何在 JIRA 中创建和配置账号这里就不介绍了，不熟悉的小伙伴可以直接看官方文档 Creating a username and password for Jira Server 的介绍

然后进入 GitLab 选择对应的 Project -> Setting ->Integrations -> Jira

GitLab JIRA 的配置页面：

配置也非常简单，这里我简要说明一下：

• Web url ：你们公司的 JIRA 访问地址
• Jira API URL：使用 JIRA cloud 填写的 api 地址，可选项，没有使用为空即可
• username or email：在上面创建 JIRA 的账号
• password：在上面创建 JIRA 的密码
• Transition id(s)：这里比较关键，是自动化工作流的核心，有以下几点注意事项：
  1. 首先这里是指 GitLab commit or merge 动作关键字触发对应的 JIRA workflow ID（状态 ID，多个状态使用 , or ; 号分割）
  2. 限制：workflow id 必须是连续的状态，如果是有中间状态则会跳转失败
  3. 只会对 JIRA status: resolution = unresolved 的 issues 生效，就是说 GitLab 不会去触发 issue 状态为 close 或者为 done 的工作流

配置成功后会显示 JIRA active

并且在 project 主菜单的左侧增加 JIRA 的快捷入口，点击快捷跳转到配置好的 JIRA web url，如图：

Setting -> Integrations 显示：

到这里第一步，配置就完成了

GitLab 如何打通 JIRA 的信息流？

完成第一步配置，后续的信息流就简单的多了，但是功能强大，让使用在 GitLab JIRA 之间无缝切换，行云流水，具体有以下几种玩法：

首先是 JIRA issue 的映射，只要是 push 到远端仓库的 commit 会自动关联到 JIRA 对应的 issue 页面，点击即可访问，在项目下的 commit history 可以看到：

点击 TEST-220 则可以直接跳转到对应的。JIRA 详情：

在解决该 issue 的过程中，所有的 commit log 也会被自动关联到 JIRA issue 的注释中，在 JIRA 系统中形成问题的解决历史和思路，方便复盘和回顾：

JIRA issue 的自动注释的格式规范：

USER mentioned this issue in RESOURCE_NAME of [PROJECT_NAME|LINK_TO_COMMENT]:
ENTITY_TITLE

更方便的是 issue 下面的自动 commit 注释，也是访问 GitLab 的超链接，点击进去可以查看到当次 commit 的修改详情，例如我们点击这个 Commit - TEST-220 resolver a problem ... ，可以看到具体的代码改动项：

要享受以上的所有收益，只需要遵循一条简单的 commit 规范，既在项目配置 JIRA active 的情况下，在 commit 中代码 JIRA issue 编号即可，而且 commit 信息一旦被推送到 GitLab 远端分支，就会马上被在对应 JIRA issue 下面增加 commit. 注释，可以说使用起来非常的方便，示例的 commit 如下：

git commit -am 'TEST-220 resolver a problem'

GitLab 如何自动化 JIRA 的工作流（workflow）？

这里应该算是集成中最实用，也比较复杂的功能，通过 GitLab 的 commit or merge 动作改变 JIRA issue 状态（根据我们上面配置的 transition ID 来流转），自动触发状态流转的关键字有以下 3 个：

• Resolvers Issue-1
• Closes Issue-1
• Fixed Issue-1

当然触发工作流的动作也是有限制的，我们先看官方文档的描述：

Notes:

• Only commits and merges into the project’s default branch (usually master) will close an issue in Jira. You can change your projects default branch under project settings.

• The Jira issue will not be transitioned if it has a resolution.

我在这里简单转述一下：

1. 只有默认分支（master 可以在 GitLab -> Settings 中配置）的 commit and merge 会触发关闭 JIRA issue
2. 已有解决方案的 JIRA issue 则不会发生状态流转（就是我之前说的：只会对 JIRA.issue.status.resolution = unresolved 的 issues 生效）

我们目前的痛点是：

每次需求上线后，都开发人员在 JIRA 里面点 On Line 来确定功能已经发布，但是此时 On Line 状态的需求通常不挂在开发人员身上，开发人员每次需求上线后需要做以下操作：

1. 登陆 Jira 系统，输入账号密码
2. 找到项目，通过需求编号，找到对应已经上线的需求
3. 在状态项点击 On Line 按钮，改变 JIRA issue 的状态

以上操作虽然不复杂，但是每一个需求上线都需要做一次重复的操作，有时候版本功能多，所有任务都需要逐个搜索出来手动更改状态，不仅效率不高，而且容易遗忘，尽管项目负责人经常反复提醒，依旧无法避免人工操作不及时的问题，最终导致 JIRA 统计 LeadTime 流程被拉长，所以这是急需自动化的痛点

介绍到这里差不多了，我们来看看如何通过自动化的 workflow 简化我们的开发环节：（这里仅仅代表我们团队的工作流，并不适用于大部分的场景）

首先这里可以看到这个 issue 任务已经完成，处于等待上线的状态（done） ：

开发人员只需在 GitLab 将对应的 TEST-225 分支提交 merge request，这里可以看到 GitLab 很智能的在 merge 描述中加入的触发 JIRA issue 的关键字，merge request 生效后，对应的工作流也自动触发了（状态为 unresolved），如图：

可以直接点击描述的 issue 跳到 JIRA 系统查看

GitLab 如何批量触发 JIRA 的工作量 ？

以上仅仅是对单个 Feature 的提交合并触发工作流，但是日常开发中这种场景比较少，很多 Feature 通常都是批量发布和上线，以我们目前的项目为例，我们目前最大的痛点是 Feature 上线后可以自动触发 Jira 的 On Line workflow，如果可以通过在 Release 合并进 Master 批量触发工作流将可以大大的简化我们目前的工作，提高效率。

在 GitLab 中有两种方式可以实现批量触发工作流，两种实现方式不同，但各有利弊：

• Release 分支通过 Merge Request 的 Description 批量添加 Closes issue id 实现
• Feature 分支通过本地 commit -m 'Closes issue id' 然后合并到默认分支实现（master）

Release 分支通过 Merge Request 的 Description 批量添加 Closes issue id 实现

这种操作实现起来对项目经理和负责人要求会高一些，需要事先整理和汇总所有要上线的分支和对应的 issue ，然后 GitLab 会在 Release -> Master 节点的时候通过 Merge 的时候自动触发 Jira 的工作流，那我们就需要在 Release 进行 Merge Request 的时候在合并描述 Description 添加触发关键字 Closes Issue 即可，具体如图所示：

在负责人点击 Merge 对应的 issue 就会自动触发 Jira 工作流，流转对应的状态

Feature 分支通过本地 commit -m 'Closes issue id' 然后合并到默认分支实现（master）

这种操作实现起来对开发人员要求会高一些，要求开发人员遵循规范，在完成 Feature 分支功能开发后，按照规范提交 commit 关键字来触发工作流，具体如下：

git checkout phoenix/feature/TEST-223
git commit -m 'Closes TEST-223'

这种方式的好处是项目负责人不需要提前收集和整理 issue，也不需要在 Release 进行 Merge Request 的时候在合并描述 Description 添加触发关键字，直接提交 Release 分支合并即可，具体如下：

它的工作原理是 GitLab 会自动在 Feature 分支的 commit log 找到触发关键字然后执行自动化工作流，点击 Merge 后通过 issue 链接跳转过去就会发现 Jira 的状态已经更新，非常方便，虽然两种方式最终实现的效果都是一样的，但是我个人比较推荐使用第二种方式，比较方便不说，而且可以培养开发人员的规范意识也是比较好的

总结

到这里集成工作就基本完成了，自从 GitLab 集成 JIRA 后开发团队的效率和幸福感大增，从此过上了幸福的生活，距离走上人生的巅峰也不远了………………

PS：这里只是进行了简单的集成，如果大家发现更好的功能，可以分享出来交流和讨论

参考资料：

• GitLab Jira integration