概述

在 DevOps 实践中，将 Jenkins 流水线的执行状态实时反馈到 GitLab 合并请求（Merge Request，MR）页面，可以让开发人员在代码评审阶段直观地看到 CI 结果，无需在 Jenkins 和 GitLab 之间来回切换，从而提升研发协作效率、保障代码质量。

本文档按配置的先后顺序描述了通过  GitLab Webhook + Jenkins Pipeline 插件  实现 Jenkins 流水线状态在 GitLab MR 页面展示的完整流程。流水线脚本采用  Pipeline Script （直接在 Jenkins Job 中编写）格式。

集成效果：

• 在 GitLab MR 页面顶部显示整体流水线状态（running / passed / failed）
• 在每次提交（commit）旁显示该提交对应的构建状态徽章
• 在 MR 详情页可查看流水线阶段（stages）的执行情况
• 支持点击状态徽章跳转到 Jenkins 任务详情页

前置条件

在开始配置之前，请确保以下条件已满足：

配置流程总览

本文档按以下顺序进行配置，请严格按步骤执行：

┌─────────────────────────────────────────────────────────────┐
│  Step1  安装 Jenkins 插件                                   
│  Step2  在 GitLab 创建访问令牌                              
│  Step3  在 Jenkins 配置 GitLab 连接（依赖 Step2 的 Token）  
│  Step4  在 Jenkins 创建流水线任务                           
│  Step5  配置 GitLab Webhook 触发器（依赖 Step3 的连接）    
│  Step6  在 GitLab 配置 Webhook（依赖 Step5 的触发器 URL）   
│  Step7  在 Jenkinsfile 中回传流水线状态                     
│  Step8  端到端验证与测试                                    
│  Step9  配置 GitLab MR 合并门禁                             
└─────────────────────────────────────────────────────────────┘

⚠️ 配置顺序很重要：后续步骤依赖前序步骤生成的凭证、连接名称和触发器 URL。

第一步：安装 Jenkins 插件

Jenkins 默认不包含 GitLab 集成能力，需要先安装相关插件。

操作步骤：

• 登录 Jenkins，进入  Manage Jenkins → Plugins → Available plugins
• 搜索并勾选以下插件：

• 点击  Download now and install after restart ，或选择  Install without restart 。
• 安装完成后，重启 Jenkins 确保插件生效。

验证：

进入  Manage Jenkins → Configure System ，能找到  GitLab  配置区块，说明 GitLab Plugin 安装成功。

第二步：在 GitLab 创建访问令牌

Jenkins 需要一个具有 API 权限的 Token 用于向 GitLab 回传流水线状态。

操作步骤：

1. 创建专用用户：建议在 GitLab 中创建一个专门用于 Jenkins 的用户（如命名为 Jenkins)。
2. 获取 API Token：登录该用户，进入 Profile Settings -> Account（或 Access Tokens），生成一个具有 api 权限的私人访问令牌（Private API Token）
3. 点击  Add new token ，填写如下信息：
• Name ： jenkins-pipeline-status
• Scopes ：勾选  api （必须）、 read_repository
• Expiration date ：按需设置，建议不超过 1 年
• 生成token ：点击  Create project access token 。
• 保存token ：仅展示一次，请妥善保存，后续 Step 3 将使用。
4. 授予项目权限：将该用户添加到对应的 GitLab 代码仓库成员中，并至少授予 Developer 角色。如果需要在构建成功后自动接受合并请求，则需要 Maintainer 或 Owner 权限。

⚠️  安全提示 ：该 Token 等同于 API 凭证，切勿提交到代码仓库或写入日志。

第三步：在 Jenkins 配置 GitLab 连接

使用 Step 2 中生成的 Token，在 Jenkins 侧建立与 GitLab 的连接。

操作步骤：

1. 进入  Manage Jenkins → Configure System ，找到  GitLab  配置区。
2. 点击  Add GitLab Server ，填写：
• Name ： gitlab-server （记住此名称，Step 7 的  gitLabConnection  需引用）
• Server URL ： http://<gitlab-host>
3. 在  Credentials  下拉点击  Add → Jenkins ，弹出凭据配置框：
• Kind ：选择  GitLab API token
• API token ：粘贴 Step 2 中生成的 Token
• ID ： gitlab-api-token
4. 点击  Add  保存凭据。
5. 回到 GitLab Server 配置，在  Credentials  下拉选择刚创建的  gitlab-api-token 。
6. 点击  Test Connection ，返回  Success  表示连接正常。
7. 点击页面底部  Save / Apply  保存配置。

验证：

Test Connection  返回  Success ，且连接名称  gitlab-server  已保存。

注意：

这里配置之后可能会导致 gitlab 仓库代码发生变更后无法正常触发流水线，返回  Hook executed successfully but returned HTTP 403 ，解决方式可以看后文的常见问题2。

第四步：在 Jenkins 创建流水线任务

创建一个 Pipeline 类型的 Job，用于承载后续的触发器与构建逻辑。

操作步骤：

1. Jenkins 首页 →  New Item 。
2. 输入任务名称，如  gitlab-mr-pipeline 。
3. 选择  Pipeline  类型，点击  OK 。
4. 在  General  区配置：
• 描述 ：填写描述信息
• GitLab Connection ：如果有这个选项，就选择 Step 3 中的 gitlab 连接名称（这里上文是  gitlab-server ）
5. 在  Pipeline  区配置：
• Definition ：选择  Pipeline script
• Script ：暂时先不填写（可参考 Step 7 中 Pipeline Script 内容）
6. 暂时先不保存触发器，前往 Step 5。

第五步：配置 GitLab Webhook 触发器

在 Jenkins Job 中启用 GitLab 触发器，生成接收 Webhook 的 URL，供 Step 6 使用。

配置教程可以参考文档 A11_gitlab自动触发 jenkins 示例(TODO:修改超链接)

操作步骤：

1. 进入 Step 4 创建的 Job 配置页，找到  Build Triggers  区。
2. 勾选  Build when a change is pushed to GitLab 。
3. 记录页面显示的  GitLab webhook URL ，格式如下：
   http: // <jenkins-host> /project/gi tlab-mr-pipeline
   该 URL 将在 Step 6 填入 GitLab Webhook。
4. 点击  Advanced ，做如下配置：
• ✅  Push Events
• ✅  Opened Merge Request Events
• ...  其他按需选择
• Trigger  勾选：
5. 保存 Job 配置。

第六步：在 GitLab 配置 Webhook

将 Step 5 生成的 Jenkins Webhook URL 配置到 GitLab，使 GitLab 能将 MR 事件推送给 Jenkins。

配置教程可以参考文档 A11_gitlab自动触发jenkins示例(TODO:修改超链接)

操作步骤：

1.进入 GitLab 项目  Settings → Webhooks 。

2.URL  填写 Step 5 中记录的 Jenkins Webhook URL：

http://<jenkins-host>/project/gitlab-mr-pipeline

如果 Jenkins 启用了 CSRF 保护，使用带凭据的 URL：

http://<jenkins-user>:<api-token>@<jenkins-host>/project/gitlab-mr-pipeline

3.Trigger  勾选：

• ✅  Merge request events
• ✅  Push events （可选）

4.去掉  Enable SSL verification  的勾选（若 Jenkins 自签证书），生产环境建议保持启用。

5.点击  Add webhook  保存。

验证 Webhook：

在 Webhook 列表点击  Test → Merge request events ，GitLab 会发送测试请求。

• 若返回  Hook executed successfully: HTTP 200 ，说明配置成功。
• 若返回  Hook executed successfully but returned HTTP 403 ，解决方式可以看后文的常见问题2。

第七步：在 Jenkinsfile 中回传流水线状态（Pipeline Script 格式）

前六步完成了"触发 → 构建"的链路，本步骤通过  updateGitlabCommitStatus  和  gitlabCommitStatus  将构建状态回传到 GitLab MR。

Pipeline Script 完整示例：

将以下脚本填写到 Step 4 中 Job 配置的  Pipeline → Script  文本框中：

pipeline {
    agent any
 
    options {
        // 这里的名称必须与 Jenkins 系统配置中 GitLab 连接名称一致（引用 Step 3 中的连接名称）
        gitLabConnection('gitlab-server')
    }
 
    stages {
        stage('打印所有参数与环境变量') {
            steps {
                script {
                    echo "================ 开始打印 ================"
                    sh '''
                        # 只打印用户定义的或自定义的变量，过滤掉系统路径等杂项
                        printenv | sort
                    '''
                    echo "================ 打印结束 ================"
                }
 
            }
        }
        stage('Build') {
            steps {
                updateGitlabCommitStatus name: 'jenkins/build', state: 'running'
                // 模拟任务执行
                sh 'echo "building..."; sleep 60'
                updateGitlabCommitStatus name: 'jenkins/build', state: 'success'
            }
        }
        stage('Test') {
            steps {
                updateGitlabCommitStatus name: 'jenkins/test', state: 'running'
                // 模拟任务执行
                sh 'echo "testing..."; sleep 60'
                updateGitlabCommitStatus name: 'jenkins/test', state: 'success'
            }
        }
    }
    post {
        success {
            updateGitlabCommitStatus name: 'jenkins/build', state: 'success'
            updateGitlabCommitStatus name: 'jenkins/test', state: 'success'
        }
        failure {
            updateGitlabCommitStatus name: 'jenkins/build', state: 'failed'
            updateGitlabCommitStatus name: 'jenkins/test', state: 'failed'
        }
        aborted {
            updateGitlabCommitStatus name: 'jenkins/build', state: 'canceled'
            updateGitlabCommitStatus name: 'jenkins/test', state: 'canceled'
        }
    }
}

关键点说明：

• options { gitLabConnection('gitlab-server') } ：指定 Step 3 中配置的 GitLab 连接名称， 必须一致 。
• updateGitlabCommitStatus name: 'jenkins/build', state: '...' ：向 GitLab MR 回传指定阶段的状态，name 会作为 MR 页面上的状态徽章名称。
• state  取值包括： running 、 success 、 failed 、 canceled 。
• post  块用于在流水线整体结束后统一回传最终状态，避免中间阶段异常导致状态不一致。

状态回传时序示意：

Stage: Build
  ├─ running  → GitLab MR 显示 jenkins/build 🟡
  ├─ success  → GitLab MR 显示 jenkins/build 🟢
Stage: Test
  ├─ running  → GitLab MR 显示 jenkins/test 🟡
  ├─ success  → GitLab MR 显示 jenkins/test 🟢
post:
  ├─ success  → 最终回传 success

1. 使用 gitlabCommitStatus 包裹（简化写法）：

pipeline {
    agent any
 
    options {
         // 这里的名称必须与 Jenkins 系统配置中 GitLab 连接名称一致（引用 Step 3 中的连接名称）
        gitLabConnection('gitlab-server')
    }
 
    stages {
        stage('Build') {
            steps {
                gitlabCommitStatus(name: 'jenkins/build') {
                    sh 'echo "building..."; sleep 60'
                }
            }
        }
        stage('Test') {
            steps {
                gitlabCommitStatus(name: 'jenkins/test') {
                    sh 'echo "testing..."; sleep 60'
                }
            }
        }
    }
}

gitlabCommitStatus { ... }  会自动在阶段开始时回传  running ，结束时根据步骤结果回传  success  或  failed ，写法更简洁。

第八步：端到端验证与测试

完成前七步后，执行端到端验证。

验证流程：

1. 在 GitLab 创建一个新的 MR（或更新已有 MR 的源分支提交）。
2. 观察 Jenkins 是否自动触发构建：
• Jenkins 任务页面出现新的构建记录
• 构建日志中出现  Triggered by GitLab Merge Request  字样
3. 打开 GitLab MR 页面，应看到：
• 顶部  Pipeline  区块显示流水线状态
• 提交记录旁出现状态图标（时钟/对勾/叉号）
• jenkins/build 、 jenkins/test  等独立状态徽章
4. 点击状态徽章，可跳转到 Jenkins 对应构建详情页。

运行效果：

状态对照表：

第九步：配置 GitLab MR 合并门禁

状态回传成功后，可在 GitLab 侧启用合并门禁，强制 MR 在流水线通过后才能合并。

操作步骤：

1. 进入 GitLab 项目  Settings → Merge requests 。
2. 在  Merge checks  区勾选：
• ✅  Pipelines must succeed
• ✅  All threads must be resolved （可选）
3. Merge method  按需选择：Merge commit / Fast-forward / Rebase。
4. Squash commits when merging  按需开启。
5. 保存配置。

至此，形成"代码提交 → Webhook 触发 → Jenkins 构建 → 状态回传 → MR 合并门禁"的完整闭环。

常见问题排查

Q1：GitLab MR 页面不显示流水线状态

排查步骤：

1. 检查 Jenkins Job 是否被正确触发（查看构建历史）。
2. 检查 Pipeline Script 中  gitLabConnection('gitlab-server')  名称是否与 Step 3 配置一致。
3. 检查 GitLab Token 权限是否包含  api （Step 2）。
4. 查看 Jenkins 日志是否有  Failed to update GitLab commit status  报错。

Q2：Webhook 触发失败，GitLab 显示  Hook executed successfully but returned HTTP 403

原因 ：Jenkins 启用了 CSRF 保护，拒绝未携带 Token 的请求。

解决 ：

• 方案 A：在 Step 6 的 Webhook URL 中嵌入  user:api-token@host 。
• 方案 B：在 Jenkins  Configure Global Security  中为 GitLab 单独配置 Token，或允许匿名读取（这里按照图中配置是最简单快速的），
• 方案 C：在 Jenkins Job 的  Build Triggers → Advanced  中生成  Secret token ，将该 Token 填入 GitLab Webhook 的  Secret token  字段。

Q3：状态回传失败，日志提示 401 Unauthorized

原因 ：Token 过期或权限不足（Step 2 / Step 3 配置问题）。

解决 ：

1. 重新生成 GitLab Access Token（Step 2）。
2. 在 Jenkins 凭据中更新 Token（Step 3）。
3. 重新执行  Test Connection 。

Q4：多分支场景下状态串台

原因 ：未按分支过滤触发器。

解决 ：

• 在 Step 5 的  Advanced → Allowed branches  中配置分支过滤。
• 或使用  GitLab Branch Source Plugin  自动按分支创建 Job。

Q5：自签证书导致 HTTPS 请求失败

解决 ：

在 Jenkins 启动参数中添加：

-Dcom.sun.jersey.client.apache.config.ApacheHttpClientConfigConfig.DISABLE_ENCODED_SLASH=true
-Djsse.enableSNIExtension=false
-Djavax.net.ssl.trustStore=/path/to/truststore.jks

或将 GitLab 证书导入 Jenkins 信任库。

Q6：Pipeline Script 语法错误导致 Job 无法执行

排查步骤：

1. 在 Jenkins Job 页面使用  Replay  功能查看上次构建脚本。
2. 使用 Jenkins 内置的  Pipeline Linter （ /pipeline-syntax ）校验脚本语法。
3. 确认  options 、 stages 、 post  等顶层块顺序正确。

最佳实践

1. 严格按顺序配置 ：Step 2 的 Token、Step 3 的连接名称、Step 5 的 Webhook URL、Step 7 的  gitLabConnection  名称需前后一致。
2. 最小权限原则 ：GitLab Token 仅授予  api  与  read_repository ，不授予写权限。
3. 专用用户 ：建议在 GitLab 中为 Jenkins 创建专用用户，避免使用个人账号 Token。
4. 细化阶段状态 ：使用多个  updateGitlabCommitStatus name: 'jenkins/xxx'  让 MR 页面展示分阶段状态，便于快速定位失败点。
5. 统一命名规范 ：阶段状态名称建议使用  jenkins/  格式，便于在 MR 页面分组展示。
6. 失败快速反馈 ：将单元测试、Lint 等快速检查放在流水线前端，尽早回传  failed  状态。
7. post 块兜底 ：在  post  块中统一回传最终状态，避免中间阶段异常导致状态不一致。
8. 凭证集中管理 ：Token、SSH Key 等敏感信息统一使用 Jenkins Credentials，禁止明文写入 Pipeline Script。
9. 定期轮转 Token ：建议每 90 天轮转一次 GitLab Access Token。
10. 开启合并门禁 ：Step 9 的  Pipelines must succeed  是质量闭环的关键，务必开启。
11. 缓存与并行化 ：利用 Jenkins 并发构建和依赖缓存缩短流水线时长，提升 MR 反馈速度。