Using SonarQube Quality Gates to Enforce Branch‑Specific Code Quality in CI

Why a Gate Matters for Every Branch

When a feature branch lands in a CI pipeline, the build should only pass if the new code meets the team’s quality expectations. A Quality Gate in SonarQube is that gate: a set of conditions that an analysis must satisfy to be considered green. If any condition fails, the gate turns red and the pipeline can be stopped or the pull request flagged.

What a Quality Gate Looks Like in SonarQube 10.x

A default gate in a fresh SonarQube 10.x instance contains:

• New Code Bugs = 0
• New Code Vulnerabilities = 0
• New Code Coverage ≥ 80%
• Must be green for all branches (if enabled)

These conditions are applied automatically to every project analysis. They can be overridden per‑branch or per‑pull‑request by assigning a different gate to that branch.

Creating a Branch‑Specific Gate

1. Log into the SonarQube UI, go to Quality Gates and click Copy on the default gate.
2. Rename the copy, e.g., Feature‑Gate, and edit the New Code Coverage threshold to 90% for a critical module.
3. Under Gate conditions, add a rule to Must be green for all branches that match the regex ^feature/.*$. This ensures any feature branch will use this gate.
4. Save the gate. It now applies automatically to any branch whose name starts with feature/.

Note: Custom gates and branch‑specific rules are only available in the Developer Edition and above. The Community Edition cannot enforce per‑branch gates.

Integrating the Gate into a CI Pipeline

Below is a minimal GitHub Actions workflow that runs SonarQube analysis on a feature branch and fails the build if the gate is not green.

name: SonarQube Scan
on:
  pull_request:
    branches:
      - main
jobs:
  sonar:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Set up JDK 17
        uses: actions/setup-java@v3
        with:
          distribution: temurin
          java-version: 17
      - name: SonarQube Scan
        uses: sonarsource/sonarqube-scan-action@v2
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
        with:
          args: "-Dsonar.branch.name=${{ github.head_ref }}"
      - name: Fail if gate is red
        if: steps.sonar.outcome != 'success'
        run: exit 1

Key points:

• The -Dsonar.branch.name parameter tells the scanner which branch to analyze. SonarQube then automatically selects the gate configured for that branch.
• SonarQube sets the exit code to 1 if the gate fails, so the CI step can fail the job.
• Using the sonarsource/sonarqube-scan-action keeps the workflow concise; replace it with sonar-scanner if you prefer a custom setup.

Programmatic Gate Status Retrieval

Sometimes you want to surface the gate status in a custom dashboard or trigger an automated rollback. SonarQube exposes a REST endpoint for this:

curl -u ${SONAR_TOKEN}: \
  "https://sonarqube.example.com/api/qualitygates/project_status?projectKey=${PROJECT_KEY}&branch=${BRANCH_NAME}"

The JSON response contains a status field with values OK, ERROR, or WARN. Use this in scripts to decide whether to proceed.

Trade‑Offs and Practical Tips

• Strictness vs. Developer Friction – Raising coverage to 90% or banning any new bug can block legitimate changes. Start with moderate thresholds, monitor how often the gate fails, and iterate.
• New Code Period – By default SonarQube considers the last 90 days as new code. If your workflow defines new code differently, adjust the New Code Period setting under Administration > General Settings > New Code to avoid unexpected failures.
• Scan Time – Adding many conditions or scanning large modules can lengthen analysis. Enable incremental analysis or limit the sonar.sources to the changed packages to keep pipelines fast.
• Language Plugins – Some metrics rely on language‑specific plugins (e.g., security vulnerabilities for Java). Ensure the necessary plugins are installed; otherwise the gate may ignore those conditions.
• Maintenance – As the codebase evolves, gates can drift. Automate a nightly report that compares the current gate thresholds to the baseline and flags any changes.

How to Verify the Gate Works in Your Environment

1. In the SonarQube UI, navigate to Quality Gates and confirm your custom gate exists.
2. Run a test analysis on a feature branch: sonar-scanner -Dsonar.branch.name=feature/test (ensure you have the necessary permissions).
3. Check the project dashboard – the Gate status should show green or red based on the new code.
4. Optionally, call the REST API endpoint shown above and confirm the status field matches the UI.

If the gate fails but the analysis shows no issues, double‑check the New Code Period and that the branch name matches the gate’s regex. If the gate passes but you see violations, verify the metrics are enabled for your language plugin.

Actionable Takeaway

By creating a branch‑specific Quality Gate and wiring it into your CI pipeline, you can:

• Prevent low‑quality code from entering the main branch.
• Provide developers with immediate, actionable feedback.
• Maintain a consistent quality baseline across all feature work.

Start small – copy the default gate, bump the coverage threshold for your critical module, and watch the gate status in your PRs. Iterate based on real data, and you’ll build a culture of quality that scales with your codebase.