Jenkins 配置 GitLab 集成指南

5.1 创建新的 Jenkins 项目

1. 点击 新建任务
2. 选择 构建一个自由风格的软件项目
3. 输入项目名称

5.2 配置源代码管理

在 源代码管理 部分：

选择：Git
Repository URL: https://gitlab.example.com/your-group/your-project.git
凭据：添加 GitLab 用户名和密码或 SSH 密钥
分支：*/main 或您想要构建的分支

5.3 配置构建触发器

在 构建触发器 部分：

1. 勾选 Build when a change is pushed to GitLab
2. 复制生成的 GitLab webhook URL
3. 生成 Secret token

6. 在 GitLab 中配置 Webhook

6.1 添加 Webhook

1. 进入 GitLab 项目 Settings > Webhooks
2. 粘贴从 Jenkins 复制的 Webhook URL
3. 选择触发事件（推荐）：
   • Push events
   • Merge request events
   • Tag push events

如果出现【invalid url given】字样，则需要检查 GitLab 的网络设置。

GitLab 默认禁止向本地网络发送 Webhook 请求。需要管理员权限修改设置：

1. 转到 Admin Area > Settings > Network。
2. 勾选 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 接收构建状态：

1. 在 Jenkins 构建后操作 中添加 Publish build status to GitLab
2. 选择对应的 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 配置

1. 在 Jenkins 中创建 Multibranch Pipeline
2. 配置分支源为 GitLab
3. 设置分支发现策略

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 流程。