Enforcing SonarQube Quality Gates in CI Pipelines

The Problem: Analyses That Never Block Anything

Running SonarQube in CI without a Quality Gate produces a report, not a control. The scanner uploads findings, the server computes metrics, and the build finishes successfully even when coverage drops or new bugs appear. A Quality Gate fixes this by attaching pass/fail criteria to the analysis, but the criteria only matter if the pipeline waits for the server's verdict.

How Quality Gates Work

A Quality Gate is a server-side rule set evaluated after each analysis. When the scanner finishes uploading the report, the server recomputes metrics for the project and compares them against the gate's conditions. If any condition marked as ERROR is violated, the gate fails. The scanner can then be told to poll the server until the evaluation completes and to exit with a non-zero status if the gate fails.

Two pieces must be in place: the gate itself, defined and assigned in the SonarQube UI, and the scanner property sonar.qualitygate.wait=true in the build command.

Defining a Gate in the SonarQube UI

Creating or editing a gate requires the Quality Gate Administrator permission (or the equivalent global admin role). Without it, the UI may hide the create option or silently reject the change.

Navigate to Quality Gates and choose Create. Give the gate a descriptive name, then add one or more conditions. Each condition selects a metric, an operator, and a threshold, and assigns a severity. The severity determines whether a violation fails the gate.

Worked Example: Coverage Threshold

Setting	Value
Gate name	Coverage Gate
Metric	Coverage
Operator	is less than
Threshold	80%
Severity	ERROR

After saving, assign the gate to the target project. You can set it as the default for all new projects, or override it per project under the project's Quality Gate settings.

Making the Pipeline Wait for the Verdict

By default, the scanner uploads the report and exits. It does not wait for the server to evaluate the gate. Adding sonar.qualitygate.wait=true changes that: the scanner polls the server until the gate result is ready, then fails the build if the status is ERROR.

Run the scanner from your CI job's working directory, using a token with execute-analysis permissions. The exact property syntax depends on the scanner.

# Maven example
mvn verify sonar:sonar \
  -Dsonar.host.url=https://sonarqube.example.com \
  -Dsonar.token=$SONAR_TOKEN \
  -Dsonar.projectKey=my-project \
  -Dsonar.qualitygate.wait=true

For Gradle, pass the same property to the sonarqube task, either as a system property or within the task configuration, depending on the plugin version.

The wait mode adds latency proportional to the server's processing time and the polling interval.

Verifying the Gate Is Active

1. In the SonarQube UI, open Quality Gates and confirm the condition appears with the correct metric and threshold.
2. Open the target project and verify the assigned gate name matches the one you created.
3. Run a pipeline with sonar.qualitygate.wait=true and inspect the build log. The scanner output should include a line reporting the quality gate status, such as QUALITY GATE STATUS: ERROR when the threshold is violated.
4. Check the project's overview page: a failed gate displays the violated condition.

Limits and Common Mistakes

• Only computed metrics. Gates evaluate metrics produced by the analysis itself. They cannot query external systems, check deployment health, or enforce policies outside SonarQube's data model.
• Silent permission failures. If the CI token lacks the Execute Analysis permission, the upload may be rejected and the gate never runs.
• Metric name drift. After a SonarQube upgrade, metric keys can change. A condition referencing an old key may be silently ignored rather than raising an error, leaving the gate weaker than intended.
• Too many conditions. A gate with dozens of ERROR conditions can produce noisy output. Some CI integrations surface only the first failure, which can mask the most actionable violation.
• Missing wait flag. The most common failure mode: the gate evaluates correctly on the server, but the build completes before the result is known, so the pipeline never blocks.

Rolling Back a Gate Change

Quality Gates are server-side configuration, so changes persist until reverted. To roll back:

1. Open Quality Gates, select the gate, and delete the added condition—or delete the gate entirely if it is not the default.
2. If the gate was assigned to a specific project, open that project's Quality Gate settings and reassign it to the previous gate or the default.
3. If the CI configuration was modified to add sonar.qualitygate.wait=true, remove that property from the pipeline definition if the wait behavior is no longer desired.

Re-run the analysis after rollback to confirm the project returns to the expected pass/fail behavior.