Using SonarQube Quality Gates to Enforce Code Quality Thresholds

Useful answer

SonarQube’s Quality Gate feature automatically evaluates whether new code meets predefined quality thresholds (e.g., bug count, coverage, duplication). If any condition fails, the gate returns an ERROR status that you can use to fail a build or block a merge.

Mechanism – worked configuration

1. Create a Quality Gate

1. Log in to SonarQube as an administrator.
2. Navigate to Administration → Quality Gates → Create.
3. Name the gate, e.g., my‑project‑gate.
4. Click Add Condition and choose:
• New Bugs → <= 0
• New Coverage → >= 80
5. Save the gate.

2. Bind the gate to a project

1. Open the project (Projects → your‑project).
2. Go to Project Settings → Quality Gate.
3. Select the gate you just created and click Set as default.

3. Run analysis with sonar-scanner

Execute the scanner on the machine that has access to the source code and network connectivity to the SonarQube server.

# Replace placeholders with your values
sonar-scanner \
  -Dsonar.projectKey=my-app \
  -Dsonar.sources=. \
  -Dsonar.host.url=http://sonarqube:9000 \
  -Dsonar.login=$SONAR_TOKEN

Where to run: Any CI agent or developer workstation with the scanner installed.

Permissions: Read access to the source directories; a user token with scan permission (or admin if you also manage gates).

Expected check: The scanner log ends with a line like Analysis report uploaded in Xs and later Quality gate status: OK or ERROR.
4. Consume the gate status
SonarQube does not fail the build by itself. Your CI must treat a non‑zero exit code from sonar-scanner or poll the gate status.

  
Simple approach: Add -Dsonar.qualitygate.wait=true to the scanner command; the scanner will block until the gate is evaluated and return exit code 1 on ERROR.
  
API approach: After analysis, call:

curl -s -u $SONAR_TOKEN: "http://sonarqube:9000/api/qualitygates/project_status?projectKey=my-app"

The JSON response includes a status field (OK or ERROR) and a conditions array showing each condition’s evaluation.
Limits

  
Conditions apply to new code (changes since the last analysis) unless you explicitly enable overall conditions.
  
Only simple thresholds are supported; you cannot combine conditions with logical AND/OR inside a single gate.
  
The gate itself does not block a build; you must configure your CI to react to the status or exit code.

Common mistakes

  
Failing to bind the gate to the project – the analysis runs but uses the default gate (often Sonar way) and you may miss your custom thresholds.
  
Using an outdated scanner (< 4.0) that does not send the required analysisId for gate evaluation, causing the gate to appear as NONE.
  
Assuming a gate failure will automatically abort the build; without sonar.qualitygate.wait=true or a manual API check, the CI may continue despite an ERROR.
  
Mixing overall and new‑code conditions unintentionally, which can make a gate pass when new code is bad but overall metrics are still acceptable.

Verification

  
Create a gate with a single condition, e.g., New Bugs <= 0.
  
Bind it to a test project.
  
Run sonar-scanner on a clean repository; confirm the dashboard shows Quality gate status: OK and the log contains that line.
  
Introduce a bug (e.g., add int unused = 1;) and re‑run analysis; the gate should change to ERROR and the CI should fail if you used sonar.qualitygate.wait=true.
  
Optionally, query the API as shown above to see the conditions array reflect the failure.