Quality Gates, Conditions, Policies, and Pipeline Enforcement: Core Concepts and Mental Model

1. Current baseline and chapter boundary

A quality gate is not a scanner option that decides whether source code is “good.” It is a server-side policy evaluation performed after an analysis report has been accepted and processed. The scanner discovers and analyzes files, uploads a report, and records task metadata. SonarQube’s Compute Engine then processes that report, persists measures and findings, and evaluates the quality gate assigned to the project.

That ordering matters. A scanner process can finish successfully while the background task is still queued, and a background task can succeed while the resulting quality gate fails. A CI job becomes a release control only when it deliberately connects those states.

2. The problem: a green command is not a release decision

Imagine a CI log that ends with EXECUTION SUCCESS. That means the scanner completed its own work and uploaded the analysis report. It does not, by itself, prove that Compute Engine processed the report successfully, that the project used the expected gate, that the gate passed, or that the CI provider enforced that result.

A trustworthy gate answers a narrower, auditable question: for this exact analyzed revision, under this exact gate definition and new-code policy, did the computed measures satisfy every applicable condition? A trustworthy pipeline then decides what to do with that answer.

3. Mental model: analysis result to delivery policy

flowchart TD
R[Repository revision] --> S[SonarScanner]
S --> AR[Analysis report]
AR --> CE[Compute Engine task]
CE --> M[Persisted measures and findings]
G[Assigned gate definition] --> E[Gate evaluator]
N[New-code definition] --> E
M --> E
E --> QS[Gate status: OK or ERROR]
QS --> UI[SonarQube UI/API]
QS --> CI[CI gate check or scanner wait]
CI --> D[Delivery decision]

The repository revision and effective scanner inputs identify what was analyzed. The analysis report is uploaded evidence, not the final gate. Compute Engine owns asynchronous processing. The assigned gate definition supplies metric/operator/threshold conditions. The new-code definition determines the population for conditions scoped to new code. The resulting gate status is then exposed to the UI/API and, only if configured, to CI enforcement.

4. Keep the gate states separate

5. Current Sonar way: a read-only new-code gate

As of this chapter’s 2026-09-07 baseline, Community Build’s built-in Sonar way quality gate is read-only and is the default gate unless another gate is assigned. Its policy is intentionally new-code focused:

• No new issues are introduced.
• All new Security Hotspots are reviewed.
• New-code test coverage is at least 80%.
• New-code duplication is at most 3%.

The user-facing wording is stable, but the exact metrics behind “No new issues” depend on the instance mode. In MQR Mode and Standard Experience, issue/rating metrics differ. Record the instance mode and inspect the actual gate definition rather than copying condition keys from a different release or mode.

6. Small changes and the quality-gate fudge factor

Coverage and duplication percentages can swing wildly on tiny diffs. Current Community Build therefore enables a quality-gate “fudge factor” by default: coverage conditions are ignored until there are at least 20 new lines to cover, and duplication conditions are ignored until there are at least 20 new lines. The setting is global by default and may be overridden for a project.

This is not permission to ignore small changes. Issue and hotspot conditions still matter, and the underlying coverage metric remains evidence. The operational lesson is to record whether sonar.qualitygate.ignoreSmallChanges or the corresponding UI setting is in force before diagnosing an unexpected pass.

7. Read-only inspection before policy changes

Start with state discovery. The UI is the least ambiguous way to see names and conditions; authenticated Web API calls are useful evidence when automation is needed.

export SONAR_HOST_URL="http://localhost:9000"
# Keep a real token in an environment/secret store. Do not paste it into HTML, source, or shell history.

# Server identity
curl -fsS "$SONAR_HOST_URL/api/server/version"

# Gate inventory (authentication requirements depend on instance security settings)
curl -fsS -H "Authorization: Bearer $SONAR_TOKEN" \
  "$SONAR_HOST_URL/api/qualitygates/list"

# Inspect the built-in gate without modifying it
curl -fsS -H "Authorization: Bearer $SONAR_TOKEN" --get \
  --data-urlencode "name=Sonar way" \
  "$SONAR_HOST_URL/api/qualitygates/show"

# After a project analysis, retrieve the project gate status
curl -fsS -H "Authorization: Bearer $SONAR_TOKEN" --get \
  --data-urlencode "projectKey=academy-sq-ch11" \
  "$SONAR_HOST_URL/api/qualitygates/project_status"

Record the raw response as evidence, but treat Web API paths as release-sensitive. The platform is gradually moving endpoints to Web API V2, so the instance’s own API documentation remains authoritative.

8. DevOps control: policy must be correlated to a task

A release gate is reproducible only if an auditor can connect revision → effective analysis inputs → report → ceTaskId → CE completion → assigned gate → gate status → CI decision. If any link is missing, “the gate failed” is an incomplete diagnosis.

This chapter therefore never uses gate color as standalone truth. Every later lesson preserves the gate definition and task identity alongside the result.

Knowledge check

Official references and version notes

• Understanding quality gates — conditions, Sonar way, new/overall code, and the small-change fudge factor.
• Managing custom quality gates — creation, condition changes, permissions, and review/update workflow.
• Changing a project quality gate and fudge factor — project assignment and small-change configuration.
• Quality standards and new code — new-code definitions and Clean-as-You-Code context.
• Scanner-only analysis parameters — sonar.qualitygate.wait, timeout, and report-task.txt.
• CI integration overview — supported quality-gate enforcement patterns.
• Analysis overview — asynchronous server-side processing and quality-gate computation.
• Feature comparison — Community Build versus Server/Cloud branch and pull-request boundaries.
• Web API — authenticated API usage and Web API V2 migration guidance.
• SonarQube releases — current Community Build and Server/LTA release identities.
• SonarScanner CLI 8.1.0.6389 — scanner baseline used by the local lab.