准时下班的秘密：集成 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)：这里比较关键，是自动化工作流的核心，有以下几点注意事项：首先这里是指 GitLab commit or merge 动作关键字触发对应的 JIRA workflow ID（状态 ID，多个状态使用 , or ; 号分割）限制：workflow id 必须是连续的状态，如果是有中间状态则会跳转失败只会对 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 可以看到：

所有的 Issue 都会链接到 JIRA

点击 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 即可，具体如图所示：

批量关闭 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