Help us learn about your current experience with the documentation. Take the survey.

Jenkins

Tier: 免费版、高级版、旗舰版
Offering: GitLab.com、GitLab 自托管、GitLab 专用

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

当您应该使用 Jenkins 与 GitLab 的集成时：

您计划将来将 CI 从 Jenkins 迁移到 GitLab CI/CD，但需要一个临时解决方案。
您已经投入了 Jenkins 插件的资源，并选择继续使用 Jenkins 来构建您的应用程序。

当有变更推送到 GitLab 时，此集成可以触发 Jenkins 构建。

您不能使用此集成从 Jenkins 触发 GitLab CI/CD 管道。相反，请在 Jenkins 作业中使用 pipeline triggers API 端点，并通过 pipeline trigger token 进行身份验证。

配置 Jenkins 集成后，当您将代码推送到仓库或在 GitLab 中创建合并请求时，您将在 Jenkins 中触发构建。Jenkins 管道状态将显示在合并请求小部件和 GitLab 项目的首页上。

有关 GitLab Jenkins 集成的概述，请参阅使用 Jira 问题和工作流的 GitLab 与 Jenkins 集成。

要配置 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 Pipeline 脚本来更新 GitLab 上的状态。
  
  示例 Jenkins Pipeline 脚本：
```
pipeline {
   agent any

   stages {
      stage('gitlab') {
         steps {
            echo '通知 GitLab'
            updateGitlabCommitStatus name: 'build', state: 'pending'
            updateGitlabCommitStatus name: 'build', state: 'success'
         }
      }
   }
}
```
  有关更多 Jenkins Pipeline 脚本示例，请参阅 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，请选择测试。

故障排除

错误：`连接失败。请检查您的设置`

当您配置 GitLab 时，您可能会收到一条错误消息，显示 连接失败。请检查您的设置。

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

原因	解决方案
GitLab 无法在指定地址访问您的 Jenkins 实例。	对于 GitLab 自托管，请在 GitLab 实例上提供的域中 ping Jenkins 实例。
Jenkins 实例位于本地地址，并且未包含在 GitLab 安装的允许列表中。	将实例添加到 GitLab 安装的允许列表中。
Jenkins 实例的凭据没有足够的访问权限或无效。	授予凭据足够的访问权限或创建有效的凭据。
在您的 Jenkins 插件配置中，未选择为 ‘/project’ 端点启用身份验证复选框	选择该复选框。

错误：`无法连接到 CI 服务器`

如果 GitLab 未通过 Commit Status API 收到来自 Jenkins 的构建状态更新，您可能会在合并请求中收到一条错误消息，显示 无法连接到 CI 服务器。

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

要解决此问题：

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

合并请求事件未触发 Jenkins 管道

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

对于此问题，请检查：

集成 webhook 日志中的请求失败。
/var/log/gitlab/gitlab-rails/production.log 中是否有类似以下的消息：
```
WebHook 错误 => Net::ReadTimeout
```
或
```
WebHook 错误 => 执行已过期
```

在 GitLab 自托管上，您可以通过增加 webhook 超时值来解决此问题。

在 Jenkins 中启用作业日志

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

要在 Jenkins 中启用作业日志：

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

要查看您的日志：

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