Protect New Code with SonarQube Quality Gates

The Legacy Debt Wall

When a team first runs SonarQube on a mature application, the dashboard often shows hundreds or thousands of existing bugs, vulnerabilities, and code smells. If the build is configured to fail on any issue, the pipeline turns red immediately and developers stop trusting the tool. The practical alternative is to stop measuring the entire history and start measuring only what changed.

Quality Gates for New Code

A Quality Gate is a binary pass/fail signal based on boolean conditions. In SonarQube, the Clean as You Code approach scopes those conditions to New Code, which is the code added or modified since a chosen reference point such as the previous version or a specific date. Legacy issues remain visible but do not block new merges.

The New Code period can be defined as the period since the previous version, since a specific date, or since the last analysis. Choosing the wrong reference makes the gate either too lenient or too strict. For teams deploying frequently, Previous Version usually works best; for long-lived branches, a fixed date may be clearer.

Worked Example: Enforce Coverage on New Code

Suppose a project has 15 percent overall coverage, and the team wants every new pull request to be tested without requiring months of retroactive work. Create a custom gate named Incremental-Coverage with these conditions:

Metric	Operator	Value	Scope
Coverage on New Code	is less than	80%	New Code
New Bugs	is greater than	0	New Code
New Vulnerabilities	is greater than	0	New Code

Assign this gate to the project. A commit that introduces untested code causes the gate to fail, while pre-existing low coverage does not.

Pipeline Check

SonarQube calculates gate status asynchronously, so the scanner can finish before the server evaluates the new analysis. Run this check on the CI runner after scanning. The runner needs a SonarQube token with permission to read project quality gate status.

# Run on the CI runner with SONAR_TOKEN exported
curl -s -u "$SONAR_TOKEN:" "https://sonarqube.internal/api/qualitygates/project_status?projectKey=my-app" | grep '"status:"'

If the response contains ERROR, exit the pipeline with a non-zero code. Alternatively, set sonar.qualitygate.wait=true in the scanner invocation so the scanner blocks until evaluation completes. Checking too early risks reading the previous commit's status.

Limitations and Verification

Overly strict gates on legacy repositories create alert fatigue. Start with a single condition, such as zero new critical bugs, then add coverage thresholds after the team adjusts. Also, verify the New Code period definition; if it is tied to a version that is rarely updated, the window can grow large enough to include old debt.

To verify the setup, create a test project, assign the custom gate, push a commit with no new tests, and confirm the dashboard shows FAIL before merging. Then push a second commit with adequate coverage and confirm the status returns to OK. This round-trip confirms the gate reacts to new code rather than legacy issues.