runsisi's

technical notes

gitlab MR + Jenkins 测试框架配置

2019-01-10 runsisi#git

背景

从 8.0 版本(截至 2018 年 1月 8 日,最新版本为 10.3.3)开始,gitlab 自身集成了 gitlab CI[1] 集成测试框架,该测试框架与 gitlab 自身的源代码管理系统集成的非常好,但是 gitlab CI 暂时并不支持直接测试 MR[2],而在我们的开发模式下,总是要求保证目的分支的可用性,因此需要集成一个外部的测试框架,以保证每个 MR 在合入之前进行测试。

当前 Jenkins 对 gitlab 的支持非常好,因此使用 Jenkins 是一个比较合理的解决方案,本文对 gitlab 与 Jenkins 的测试框架配置进行介绍,但需要注意的是,本文并不是一个非常详细的面面俱到的指导文档,主要只记录了关键配置项,文中有些配置步骤并没有详细的截图记录,因此要求本文的读者对 gitlab 以及 Jenkins 都要有一定的基础。

[1] https://docs.gitlab.com/ce/ci/

[2] https://gitlab.com/gitlab-org/gitlab-ce/issues/4176

版本信息

  • gitlab 10.3.2
  • Jenkins 2.89.2
  • gitlab-plugin for Jenkins[1] 1.5.2

[1] https://github.com/jenkinsci/gitlab-plugin

运行环境

运行环境实际上对测试框架的配置没有什么影响,考虑到本文的完整性简述如下:

  • gitlab 运行环境为 CentOS 7.2
  • Jenkins master 与 gitlab 运行在同一个节点上
  • Jenkins slave 为另一台 CentOS 7.3 环境

测试框架中各组件的交互如下图所示:

gitlab jenkins

其中 gitlab 的用户通过创建 MR 的形式向项目提交代码合入请求,当创建 MR 或向已有的 MR 提交新的 commit 时 gitlab 会通过 webhook 触发 Jenkins master 上的 gitlab-plugin 插件进行相应的操作,比如触发 Jenkins 的构建任务、单元测试任务等,最后任务的完成情况会反馈在 gitlab 的界面上。

配置步骤

从前面的测试框架各组件交互图可以大致看到,配置涉及 Jenkins、Jenkins 项目以及 gitlab 等三个部分的配置,下面将对这三个部分的配置以图示的方式进行说明。

Jenkins 配置

由于 Jenkins slave 节点的配置如果不熟悉的话可能有一些麻烦,因此首先简单介绍如何添加 slave 节点(Jenkins 会以当前浏览器的语言环境显示页面语言,本文附录介绍了选择特定语言的方法,本文以 Jenkins 英文界面为基础进行描述)。

  1. 安装 Jenkins 插件时可能需要配置代理(可以通过上传本地已下载好的插件进行安装,但大多数插件都会依赖于其它底层插件,因此如果能联网安装的话最好进行联网安装),通过 Jenkins/Manage Jenkins/Manage Plugins 菜单进入 Advanced 页面(该页面中间部分即通过手动上传插件的功能),配置合适的代理服务器地址

proxy

  1. 搜索并安装 SSH slave 插件

ssh plugin

  1. 主界面侧边栏点击 Build Executer Status 链接,进入 Jenkins/Nodes 配置页面

nodes

  1. 点击侧边栏 New Node 链接,添加新 slave 节点

new node

  1. 新节点的配置最关键的两个选项选择如下(注:这个版本的 Jenkins 有 bug,通过页面的 Add 按钮添加认证信息会不成功,可以通过菜单项及左边栏链接跳转到 Jenkins/Manage Jenkins/Configure Credentials/Credentials/System/Global credentials/Add Credentials 进行添加)

slave

当 slave 节点添加成功后,下面正式进行 Jenkins 测试相关的配置。

  1. 搜索并安装 gitlab-plugin 插件
  2. 通过菜单 Jenkins/Manage Jenkins/Configure System 进入 Jenkins 的全局配置页面,找到 Gitlab 的配置条目,并填入如下内容(Connection name 只是个名字而已,可以随意,在后面的 Jenkins 项目配置中会需要用到)

jenkins gitlab conn

如前所述,由于 Jenkins 的 bug,这里的 Credentials 无法通过 Add 按钮添加成功,需要切换至具体的界面进行操作:

jenkins gitlab token

其中 ID 和 Description 无关紧要,ID 要求不能重复,API token 是 gitlab 用户的访问凭证。该用户需要拥有待配置 gitlab 源代码项目的 Developer 权限,以该 gitlab 用户的身份登录并切换至 User Settings/Access Tokens 页面,勾选 api 复选框,然后点击 Create personal access token 按钮进行创建。

gitlab token

  1. 全局配置中一些与测试不相关,但非常重要的配置项简单罗列如下

jenkins global 1
jenkins global 2

至此 Jenkins 全局配置完成。

Jenkins 项目配置

  1. 切换至或新建具体的 Jenkins 项目,在 General/Gitlab connection 下拉框中选择刚才在 Jenkins 全局配置中创建的 gitlab 连接。

jenkins project conn

  1. Source Code Management 中选择 Git,并填入如下内容

jenkins project source

具体的信息由于截图不便于复制,可以访问 gitlab-plugin 的 github 主页获取[1],需要注意第一个 Refspec 中两部分内容通过空格隔开而不是换行。

注:Credentials 里的内容是以 SSH 方式访问 gitlab 的 SSH 私钥信息,如下图所示

gitlab ssh key

该私钥对应的公钥需要添加到前面创建的具有 Developer 权限的 gitlab 用户配置中,以该 gitlab 用户的身份登录并切换至 User Settings/SSH Keys 页面,然后增加一个 SSH key,如下图所示

gitlab ssh key 2

  1. Additional Behaviours 中增加 Merge before build 步骤,具体配置如下

jenkins project build 1

  1. Build Triggers 选择如下所示,其中 Rebuild open Merge Requests 下拉选项选择 On push to source branch,同时注意最上面 GitLab CI Service URL 后面的 URL,待会在配置 gitlab 时会用到

jenkins project build 2

上图中的 Comment (regex) for triggering a build 是一个正则表达式,比如这里填的是 .*retest.*,这样只要在 MR 下面发表包含 retest 关键字的回复,就会触发 jenkins 重新构建/测试。

  1. 增加两个 Post-build Actions,如下所示,不需要任何额外的配置

jenkins project build 3

至此 Jenkins 的所有配置完成。

[1] https://github.com/jenkinsci/gitlab-plugin#jenkins-job-configuration

gitlab 配置

首先以 gitlab 管理员用户登录,编辑前面所说的具有 Developer 权限的用户的属性,并赋予其 admin 权限:

gitlab 1

然后以待配置 gitlab 源代码项目的管理用户帐号(可以是该项目的 Master 用户,或者是 gitlab 管理员用户)登录 gitlab,切换至待配置项目的 Settings/Integrations 配置页面,增加如下所示的 webhook,其中 URL 为前面 jenkins 项目配置中记录的 GitLab CI Service URL

gitlab 2

如果 gitlab 没有使用 HTTPS 访问,则不要勾选 Enable SSL verification

至此 gitlab 的配置完成。

附录

Jenkins 使用英文界面

  1. 搜索并安装 locale 插件
  2. 在 Jenkins 全局配置中配置默认语言如下

jenkins locale

update 20180326

Gitlab 升级至 10.6.0 之后,出现无法触发 jenkins 构建的问题,

https://gitlab.com/gitlab-org/gitlab-ce/issues/44480

https://gitlab.com/gitlab-org/omnibus-gitlab/issues/3307#note_64245578

解决方法

  1. 以管理员身份登录 Gitlab,切换到 Admin Area(点击左上角的 扳手 图标)
  2. 选中左边栏的 Settings,然后页面拉到最后,勾选如下图的复选框:

gitlab 3