GitLab CI 集成 SonarQube 实现质量门禁，核心是通过 merge_requests 触发扫描 Job，将质量阈结果转化为 Pipeline 状态；需部署兼容的 SonarQube、GitLab Runner 和项目 Token，安装 GitLab 插件并配置质量阈规则，在 .gitlab-ci.yml 中定义含 SonarScanner 参数的 Job，敏感信息须用受保护变量管理。
GitLab CI 集成 SonarQube 实现质量门禁，核心是让 CI 流水线中的一个 Job 执行代码扫描，并把 SonarQube 的质量阈（Quality Gate）结果转化为 Pipeline 的成功或失败状态——不通过就直接中断后续步骤，比如部署或合并。
1. 前置环境必须到位
确保以下三件套已准备就绪且版本兼容：
-
SonarQube Server：建议用 Docker 部署（如官方
sonarqube:latest），需搭配独立数据库（PostgreSQL 推荐），并开放 9000 端口；启动前务必调大系统参数：vm.max_map_count=262144和文件描述符限制，否则大型项目扫描易崩溃。 -
GitLab Runner：安装在能访问 GitLab 和 SonarQube 的机器上，执行器推荐
docker或shell；注册时赋予足够权限（如gitlab-runner register --executor docker）。 -
GitLab 项目级 Token：在 GitLab 用户 Settings → Access Tokens 中创建，勾选
api、read_user、read_repository；该 Token 将用于 SonarScanner 向 GitLab 回传 MR 状态。
2. 项目中启用 GitLab 插件与质量阈
登录 SonarQube Web 界面，在 Administration → Marketplace 搜索并安装 GitLab Plugin，重启服务。接着进入 Configuration → GitLab 页面填写：
- GitLab URL（如
https://gitlab.example.com） - GitLab User Token（上一步生成的那个）
再进入 Quality Gates，编辑或新建一个门禁规则，例如：
这条规则将作为 MR 合并前的硬性门槛。
3. 在 .gitlab-ci.yml 中定义扫描 Job
以 Maven 项目为例，在项目根目录添加或更新 .gitlab-ci.yml：
sonarqube-check:
image: maven:3.8.1-openjdk-11
script:
- mvn clean verify sonar:sonar
-Dsonar.host.url=http://sonarqube.example.com:9000
-Dsonar.login=your_sonar_token
-Dsonar.gitlab.project_id=$CI_PROJECT_ID
-Dsonar.gitlab.commit_sha=$CI_COMMIT_SHA
-Dsonar.gitlab.ref_name=$CI_COMMIT_REF_NAME
-Dsonar.sources=.
only:
- merge_requests关键点说明：
-
only: merge_requests表示仅对合并请求触发扫描，避免污染主干流水线 -
-Dsonar.gitlab.*参数让 SonarQube 能关联到具体 MR，并在 GitLab UI 中显示“检查通过/失败”徽章 -
sonar.login是 SonarQube 的管理员或项目级 Token（非 GitLab Token），需在 SonarQube 中提前创建
4. 验证与日常维护要点
提交一个 MR 后，观察 GitLab Pipeline 是否自动触发 sonarqube-check Job，并在 MR 页面看到 SonarQube 状态栏。若失败，点击详情可查看具体哪项指标未达标（如覆盖率不足、新增了高危漏洞）。
- 敏感信息如
sonar.login不要写死在 yml 文件里，应设为 GitLab 项目的 CI/CD Variables（标记为 Protected & Masked） - 建议为
main分支配置更严格的质量阈，而feature分支允许临时放宽（如只检查新增问题） - 定期清理 SonarQube 的旧项目快照和 Elasticsearch 索引，防止磁盘爆满
