很多团队一上来就先往`.gitlab-ci.yml`里塞扫描命令，结果跑是能跑，后面要么MR不出结果，要么质量门禁没法拦合并，要么分支和MR参数还互相打架。SonarQube官方文档把这条链路拆得很清楚，GitLab CI集成至少有三步，先在SonarQube里把项目建好并和GitLab关联，再把分析任务接进GitLab CI/CD，最后再让MR分析和质量门禁结果回写到GitLab。真正稳的做法，不是先写脚本，而是先把项目绑定、扫描入口和MR触发条件摆顺。
一、SonarQube GitLab CI集成怎么做
GitLab CI集成这一步，重点不是只把扫描命令跑通，而是让CI能稳定识别当前是在跑主分支、普通分支，还是Merge Request。官方说明里已经写明，GitLab CI/CD是SonarScanner能自动识别分支和合并请求参数的CI之一，所以前面项目和流水线只要接法正确，后面就不需要再额外手工塞一套MR参数。
1、先在SonarQube里创建或导入项目，并把GitLab仓库关联起来。项目先绑定好，后面质量门禁状态和MR装饰结果才有地方回写。
2、再把`sonar.token`和`sonar.host.url`放进GitLab CI/CD Variables，不要把认证信息直接写死在仓库脚本里。官方把这两个参数明确列成GitLab CI的基础认证入口。
3、在`.gitlab-ci.yml`里单独建一个SonarQube分析任务，并用`rules`或同类条件把它挂到主分支和`merge_request_event`上。官方给出的GitLab示例就是按这个思路组织的。
4、把`GIT_DEPTH`设为`0`，避免浅克隆。官方明确提醒，浅克隆或部分检出会导致blame信息缺失，甚至出现找不到ref的问题，影响分析结果和MR判定。
二、SonarQube MR分析怎么配置
MR分析真正关键的，不是“能不能扫到代码”，而是“扫描时识别到的到底是不是当前这个MR”。SonarQube官方对Pull Request analysis的要求很明确，CI本地仓库必须检出源分支、拉到目标分支，并且保留有效的Git元数据；同时，GitLab CI/CD本身就在SonarScanner的自动检测名单里，所以只要流水线环境干净，MR参数通常不需要手工再传。
1、先确保CI里检出了MR的源分支，同时也能拿到目标分支。官方把这两项都列为MR分析前提，少了任何一边，MR对比基线都会不稳。
2、不要随手手工设置`sonar.pullrequest.key`、`sonar.pullrequest.branch`、`sonar.pullrequest.base`，除非你的场景确实不能自动识别。官方明确提醒，只要手工设置了这些参数，就会覆盖自动检测。
3、MR流水线要真的被触发。SonarQube官方在GitLab集成页写得很清楚，Developer Edition及以上要分析MR，就得在`.gitlab-ci.yml`里用`rules`让`merge_request_event`进分析任务，而不是只跑普通分支流水线。
4、如果想让质量门禁失败直接影响流水线，可以在扫描命令里加`sonar.qualitygate.wait=true`。官方说明，这样扫描任务会等待质量门禁结果，并在质量门禁失败时让CI任务失败。
三、SonarQube MR结果怎么回写到GitLab
很多团队前面扫描已经跑通了，最后还是会说“为什么MR页面什么都没有”。这通常不是扫描没执行，而是项目绑定、MR装饰或GitLab合并规则没有接上。官方文档写得很直接，SonarQube可以把质量门禁状态和分析指标直接报告到GitLab Merge Request里，但前提是GitLab集成和项目级配置都已经完成；另外，GitLab侧如果要拦合并，还得把Merge Checks里的流水线成功要求一起开起来。
1、先确认项目是不是绑定项目。绑定项目在SonarQube里会自动配置质量门禁状态回写，非绑定项目则需要你在项目设置里手工补GitLab配置名和Project ID。
2、MR页面里能看到的是质量门禁状态和分析指标，不要预期它会像某些平台那样给你逐行内联注释。官方文档明确说明，GitLab这边支持MR装饰，但不支持inline annotations。
3、如果你希望质量门禁不通过时直接阻止合并，就去GitLab项目的Merge requests设置里把`Pipelines must succeed`打开。SonarQube官方把这一步直接写进了GitLab项目级配置说明。
4、最后再看版本能力边界。MR和分支分析不是Community Edition的能力，官方明确说明，Merge Request和Pull Request分析从Developer Edition起才支持，所以版本先要对得上。
总结
SonarQube GitLab CI集成怎么做，SonarQube MR分析怎么配置，真正要抓住的是三条线。第一条线是项目绑定和认证，把SonarQube项目和GitLab仓库先接上；第二条线是GitLab CI分析任务，把扫描任务挂到主分支和`merge_request_event`，同时保留完整Git历史；第三条线是结果回写和合并控制，把质量门禁状态送回GitLab，再用`Pipelines must succeed`去约束MR。顺着这条线搭，后面的MR分析通常会比一开始就堆参数稳得多。
