sonarqube-quality-gate

SonarQube Quality Gate Enforcement

Overview

A quality gate is a set of conditions that a project must pass to be considered ready. When a quality gate fails, the project status is ERROR and cannot be merged/deployed. This skill guides interpretation and remediation of quality gate failures.

Quality Gate Conditions

Security-Critical Conditions (Fix First)

Security Rating

• Requirement: A (no open vulnerabilities)
• Failure: CRITICAL or HIGH severity vulnerabilities remain open
• Action: Remediate vulnerabilities using the sonarqube-remediation skill
• Verify: Re-scan and confirm severity is reduced

Blocker Issues

• Requirement: 0 BLOCKER issues
• Failure: Issues with BLOCKER severity exist
• Action: Fix immediately — blockers indicate critical problems
• Common causes: Null pointer dereferences, unclosed resources, infinite loops

Code Quality Conditions

Code Coverage

• Requirement: Typically ≥ 80% (project-configured)
• Failure: Coverage below threshold
• Action: Write unit tests to cover uncovered lines
• Focus: Test critical paths and error handling

Duplicated Lines

• Requirement: Typically < 3% (project-configured)
• Failure: Too much code duplication
• Action: Extract duplicate code into reusable functions/classes

Maintainability Rating

• Requirement: A or B
• Failure: Code complexity too high (Cyclomatic Complexity > 15)
• Action: Refactor complex functions into smaller, testable units

Reliability Rating

• Requirement: A or B
• Failure: Too many bugs detected
• Action: Fix identified bugs, improve error handling

Remediation Process

Step 1: Fetch Quality Gate Status

curl -H "Authorization: Bearer $SONARQUBE_TOKEN" \
  "https://sonar.example.com/api/qualitygates/project_status?projectKey=my-project"

Response structure:

{
  "projectStatus": {
    "status": "ERROR",
    "conditions": [
      {
        "status": "ERROR",
        "metricKey": "security_rating",
        "operator": "GREATER_THAN",
        "errorThreshold": "1",
        "actualValue": "3"
      }
    ]
  }
}

Step 2: Identify Security-Relevant Failures

Prioritize conditions in this order:

1. Security Rating — Always fix first
2. Blocker Issues — Fix before Quality issues
3. Coverage — Fix to prevent regressions
4. Complexity & Duplication — Refactor for long-term health

Step 3: Remediate Each Condition

For Security Rating failures:

• Use sonarqube-remediation skill to fix vulnerabilities
• Re-scan after fixes
• Transition fixed issues via API: POST /api/issues/do_transition

For Coverage failures:

• Write unit tests for uncovered lines
• Aim for > 85% coverage on security-sensitive code
• Use test framework conventions (Jest, pytest, etc.)

For Complexity failures:

• Break large functions into smaller, focused functions
• Extract cyclomatic complexity by using early returns, guard clauses
• Add comments explaining complex logic

For Duplication failures:

• Extract repeated code into utility functions
• Use inheritance or composition to share code patterns
• Consider refactoring similar functions into a single parameterized version

Step 4: Re-Run Quality Gate Check

After fixes:

# Trigger a new SonarQube analysis
sonar-scanner \
  -Dsonar.projectKey=my-project \
  -Dsonar.host.url=https://sonar.example.com \
  -Dsonar.login=$SONARQUBE_TOKEN

# Verify gate status
curl -H "Authorization: Bearer $SONARQUBE_TOKEN" \
  "https://sonar.example.com/api/qualitygates/project_status?projectKey=my-project"

Expected result: "status": "OK"

Quality Gate Best Practices

• Security First: Never accept CRITICAL or HIGH vulnerabilities
• Progressive Improvement: Gradually increase coverage and reduce complexity
• Test-Driven: Write tests alongside fixes for coverage
• Regular Reviews: Check gate status during development, not just before merge
• Document Rules: Keep team aligned on which conditions are mandatory vs. aspirational

Troubleshooting

Condition	Cause	Solution
Security Rating fails	Known vulnerabilities	Remediate using sonarqube-remediation skill
Coverage drops	Missing tests	Write unit tests for new code
Complexity spike	Large refactor	Break into smaller PRs or functions
Duplication increases	Code copy-paste	Extract into shared utilities
Intermittent failures	Test flakiness	Fix non-deterministic tests