合并到main分支时触发SonarQube扫描的最小可行配置是：在GitHub Actions中设置on.push.branches: [main]，配置sonar-scanner命令并传入SONAR_TOKEN和SONAR_HOST_URL，且不指定sonar.branch.*参数以启用主干基准分析与质量门禁检查。
合并到 main 分支时触发 SonarQube 扫描的最小可行配置
Git 分支合并后自动运行 SonarQube，本质是靠 CI 流水线响应分支变更事件来驱动扫描，不是 Git 或 SonarQube 自身具备“监听合并”能力。最直接的做法是在 CI 中对 main 分支的 push 事件（含 merge commit）触发 sonar-scanner。
以 GitHub Actions 为例，关键在于正确设置 workflow 的触发条件和权限：
-
on.push.branches必须显式写成['main']，不能用['*']或['**']—— 否则 PR 合并前的临时分支推送也会触发，造成重复或无效扫描 - 需要在 job 级别添加
permissions: contents: read, packages: read, id-token: write（GitHub-hosted runner 调用 SonarQube OAuth 或 token 鉴权时必需） -
sonar-scanner命令必须指定-Dsonar.projectKey=xxx和-Dsonar.sources=.，否则会因项目标识缺失而静默失败，日志里只报Project not found
为什么 merge commit 没触发扫描？检查这三处
常见现象：PR 合并后没看到 SonarQube 报告更新，流水线也没运行。大概率不是 SonarQube 配置问题，而是 CI 侧漏掉了 merge commit 的识别。
- Git 服务器设置：GitHub 默认开启
Squash and merge，这种操作产生的 commit 属于main上的新提交，能被on.push.branches: [main]捕获；但若团队启用了Rebase and merge或Create a merge commit，且仓库设置了Require linear history，部分平台（如旧版 GitLab CI）可能把 merge commit 归类为 “merge request event”，而非普通 push —— 此时需额外加on.merge_group（GitHub）或on.merge_request（GitLab） - CI 缓存干扰：如果 workflow 使用了
actions/cache缓存node_modules或.sonar目录，而 merge 后未改变 package-lock.json 或源码哈希，scanner 可能跳过分析（尤其sonar.scanner.skip为 true 时）。建议在 scan 步骤开头加rm -rf .sonar - 分支保护规则冲突：GitHub 的 branch protection 若启用
Require status checks to pass before merging，但 SonarQube 的 status check 名字（sonarqube/scan）未填入允许列表，会导致 merge 被阻断，看起来像“没触发”，其实是被卡在前置校验
如何让 SonarQube 区分 feature 分支和 main 分支的扫描结果
SonarQube 默认把所有扫描都归到同一项目下，不区分分支。要实现“feature 分支只做预检、main 分支才进质量门禁”，必须靠 sonar.branch.name 和 sonar.branch.target 控制。
- 在 CI 中对非 main 分支扫描时，传参：
-Dsonar.branch.name=${{ github.head_ref }} -Dsonar.branch.target=main。这样 SonarQube 会将该次扫描标记为“对比 main 的差异分析”，不会覆盖 main 的指标，也不会触发 quality gate - 对
main分支扫描时，**不要**传sonar.branch.*参数 —— 这是关键。SonarQube 会将其视为“主干基准”，启用 full analysis + quality gate 检查 - 注意版本兼容性：
sonar.branch.*在 SonarQube 8.9+ 和 SonarCloud 全面支持；7.9 及以下版本需用sonar.branch（单参数，仅支持 name），且不支持 target 对比
流水线里跑 sonar-scanner 失败但没报错？看这几行日志
sonar-scanner 常静默退出（exit code 0），实际没上传数据。真正有效的判断依据不是“命令是否成功”，而是日志末尾有没有 ANALYSIS SUCCESSFUL 和 More about the report processing at 这两行。
- 典型假成功场景：
INFO: ANALYSIS SUCCESSFUL, you can find the results at: http://sonarqube.example.com/dashboard?id=my-proj—— 这句话出现，才代表数据已发往服务端；若只有EXECUTION SUCCESS，只是本地解析完成，没发出去 - 网络相关失败常被吞掉：比如 SonarQube 服务端 TLS 证书不可信，
sonar-scanner会 fallback 到 HTTP（若配置了sonar.host.url=http://...），但不报 warning。建议在 scan 前加curl -I -k ${SONAR_HOST_URL}/api/server/version验证连通性 - Java 版本陷阱：SonarQube 9.x 要求 scanner 运行在 Java 11+，但很多 CI runner 默认是 Java 8。错误表现为日志卡在
Load project repositories后无响应 —— 加java -version和echo $JAVA_HOME排查
分支合并后的质量检测不是加个插件就完事，真正卡点永远在 CI 事件捕获的准确性、SonarQube 分支语义的显式声明、以及 scanner 网络链路的可观测性上。少一个，就会出现“以为跑了，其实没跑”或者“跑了，但结果没进对的地方”。
