SonarQube Quality Gates
A Quality Gate is a set of pass/fail conditions that every scan must satisfy. It is SonarQube's most powerful enforcement tool. This topic explains how Quality Gates work, how to configure them, and how to use them in CI/CD pipelines.
The Quality Gate Concept
Think of a Quality Gate like a border checkpoint. Your code must pass all the checks at the checkpoint before it is allowed to continue. If it fails any check, the pipeline stops and developers receive a notification to fix the issues.
CODE COMMITTED
|
v
[SCAN RUNS]
|
v
[QUALITY GATE CHECK]
|
+-- All conditions pass? --> PASSED --> Code continues to deploy
|
+-- Any condition fails? --> FAILED --> Pipeline stops, fix required
The Sonar Way Gate (Default)
SonarQube ships with a built-in gate called Sonar Way. It focuses entirely on new code — code written since the last analysis or a defined baseline date. The default conditions are:
SONAR WAY DEFAULT CONDITIONS (on new code) +-------------------------------------------+ | Coverage on new code >= 80% | | Duplicated lines on new <= 3% | | Maintainability rating = A | | Reliability rating = A | | Security rating = A | | Security hotspots reviewed = 100% | +-------------------------------------------+
If any single condition is not met, the gate status is FAILED.
Why Focus on New Code
Most legacy projects have many existing issues accumulated over years. Requiring the entire codebase to be clean before deploying anything would halt all development immediately. The new code approach lets teams enforce quality on all new work without being blocked by old problems. Over time, as developers fix old issues and write new clean code, the overall project quality improves naturally.
EXISTING PROJECT WITH LEGACY ISSUES +-----------------------------------------------+ | OVERALL CODE: 500 bugs, 200 vulnerabilities | | | | NEW CODE (this sprint): 0 bugs, 0 vuln = PASS | +-----------------------------------------------+ The gate checks only the NEW CODE portion.
Creating a Custom Quality Gate
Administrators create custom gates at Quality Gates in the top navigation. The built-in Sonar Way gate cannot be edited, but you can copy it and modify the copy.
- Go to Quality Gates in the navigation bar
- Click Copy next to Sonar Way
- Name your copy (for example,
Strict Gate) - Add, remove, or change conditions
- Click Set as Default if you want all projects to use it
Available Condition Metrics
You can build conditions using these metrics:
METRIC CATEGORY EXAMPLE CONDITIONS ----------------- ------------------------------------------ Reliability Bugs = 0 | Reliability Rating = A Security Vulnerabilities = 0 | Security Rating = A Maintainability Code Smells = 0 | Technical Debt Ratio <= 5% Coverage Coverage >= 80% | Uncovered Lines <= 100 Duplications Duplicated Lines <= 3% Size Lines of code (rarely used in gates)
Each condition targets either overall code or new code. Using new code is strongly recommended for most conditions.
Assigning a Gate to a Project
By default, all projects use the default Quality Gate. To assign a different gate to one project:
- Open the project dashboard
- Go to Project Settings > Quality Gate
- Select your custom gate from the dropdown
- Save
PROJECT SETTINGS: QUALITY GATE +----------------------------------------------+ | Use project-specific quality gate: [ON] | | | | Quality gate: [Strict Gate ▼] | | | | [Save] | +----------------------------------------------+
Quality Gate Status in the Dashboard
The Quality Gate status appears prominently at the top of every project dashboard. It shows either a green Passed badge or a red Failed badge.
PASSED DASHBOARD FAILED DASHBOARD +--------------------+ +--------------------+ | QUALITY GATE | | QUALITY GATE | | [ ✓ PASSED ] | | [ ✗ FAILED ] | | | | | | All conditions | | Coverage: 64% | | met | | Required: >= 80% | +--------------------+ +--------------------+
Using the Quality Gate in CI/CD
The SonarScanner CLI returns an exit code based on the Quality Gate result. You can use this in any CI/CD system:
# The scanner waits for server analysis and then checks the gate sonar-scanner \ -Dsonar.qualitygate.wait=true \ -Dsonar.qualitygate.timeout=300 # Exit code 0 = PASSED (pipeline continues) # Exit code 1 = FAILED (pipeline stops)
The sonar.qualitygate.wait=true parameter is critical. Without it, the scanner finishes before the server completes its analysis, so the gate result is not checked.
Notifications on Gate Failures
SonarQube sends email notifications when a Quality Gate status changes — from Passed to Failed, or from Failed to Passed. Configure notifications under My Account > Notifications. Each user can choose which events trigger a notification and for which projects.
Quality Gate vs Code Review
QUALITY GATE (automated) CODE REVIEW (human) ----------------------------- ---------------------------- Runs every scan automatically Happens when PR is opened Checks objective metrics Evaluates logic and design Blocks bad code instantly Requires reviewer availability Same rules for every developer Reviewer judgment varies
Quality Gates and code reviews complement each other. The gate handles objective, measurable checks. Human reviewers handle subjective decisions about design and architecture.
Gradual Quality Gate Tightening
For teams new to SonarQube, starting with a strict gate from day one can be overwhelming. A practical approach:
- Month 1: Gate requires only 0 new blockers and 0 new critical vulnerabilities
- Month 2: Add coverage requirement of 50% on new code
- Month 3: Raise coverage to 70%, add reliability rating A requirement
- Month 6: Use the full Sonar Way conditions
This staged approach lets the team build the habit of clean code without stopping all delivery momentum on day one.