Quality Gates, Conditions, Policies, and Pipeline Enforcement: Diagnostics, Failure Modes, and Production Practices

1. Diagnostic contract: preserve the first failure

Quality-gate troubleshooting starts by freezing the evidence that existed when the decision was made. Do not rerun the scanner, edit the gate, delete .scannerwork, or lower a threshold before saving the first task/result.

If those artifacts point to different runs, the diagnosis is already contaminated.

2. Evidence-first diagnostic ladder

1. Preserve scanner, CI, API, and gate-definition evidence.
2. Confirm SonarQube edition/version, scanner/runtime, instance mode, and integration versions.
3. Confirm exact Git revision and effective analysis parameters.
4. Inspect indexed-file/report evidence and ceTaskId.
5. Wait for the matching Compute Engine task and inspect its status.
6. Inspect project gate assignment, new-code definition, small-change setting, and actual failed condition values.
7. Only then inspect auth/network/provider or server/database/search resource layers if the evidence points there.
8. Apply the least destructive correction and rerun the smallest equivalent scenario.

3. Failure mode: scanner exit 0, server gate ERROR

This is the chapter’s intentionally broken example. A CI script assumes the scanner return code is the release decision:

# BROKEN POLICY
sonar-scanner -Dsonar.host.url="$SONAR_HOST_URL" -Dsonar.token="$SONAR_TOKEN"
echo "Quality passed; deploy now"

The scanner can exit successfully after upload while the matching background task later computes a failed gate. Prove the mismatch:

cat .scannerwork/report-task.txt
CE_TASK_ID=$(awk -F= '$1=="ceTaskId"{print $2}' .scannerwork/report-task.txt)
curl -fsS -H "Authorization: Bearer $SONAR_TOKEN" \
  "$SONAR_HOST_URL/api/ce/task?id=$CE_TASK_ID"
curl -fsS -H "Authorization: Bearer $SONAR_TOKEN" --get \
  --data-urlencode "projectKey=$PROJECT_KEY" \
  "$SONAR_HOST_URL/api/qualitygates/project_status"

If CE is SUCCESS and gate status is ERROR, the failure is not scanner execution. Repair the CI enforcement layer: use a supported provider quality check or sonar.qualitygate.wait=true. Do not change the project key or threshold.

4. Failure mode: choosing the threshold after seeing the result

A team gets 72% coverage and changes the gate from 80% to 70% that afternoon. The next pipeline is green, but the code did not improve. This is a policy change, not remediation.

Detect it by comparing gate definition/history, revision, and metrics. A legitimate threshold change must have independent rationale, representative impact analysis, approval, and rollback. If the only rationale is “the build was red,” reject the change as post-result tuning.

5. Failure mode: overall-code gate freezes a legacy system

A mature application with years of debt is assigned an overall maintainability/coverage threshold it cannot satisfy. Every unrelated patch fails. Teams respond by accepting issues, suppressing findings, or weakening gates.

The causal problem is policy population, not necessarily analyzer quality. Preserve the overall metrics, new-code metrics, NCD, and gate definition; then evaluate a new-code-focused gate plus a separately governed modernization objective. Do not erase old issues to obtain a green release.

6. Failure mode: “coverage is 0%, but the gate passed”

First inspect the denominator. Under the default small-change mechanism, a coverage condition can be ignored until there are enough new lines to cover. Capture:

• new lines and new lines to cover;
• coverage value;
• the exact coverage condition;
• the project/global “Ignore duplication and coverage on small changes” state;
• the gate’s other condition results.

If the behavior matches the documented fudge factor, there is no defect to fix. Decide separately whether your organization wants a different small-change policy.

7. Failure mode: branch policy copied blindly into a pull request

Pull-request analysis is change-oriented and capability varies by deployment. A condition meaningful only for overall code should not be assumed to enforce identically in a PR. Community Build has narrower branch/PR support than commercial Server.

Diagnose by confirming edition, target branch, analysis type, applicable gate conditions, and provider decoration/check state. If the metric is unavailable in that context, move that control to a supported branch/release analysis or choose an appropriate new-code metric. Do not substitute a random metric just to keep one YAML template.

8. Failure mode: a shared gate changes silently

Two projects analyze unchanged revisions on different days and one unexpectedly flips status. Before blaming scanners, compare gate definition and project assignment timestamps. A shared gate edit can alter subsequent quality decisions across many projects.

Production practice: gate changes are configuration changes. Export/record the old definition, identify affected projects, review representative results, communicate the change, and retain an owner. “Someone with admin rights adjusted it” is not an acceptable audit trail.

9. Shortcuts that destroy diagnostic value

• Do not rerun until the original report-task.txt and CI log are preserved.
• Do not lower thresholds to “test” whether the gate is the problem.
• Do not change project keys to escape history.
• Do not use administrator tokens everywhere.
• Do not disable TLS verification or auth to bypass a provider/network problem.
• Do not edit the SonarQube database/search index directly.
• Do not bulk-accept/suppress issues to make a gate green.

10. Production triage record

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.