Choosing Between Leak Period and Overall Quality Gates in SonarQube

Decision and Constraints

When you configure a SonarQube Quality Gate you must decide whether the gate evaluates only the code that has changed since a reference branch (the Leak Period) or the entire codebase (Overall). The choice impacts how quickly you get feedback on new work, how much pressure is placed on legacy issues, and what effort is required to keep the gate passing.

Constraints to consider:

1. Size and age of the existing codebase – a large legacy base makes it difficult for an Overall gate to pass because all existing violations count.
2. Team capacity to address technical debt – if the team spends most of its time on feature work, a Leak Period gate lets them focus on new code while tolerating known debt.
3. Availability of a stable reference branch (e.g., main or master) – Leak Period calculations rely on this branch; frequent rebases or force‑pushes can corrupt the leak calculation.
4. Desired feedback latency – Leak Period gives a pass/fail result shortly after a change is analyzed, whereas Overall may require fixing many pre‑existing issues before the gate turns green.

Option Comparison

Option	Metrics evaluated	When to use	Effect on legacy	Typical gate conditions
Leak Period (new code)	New Bugs, New Vulnerabilities, New Code Smells, New Coverage, New Duplications	Active development, feature branches, pull‑request validation	Legacy issues are ignored; existing debt can accumulate	New Bugs ≤ 0, New Vulnerabilities ≤ 0, New Code Smells ≤ 5, New Coverage ≥ 80%
Overall (all code)	Overall Bugs, Vulnerabilities, Code Smells, Coverage, Duplication, Reliability Rating, Security Rating	Mature projects, debt‑reduction initiatives, release gating	All code counted; legacy violations must be fixed to pass	Overall Bugs ≤ 0, Overall Vulnerabilities ≤ 0, Overall Code Smells ≤ 10, Overall Coverage ≥ 85%

Trade‑offs

Leak Period provides rapid feedback on the quality of newly added or modified code. It reduces pressure on legacy debt, allowing teams to ship features while still enforcing a baseline for new work. The downside is that existing technical debt can grow unnoticed because the gate does not penalize it.

Overall forces continual improvement of the entire codebase, leading to a higher baseline quality over time. However, on a large legacy system the gate may fail frequently, causing frustration and potentially encouraging work‑arounds that bypass quality checks. Achieving an Overall gate pass often requires dedicated effort to clean up existing violations.

Concrete Implementation Example

Below is a step‑by‑step guide to create a Leak Period‑based Quality Gate named “New‑Code Gate” and use it in a Jenkins pipeline.

1. Create the gate in SonarQube UI

1. Log in to SonarQube with a user that has the Administer Quality Gates permission.
2. Navigate to Quality Gates → Create.
3. Enter the name New‑Code Gate and optionally a description.
4. Click the New Code tab.
5. Add the following conditions (click Add Condition for each):
   • New Bugs – is less than or equal to 0
   • New Vulnerabilities – is less than or equal to 0
   • New Code Smells – is less than or equal to 5
   • New Coverage – is greater than or equal to 80
6. Save the gate.
7. Optionally set it as the default gate for new projects under Configuration → Quality Gates → Set as default.

2. Configure the Jenkins pipeline

Assuming you have the SonarQube Scanner installed and configured as a global tool named SonarQubeScanner, add the following snippet to your Jenkinsfile (run with sufficient permissions to execute the scanner and access the SonarQube server):

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                // your build steps here
            }
        }
        stage('SonarQube Analysis') {
            steps {
                withSonarQubeEnv('MySonarQube') {   // configure server connection
                    sh '''${tool name: "SonarQubeScanner", type: "sonarqubeScanner"}/bin/sonar-scanner \
                        -Dsonar.projectKey=my-project \
                        -Dsonar.sources=. \
                        -Dsonar.qualitygate.wait=true \
                        -Dsonar.qualitygate.timeout=300'''
                }
            }
        }
    }
    post {
        always {
            // optional: publish SonarQube results
        }
    }
}

The parameters sonar.qualitygate.wait=true and sonar.qualitygate.timeout=300 cause the pipeline to pause until the Quality Gate is evaluated (or until five minutes elapse). If the gate fails, the step throws an error and the pipeline is marked FAILED.

Validation Steps

After the analysis completes, you can confirm the gate outcome in three ways:

1. SonarQube dashboard – open the project page; the Quality Gate badge at the top shows OK when all new‑code conditions are satisfied, otherwise ERROR.
2. CI log – look for a line similar to INFO: Quality gate status is OK (or ERROR) printed by the scanner.
3. Webhook payload – if you have configured a webhook for quality‑gate events, the payload includes gate.status. You can assert in automated tests that this value equals OK.

Practical check: create a short‑lived feature branch, intentionally introduce a new bug (e.g., add assert false; in Java), push the branch, and run the pipeline. The pipeline should fail and the log should contain a message indicating that the New Bugs condition was violated. Reverting the change and re‑running should result in a passing gate.

Limitations and Mitigations

The Leak Period gate relies on a stable reference branch. If the branch is rewritten (e.g., via git push --force or frequent rebases), the leak calculation may reset or become inaccurate, leading to unexpected gate results. To mitigate this, enforce a protected reference branch that only accepts fast‑forward merges or use a merge‑commit strategy that preserves history.

For teams that eventually want to reduce overall debt, consider starting with a Leak Period gate for immediate feedback and periodically switching to an Overall gate (or adding a second gate) during dedicated debt‑reduction sprints.