SonarQube质量门禁怎么配置 SonarQube质量门禁不触发怎么排查

质量门禁的价值不在于看板上多一个红绿灯，而在于它能把代码扫描结果变成可执行的准入规则。配置时要先把门禁规则定清楚，再把项目和门禁绑定好，最后在流水线里把门禁结果接回来并决定是否中断构建，否则你会看到门禁已经失败但流水线照样放行的情况。

一、SonarQube质量门禁怎么配置

门禁配置建议从新代码入手，因为团队更容易接受对新增变更严格、对历史遗留循序推进的节奏。你按下面顺序做，基本能把门禁规则、项目绑定、扫描口径三件事一次搭好。

1、确认你有配置门禁的权限

先用管理员账号登录，进入【Administration】→【Security】→【Global Permissions】确认自己具备Administer Quality Gates权限，没有权限时你能看到门禁页面但无法保存条件。

2、新建或复制一套质量门禁

进入顶部【Quality Gates】→点击【Create】新建门禁，或在现有门禁右侧【Actions】里选择复制后再改条件，建议在名称里写清适用范围，例如仅新代码或全量代码，便于后续维护。

3、添加门禁条件并优先选新代码指标

在门禁详情页点击【Add Condition】，优先添加新代码维度的条件，例如New Bugs为0、New Vulnerabilities为0、New Code Coverage大于某个阈值、New Duplicated Lines Density小于某个阈值，先把新增风险卡住，再逐步把全量指标收紧。

4、把门禁设为默认或只绑定到指定项目

想让所有新项目默认套用，进入【Quality Gates】→选中目标门禁→【Actions】→【Set as default】；只想对某个项目生效，进入项目→【Project Settings】→【Quality Gate】→选择Always use a specific Quality Gate→选中你的门禁→【Save】。

5、把新代码口径定清楚避免指标看起来不变化

进入项目→【Project Settings】→【New Code】选择新代码定义方式，例如按Previous version或Number of days，门禁里很多新代码指标都依赖这个口径，口径不一致会导致你以为门禁没触发，实际是新代码范围为空。

二、SonarQube质量门禁不触发怎么排查

所谓不触发，通常分成两类：一类是SonarQube已计算出门禁结果但流水线没接住，另一类是分析报告还在排队或失败导致门禁状态拿不到。排查时先用页面确认门禁状态是否已生成，再回头看流水线是否等待并处理该状态。

1、先确认项目是否真的产生了本次分析结果

进入项目首页看是否出现最新一次分析时间与分析摘要，没有更新就先回到CI检查Scanner是否把报告提交成功，别在门禁上反复改条件。

2、门禁状态一直是未就绪就查后台任务

进入项目→【Project Settings】→【Background Tasks】查看最新任务是否Pending或Failed，分析日志显示EXECUTION SUCCESS也不代表已处理完成，门禁状态要等后台任务完成后才会稳定可用。

3、流水线没有等待门禁结果就加等待机制

如果你的流水线在扫描后立刻结束或进入下一阶段，门禁可能还没算出来，解决思路是让扫描步骤等待门禁状态。在Scanner侧可启用sonar.qualitygate.wait为true并设置超时，让扫描阶段轮询直到拿到门禁结果并在失败时让流水线失败。

4、用Jenkins流水线时检查是否用了等待门禁步骤

在Jenkins流水线里，确认扫描之后有waitForQualityGate步骤，并按需启用abortPipeline，这一步会暂停流水线直到SonarQube计算完门禁并返回状态，否则你会看到门禁失败但流水线仍是成功。

5、门禁条件看似没生效就核对门禁绑定与分支口径

先回到项目→【Project Settings】→【Quality Gate】确认当前项目确实绑定了你刚配置的门禁；如果你在分支或合并请求上跑分析，再核对新代码定义与分析目标分支是否一致，避免门禁条件作用在你没看的维度上。

6、依赖Webhook的链路要确认Webhook能送达

有些集成是靠Webhook把分析完成事件推给外部系统，Webhook会在分析完成时触发，并且可能不依赖门禁状态是否已最终变化，因此要在【Project Settings】→【Webhooks】或全局Webhook里核对地址与连通性，必要时在接收端打日志确认收到回调。

三、SonarQube质量门禁是否已触发怎么确认

这一段只做一件事，把门禁从配置到落地做一次闭环验收，确认你看到的红绿灯会真实影响构建结果。

1、在页面直接确认门禁结果与失败条件

进入项目首页查看Quality Gate状态并点进去，看是哪个条件触发失败，先把页面证据拿到手，再回CI对照同一次分析。

2、用后台任务定位本次分析是否完成处理

进入项目→【Project Settings】→【Background Tasks】找到对应分析任务，确认状态为Success并打开日志留存关键时间点，避免因排队导致CI拿到的是上一轮门禁。

3、在CI里做一次故意失败的对照测试

临时把某个门禁条件收紧到必失败，例如把New Code Coverage阈值调到当前项目达不到的值，触发一次分析，观察页面门禁是否变红以及流水线是否按预期失败，验证通过后再把阈值改回合理范围。

总结

配置质量门禁时，先在【Quality Gates】建立条件并优先基于新代码指标，再通过【Project Settings】→【Quality Gate】绑定到项目，并在【New Code】把新代码口径定清楚。遇到门禁不触发，先查【Project Settings】→【Background Tasks】确认分析是否处理完成，再确认流水线是否等待门禁结果，常用做法是启用sonar.qualitygate.wait或在Jenkins里使用waitForQualityGate，最后用一次故意失败的对照测试把门禁落地效果验收清楚。