SonarQube New Code Definitions: A Practical Guide for CI/CD Quality Gates

The Legacy Trap and the New Code Solution

When integrating SonarQube into an existing project, teams often hit the 'legacy trap.' Applying strict Quality Gates to an entire aging codebase causes immediate failures due to accumulated technical debt that cannot be resolved in a single sprint.

The solution is defining 'New Code.' This setting specifies which parts of the code should be evaluated against Quality Gate criteria, allowing enforcement on recent changes while ignoring legacy issues in older modules.

Four Supported New Code Strategies

SonarQube provides four primary strategies to define what constitutes 'new' code. The right choice depends on your branching strategy and release cadence.

Strategy	Best Use Case	Behavior
Previous version	Semantic versioned releases (tags).	Automatically updates when a new version is detected.
Number of days	Continuous delivery with a rolling window (e.g., last 30 days).	Focus on recent activity regardless of versions.
Specific date	One-time refactors or major migrations.	Static; requires manual updates as time passes.
Number of manually specified versions	Complex branching models.	Uses specific tags/branches to define the baseline.

Trade-offs and Constraints

Using 'Previous version' works best for teams using Git tags, but requires consistent tagging in CI pipelines. Forgetting to tag a release causes SonarQube to fall back to an older baseline, analyzing too much code.

'Number of days' suits fast-moving teams but is risky: developers taking extended breaks may have their code fall out of the 'New Code' window before merge, exempting it from Quality Gate checks entirely.

'Specific date' can lead to inconsistent results if analysis isn't performed frequently around that date. 'Number of manually specified versions' offers flexibility for complex branching but requires careful tag management.

CI/CD Integration: Webhook Configuration

Quality Gates do not block builds automatically unless the SonarQube webhook is correctly configured and the CI pipeline waits for analysis results. Configure the webhook in Project Settings > Webhooks to point to your CI server.

GitHub Actions Example

Using sonarqube/sonar-scanner-action with the wait-for-gate-result parameter ensures the pipeline pauses until SonarQube processes the report and returns status.

# name: SonarQube Scan
  uses: sonarqube/sonar-scanner-action@master
  env:
    SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
    SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}
  with:
    args: >
      -Dsonar.projectKey=my_project
      -Dsonar.projectName=My Project

# name: Wait for Quality Gate
  uses: sonarqube/sonar-quality-gate-action@master
  env:
    SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}

Note: Ensure a Webhook is configured in SonarQube under Project Settings > Webhooks pointing to GitHub.

Validation Checklist

1. Verify the 'New Code' setting in Project Settings aligns with your team's branching strategy
2. Execute a scan with low-coverage code and confirm Quality Gate status transitions to 'Failed'
3. Check Webhook delivery logs in SonarQube to ensure status payload reaches the CI server

Key Takeaway

Choose 'Previous version' for tag-based releases, 'Number of days' for continuous delivery, and always verify webhook configuration. This approach focuses quality enforcement on recent changes while avoiding the legacy trap that derails many SonarQube adoptions.