背景
从 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 的用户通过创建 MR 的形式向项目提交代码合入请求,当创建 MR 或向已有的 MR 提交新的 commit 时 gitlab 会通过 webhook 触发 Jenkins master 上的 gitlab-plugin 插件进行相应的操作,比如触发 Jenkins 的构建任务、单元测试任务等,最后任务的完成情况会反馈在 gitlab 的界面上。
配置步骤
从前面的测试框架各组件交互图可以大致看到,配置涉及 Jenkins、Jenkins 项目以及 gitlab 等三个部分的配置,下面将对这三个部分的配置以图示的方式进行说明。
Jenkins 配置
由于 Jenkins slave 节点的配置如果不熟悉的话可能有一些麻烦,因此首先简单介绍如何添加 slave 节点(Jenkins 会以当前浏览器的语言环境显示页面语言,本文附录介绍了选择特定语言的方法,本文以 Jenkins 英文界面为基础进行描述)。
- 安装 Jenkins 插件时可能需要配置代理(可以通过上传本地已下载好的插件进行安装,但大多数插件都会依赖于其它底层插件,因此如果能联网安装的话最好进行联网安装),通过
Jenkins/Manage Jenkins/Manage Plugins
菜单进入Advanced
页面(该页面中间部分即通过手动上传插件的功能),配置合适的代理服务器地址
- 搜索并安装 SSH slave 插件
- 主界面侧边栏点击
Build Executer Status
链接,进入Jenkins/Nodes
配置页面
- 点击侧边栏 New Node 链接,添加新 slave 节点
- 新节点的配置最关键的两个选项选择如下(注:这个版本的 Jenkins 有 bug,通过页面的 Add 按钮添加认证信息会不成功,可以通过菜单项及左边栏链接跳转到
Jenkins/Manage Jenkins/Configure Credentials/Credentials/System/Global credentials/Add Credentials
进行添加)
当 slave 节点添加成功后,下面正式进行 Jenkins 测试相关的配置。
- 搜索并安装 gitlab-plugin 插件
- 通过菜单
Jenkins/Manage Jenkins/Configure System
进入 Jenkins 的全局配置页面,找到 Gitlab 的配置条目,并填入如下内容(Connection name
只是个名字而已,可以随意,在后面的 Jenkins 项目配置中会需要用到)
如前所述,由于 Jenkins 的 bug,这里的 Credentials 无法通过 Add 按钮添加成功,需要切换至具体的界面进行操作:
其中 ID 和 Description 无关紧要,ID 要求不能重复,API token 是 gitlab 用户的访问凭证。该用户需要拥有待配置 gitlab 源代码项目的 Developer
权限,以该 gitlab 用户的身份登录并切换至 User Settings/Access Tokens
页面,勾选 api 复选框,然后点击 Create personal access token
按钮进行创建。
- 全局配置中一些与测试不相关,但非常重要的配置项简单罗列如下
至此 Jenkins 全局配置完成。
Jenkins 项目配置
- 切换至或新建具体的 Jenkins 项目,在
General/Gitlab connection
下拉框中选择刚才在 Jenkins 全局配置中创建的 gitlab 连接。
- 在
Source Code Management
中选择 Git,并填入如下内容
具体的信息由于截图不便于复制,可以访问 gitlab-plugin 的 github 主页获取[1],需要注意第一个 Refspec 中两部分内容通过空格隔开而不是换行。
注:Credentials
里的内容是以 SSH 方式访问 gitlab 的 SSH 私钥信息,如下图所示
该私钥对应的公钥需要添加到前面创建的具有 Developer
权限的 gitlab 用户配置中,以该 gitlab 用户的身份登录并切换至 User Settings/SSH Keys
页面,然后增加一个 SSH key,如下图所示
Additional Behaviours
中增加Merge before build
步骤,具体配置如下
Build Triggers
选择如下所示,其中Rebuild open Merge Requests
下拉选项选择On push to source branch
,同时注意最上面GitLab CI Service URL
后面的 URL,待会在配置 gitlab 时会用到
上图中的 Comment (regex) for triggering a build
是一个正则表达式,比如这里填的是 .*retest.*
,这样只要在 MR 下面发表包含 retest 关键字的回复,就会触发 jenkins 重新构建/测试。
- 增加两个
Post-build Actions
,如下所示,不需要任何额外的配置
至此 Jenkins 的所有配置完成。
[1] https://github.com/jenkinsci/gitlab-plugin#jenkins-job-configuration
gitlab 配置
首先以 gitlab 管理员用户登录,编辑前面所说的具有 Developer
权限的用户的属性,并赋予其 admin
权限:
然后以待配置 gitlab 源代码项目的管理用户帐号(可以是该项目的 Master 用户,或者是 gitlab 管理员用户)登录 gitlab,切换至待配置项目的 Settings/Integrations
配置页面,增加如下所示的 webhook,其中 URL 为前面 jenkins 项目配置中记录的 GitLab CI Service URL
如果 gitlab 没有使用 HTTPS 访问,则不要勾选 Enable SSL verification
至此 gitlab 的配置完成。
附录
Jenkins 使用英文界面
- 搜索并安装 locale 插件
- 在 Jenkins 全局配置中配置默认语言如下
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
解决方法
- 以管理员身份登录 Gitlab,切换到 Admin Area(点击左上角的 扳手 图标)
- 选中左边栏的
Settings
,然后页面拉到最后,勾选如下图的复选框:
最后修改于 2019-01-10