1. 配置前的准备工作
在开始配置前，请确保您已具备以下条件：
-
已安装并运行 Jenkins 和 GitLab
-
拥有 GitLab 管理员权限
-
了解基本的 Jenkins 和 GitLab 操作
2. 安装必要的 Jenkins 插件
2.1 安装 GitLab 插件
登录 Jenkins 管理界面
进入 系统管理 > 插件管理 > 可用插件
搜索并安装以下插件：
-
GitLab Plugin（核心插件）
-
Git plugin（Git 集成）
-
Build Authorization Token Root Plugin（Webhook 认证）
2.2 插件配置检查
安装完成后，重启 Jenkins 服务确保插件生效：
sudo systemctl restart jenkins
3. 在 GitLab 中创建访问令牌
3.1 创建 Personal Access Token
登录 GitLab，进入 Settings > Access Tokens
创建新令牌，配置以下权限：
-
api（完全 API 访问）
-
read_repository（读取仓库）
-
write_repository（写入仓库）
保存生成的令牌（稍后在 Jenkins 中需要使用）
3.2 创建 Project Access Token（推荐用于项目级集成）
对于更安全的项目级集成，建议使用项目访问令牌：
进入具体项目 Settings > Access Tokens
创建令牌并选择所需权限
4. 在 Jenkins 中配置 GitLab 连接
4.1 添加 GitLab 服务器配置
进入 系统管理 > 系统配置
找到 GitLab 部分，配置如下：
GitLab 连接名称: gitlab-server
GitLab 主机 URL: https://your-gitlab-domain.com
凭据: 选择或添加 GitLab 访问令牌
4.2 配置凭据
点击 添加 > Jenkins
选择 GitLab API token 类型
输入在 GitLab 中创建的访问令牌
ID 可留空，系统会自动生成
5. 配置 Jenkins 项目连接 GitLab
5.1 创建新的 Jenkins 项目
点击 新建任务
选择 构建一个自由风格的软件项目
输入项目名称
5.2 配置源代码管理
在 源代码管理 部分：
选择: Git
Repository URL: https://gitlab.example.com/your-group/your-project.git
凭据: 添加 GitLab 用户名和密码或 SSH 密钥
分支: */main 或您想要构建的分支
5.3 配置构建触发器
在 构建触发器 部分：
勾选 Build when a change is pushed to GitLab
复制生成的 GitLab webhook URL
生成Secret token
6. 在 GitLab 中配置 Webhook
6.1 添加 Webhook
进入 GitLab 项目 Settings > Webhooks
粘贴从 Jenkins 复制的 Webhook URL
选择触发事件（推荐）：
-
Push events
-
Merge request events
-
Tag push events
如果出现【invalid url given】字样，则需要检查 GitLab 的网络设置
GitLab 默认禁止向本地网络发送 Webhook 请求。需要管理员权限修改设置：
转到 Admin Area > Settings > Network。
勾选 Allow requests to the local network from web hooks and services。
6.2 配置 SSL 验证（可选）
如果使用 HTTPS：
-
勾选 Enable SSL verification（生产环境推荐）
-
或取消勾选（测试环境）
6.3 测试 Webhook
点击 Test 下拉菜单，选择事件类型测试连接：
-
推送事件测试
-
合并请求测试
jenkins回收到相关时间，并执行相关处理。
7. 高级配置选项
7.1 基于分支的构建规则
在 Jenkins 项目的 构建触发器 中配置高级选项：
# 只构建特定分支
Filter branches by name: ^(main|develop)$
# 基于合并请求的构建
Filter merge requests by target branch name: ^main$
7.2 构建状态通知
配置 GitLab 接收构建状态：
在 Jenkins 构建后操作 中添加 Publish build status to GitLab
选择对应的 GitLab 连接
8. Pipeline 项目配置
8.1 使用 Jenkinsfile
在项目根目录创建 Jenkinsfile：
pipeline {
agent any
triggers {
gitlab(
triggerOnPush: true,
triggerOnMergeRequest: true,
branchFilterType: 'All'
)
}
stages {
stage('Build') {
steps {
echo 'Building…'
}
}
stage('Test') {
steps {
echo 'Testing…'
}
}
}
post {
always {
updateGitlabCommitStatus name: 'build', state: 'success'
}
}
}
8.2 多分支 Pipeline 配置
在 Jenkins 中创建 Multibranch Pipeline
配置分支源为 GitLab
设置分支发现策略
9. 安全配置最佳实践
9.1 网络隔离
-
确保 Jenkins 和 GitLab 在同一网络或可互相访问
-
配置防火墙规则限制访问
9.2 凭据管理
-
使用 Jenkins 凭据管理器存储敏感信息
-
定期轮换访问令牌
-
为不同环境使用不同的凭据
9.3 Webhook 安全
# 启用 Secret Token 增强安全性
在 GitLab Webhook 配置中设置 Secret Token
在 Jenkins 项目配置中配置相同的令牌
10. 故障排除常见问题
10.1 Webhook 测试失败
问题：GitLab 显示 "Could not connect to the URL"
解决：
-
检查 Jenkins URL 可访问性
-
验证网络连接和防火墙设置
-
检查 Jenkins 是否运行正常
10.2 认证失败
问题：Failed to connect to repository
解决：
-
验证凭据是否正确
-
检查 GitLab 用户权限
-
确认访问令牌未过期
10.3 构建不触发
问题：代码推送后 Jenkins 不自动构建
解决：
-
检查 Webhook 配置
-
查看 Jenkins 系统日志
-
验证分支过滤规则
11. 监控和日志
11.1 查看构建日志
-
在 Jenkins 项目页面查看构建历史和日志
-
使用 Blue Ocean 插件获得更好的可视化
11.2 GitLab 集成状态
-
在 GitLab 合并请求中查看 Jenkins 构建状态
-
监控 Webhook 最近交付记录
12. 性能优化建议
12.1 构建触发优化
-
设置合理的轮询间隔
-
使用 Webhook 替代 SCM 轮询
-
配置构建队列策略
12.2 资源管理
-
为不同的项目设置不同的执行器
-
使用 Docker 代理实现环境隔离
-
配置构建超时和资源限制
通过以上配置，您就成功建立了 Jenkins 与 GitLab 的完整集成，可以实现代码推送自动构建、合并请求验证等现代化 CI/CD 流程。
