Jenkins - GitLab - GitLab 文档中心

Tier: 基础版，专业版，旗舰版

Offering: JihuLab.com，私有化部署

版本历史

在 13.7 中移至极狐GitLab 基础版。

Jenkins 是一个开源的自动化服务器，支持构建、部署和自动化项目。

你应在以下场景使用 Jenkins 与极狐GitLab 的集成：

你计划将来将 CI 从 Jenkins 迁移到极狐GitLab CI/CD，但需要一个过渡方案。
你已投入 Jenkins 插件并选择继续使用 Jenkins 构建你的应用。

此集成可以在变更推送到极狐GitLab 时触发 Jenkins 构建。

你不能使用此集成从 Jenkins 触发极狐GitLab CI/CD 流水线。相反，应在 Jenkins 作业中使用流水线触发器 API 端点，并使用流水线触发令牌进行认证。

配置 Jenkins 集成后，当你推送代码到仓库或在极狐GitLab 中创建合并请求时，会触发 Jenkins 中的构建。Jenkins 流水线状态会显示在合并请求组件和极狐GitLab 项目的主页上。

要配置 Jenkins 与极狐GitLab 的集成：

授予 Jenkins 对极狐GitLab 项目的访问权限。
配置 Jenkins 服务器。
配置 Jenkins 项目。
配置极狐GitLab 项目。

授予 Jenkins 对极狐GitLab 项目的访问权限#

创建个人、项目或群组访问令牌。
- 创建个人访问令牌以便为该用户的所有 Jenkins 集成使用令牌。
- 创建项目访问令牌仅在项目级别使用令牌。例如，你可以在项目中撤销令牌，而不影响其他项目中的 Jenkins 集成。
- 创建群组访问令牌为该群组内所有项目的所有 Jenkins 集成使用令牌。
将访问令牌范围设置为 API。
复制访问令牌值以配置 Jenkins 服务器。

配置 Jenkins 服务器#

安装并配置 Jenkins 插件以授权与极狐GitLab 的连接。

在 Jenkins 服务器上，选择 管理 Jenkins > 管理插件。
选择可用选项卡。搜索 gitlab-plugin 并选择安装。有关其他安装插件的方法，请参阅 Jenkins GitLab 文档。
选择 管理 Jenkins > 配置系统。
在 GitLab 部分，选择 为 '/project' 端点启用认证。
选择添加，然后选择 Jenkins 凭证提供者。
选择 GitLab API 令牌 作为令牌类型。
在 API 令牌 中，粘贴你从极狐GitLab 复制的访问令牌值并选择添加。
在 GitLab 主机 URL 中输入极狐GitLab 服务器的 URL。
要测试连接，选择 测试连接。

更多信息，请参阅 Jenkins 到 GitLab 的认证。

配置 Jenkins 项目#

设置你打算运行构建的 Jenkins 项目。

在你的 Jenkins 实例上，选择 新建项目。
输入项目名称。
选择 自由风格 或 流水线 并选择确定。你应该选择自由风格项目，因为 Jenkins 插件会在极狐GitLab 上更新构建状态。在流水线项目中，你必须配置一个脚本以在极狐GitLab 上更新状态。
从下拉列表中选择你的极狐GitLab 连接。
选择 当变更推送到极狐GitLab 时构建。
选择以下复选框：
- 接受的合并请求事件
- 关闭的合并请求事件

指定如何将构建状态报告给极狐GitLab：

如果你创建了自由风格项目，在 构建后操作 部分，选择 发布构建状态到极狐GitLab。

如果你创建了流水线项目，你必须使用 Jenkins 流水线脚本在极狐GitLab 上更新状态。

Jenkins 流水线脚本示例：

groovy
1pipeline {
2   agent any
3
4   stages {
5      stage('gitlab') {
6         steps {
7            echo '通知 极狐GitLab'
8            updateGitlabCommitStatus name: 'build', state: 'pending'
9            updateGitlabCommitStatus name: 'build', state: 'success'
10         }
11      }
12   }
13}

更多 Jenkins 流水线脚本示例，请参阅 GitHub 上的 Jenkins GitLab 插件仓库。

配置极狐GitLab 项目#

通过以下方式之一配置极狐GitLab 与 Jenkins 的集成。

使用 Jenkins 服务器 URL#

如果你可以向极狐GitLab 提供 Jenkins 服务器 URL 和认证信息，应使用此方法进行 Jenkins 集成。

在顶部栏中，选择 搜索或跳转到 并找到你的项目。
在左侧边栏中，选择设置 > 集成。
选择 Jenkins。
选中启用复选框。
选择你希望极狐GitLab 触发 Jenkins 构建的事件：
- 推送
- 合并请求
- 标签推送
输入 Jenkins 服务器 URL。
可选。清除 启用 SSL 验证 复选框以禁用 SSL 验证。
输入 项目名称。项目名称应是 URL 友好的，空格替换为下划线。为确保项目名称有效，请在查看 Jenkins 项目时从浏览器地址栏复制它。
如果你的 Jenkins 服务器需要认证，输入 用户名 和密码。
可选。选择 测试设置。
选择 保存更改。

使用 Webhook#

如果你无法向极狐GitLab 提供 Jenkins 服务器 URL 和认证信息，可以配置 Webhook 来集成极狐GitLab 和 Jenkins。

在 Jenkins 作业的配置中，在 GitLab 配置部分，选择高级。
在 密钥令牌 下，选择生成。
复制令牌，并保存作业配置。
在极狐GitLab 中：
- 为你的项目创建 Webhook。
- 输入触发 URL（例如 https://JENKINS_URL/project/YOUR_JOB）。
- 在 密钥令牌 中粘贴令牌。
要测试 Webhook，选择测试。

故障排查#

错误：Connection failed. Please check your settings#

配置极狐GitLab 时，你可能会收到错误 Connection failed. Please check your settings。

此问题有多种可能的原因和解决方案：

原因	解决方法
极狐GitLab 无法访问给定地址的 Jenkins 实例。	对于极狐GitLab 私有化部署，在极狐GitLab 实例上 ping 所提供的域上的 Jenkins 实例。
Jenkins 实例位于本地地址，且未包含在极狐GitLab 安装的允许列表中。	将该实例添加到极狐GitLab 安装的允许列表中。
Jenkins 实例的凭证没有足够的访问权限或无效。	授予凭证足够的访问权限或创建有效凭证。
在你的 Jenkins 插件配置中未选中为 /project 端点启用认证复选框。	选中该复选框。

错误：Could not connect to the CI server#

如果极狐GitLab 未通过提交状态 API 从 Jenkins 收到构建状态更新，你可能会在合并请求中收到错误 Could not connect to the CI server。

当 Jenkins 未正确配置或通过 API 报告状态时出错，会出现此问题。

要修复此问题：

为极狐GitLab API 访问配置 Jenkins 服务器。
配置 Jenkins 项目，并确保如果你创建了自由风格项目，选择了“发布构建状态到极狐GitLab”构建后操作。

合并请求事件未触发 Jenkins 流水线#

当请求超过 Webhook 超时限制（默认设置为 10 秒）时，可能会出现此问题。

对于此问题，请检查：

集成 Webhook 日志中是否有请求失败。

/var/log/gitlab/gitlab-rails/production.log 中是否有类似以下的消息：

plaintext
WebHook 错误 => Net::ReadTimeout

或

plaintext
WebHook 错误 => 执行超时

在极狐GitLab 私有化部署上，你可以通过增加 Webhook 超时值来修复此问题。

在 Jenkins 中启用作业日志#

要排查集成问题，你可以在 Jenkins 中启用作业日志以获取有关构建的更多详细信息。

要在 Jenkins 中启用作业日志：

转到 仪表板 > 管理 Jenkins > 系统日志。
选择 添加新的日志记录器。
输入日志记录器的名称。
在下一个屏幕上，选择添加并输入 com.dabsquared.gitlabjenkins。
确保日志级别为全部并选择保存。

要查看日志：

运行一次构建。
转到 仪表板 > 管理 Jenkins > 系统日志。
选择你的日志记录器并检查日志。

授予 Jenkins 对 极狐GitLab 项目的访问权限#