Many teams begin a SonarQube implementation by connecting the scanner to their CI/CD pipeline and running their first analysis. The result can be intimidating, with thousands of issues and low coverage on an application that has already been in production for years. If those findings are treated as one large remediation project, the team can quickly lose confidence in the process and stop using the dashboard altogether.
Why the Initial SonarQube Issue Count Should Not Be Your Main Target
Those legacy issues represent years of technical decisions made under real delivery constraints. Treating the entire backlog as an immediate remediation target is rarely practical. Rewriting stable production code without adequate test coverage can also introduce unnecessary regression risk. A sustainable SonarQube strategy should therefore distinguish legacy technical debt from problems introduced by new development.
An unrealistic target can create a more subtle problem, namely that teams begin to ignore the quality signal altogether. Once a red quality gate becomes routine rather than actionable, it loses its value—even when it identifies a genuine defect or security concern.
Use Quality Gates for New Code, Not Legacy Code
SonarQube calls this approach Clean as You Code. Instead of trying to fix the entire legacy codebase at once, the quality gate focuses on code that has been recently added or changed. You can define the new code period based on the previous release, a rolling period such as 30 days, or a specific analysis. Legacy issues remain visible for reporting and long-term improvement, but they do not have to block current development.
In practice, this means a four-year-old file with 40 existing issues does not automatically become a sprint objective. The focus is on the 60 new or modified lines introduced today. Technical debt is addressed incrementally in the areas the team is already changing, where developers have the necessary context and can add or improve tests alongside the changes.
A legacy codebase improves sustainably when new development is held to a consistent quality standard.
How to Configure the SonarQube Quality Gate
The built-in Sonar way quality gate is a useful starting point, but teams should review its conditions against their current engineering practices. An 80% coverage target on new code may be appropriate for a mature testing culture. For a codebase with only 11% overall coverage, however, introducing an aggressive threshold immediately can make every pull request fail and encourage teams to bypass the gate. A quality gate is effective only when the team treats it as an enforceable engineering standard.
| Condition | Where we start | Reasoning |
|---|---|---|
| New bugs and vulnerabilities | 0 | The one condition worth being strict about. New code should not ship known defects. |
| Security hotspots reviewed | 100% | A hotspot asks for a decision, not always a fix. Marking it safe with a sentence of context is a pass. |
| Coverage on new code | 50-60%, raised each quarter | A number the team can hit and will keep beats a best-practice number that gets bypassed. |
| Duplicated lines on new code | 3% | Catches the copy-paste-and-tweak that turns one bug into four. |
| Ratings on overall code | Reporting only | Blocking on these punishes whoever happens to touch the oldest file next. |
How SonarQube Handles Test Coverage
This one catches almost everyone. SonarQube does not execute your tests or calculate test coverage itself. Instead, it imports coverage reports generated by your existing build and test process. If the report path is not configured correctly, SonarQube may display 0.0% coverage even when automated tests are present.
- Java and Kotlin use the JaCoCo XML report, via sonar.coverage.jacoco.xmlReportPaths.
- JavaScript and TypeScript use lcov.info, via sonar.javascript.lcov.reportPaths.
- Go uses the output of go test -coverprofile, via sonar.go.coverage.reportPaths.
- PHP uses the Clover XML report, via sonar.php.coverage.reportPaths.
- Python uses coverage.xml, via sonar.python.coverage.reportPaths.
- For .NET, run the MSBuild scanner in its begin and end form, and hand it the OpenCover or dotnet-coverage output.
The coverage report must be available to the SonarQube scanner in the same job, or be copied into the scan environment before analysis. If the report remains on another runner or at an inaccessible path, SonarQube cannot import it. The resulting 0.0% coverage can therefore be a configuration problem rather than an absence of tests.
What SonarQube Can Detect—and What It Cannot
SonarQube is particularly useful for identifying repeatable code-quality, reliability, maintainability, and security patterns that can be difficult to catch consistently during manual review. Examples include resources that are not closed, exceptions that are silently ignored, incorrect equals/hashCode implementations, problematic regular expressions, exposed credentials, and SQL queries assembled through unsafe string concatenation.
Static analysis also has important limitations. SonarQube understands code patterns, but it does not understand every business rule or runtime condition in your application. As a result, some important defects require domain knowledge, integration testing, or runtime validation.
- A discount rule that applies the wrong percentage. Every line is clean and the outcome is still wrong.
- An endpoint missing an authorization check, when the code around it looks perfectly ordinary.
- A race condition that only appears under real concurrency.
- A migration that is correct SQL and locks a large table at the worst hour of the day.
Teams should also confirm which SonarQube edition provides the features they need. Cross-file taint analysis, branch analysis, and pull request decoration are among the capabilities associated with paid editions rather than the basic Community experience. If the objective is to block a pull request before merge, verify the current edition and feature requirements before designing the CI/CD workflow around that assumption.
A SonarQube Implementation Strategy That Lasts
- 1Run the first SonarQube analysis on the main branch and use it as a baseline rather than treating the total issue count as an immediate remediation target. Set the new code period to the previous release, or use an appropriate rolling period such as 30 days for continuous delivery.
- 2Configure the quality gate primarily around new or changed code. Keep overall code metrics visible for technical-debt tracking without making the legacy backlog an immediate release blocker.
- 3Confirm the SonarQube edition and required features early in the rollout. If pull-request analysis and blocking are required, verify the edition that supports the intended workflow. If the current setup analyzes the main branch after merge, define a clear process for addressing failed quality conditions promptly.
- 4Use the first few weeks to review and refine the quality profile. For rules that repeatedly create disagreement, make an explicit decision, either keeping the rule and defining how it should be applied or disabling it when it is not relevant to the project. A clear configuration is preferable to widespread NOSONAR suppressions that obscure why findings are being ignored.
- 5Exclude artifacts that should not be evaluated as application source code, such as generated clients, database migrations where appropriate, vendored dependencies, and build output. Keep these exclusions version-controlled in sonar-project.properties or the relevant project configuration so they are visible and reviewable alongside the code.
- 6Use SonarQube for IDE, formerly known as SonarLint, and connect it to the SonarQube server so developers can work with consistent quality rules. Catching an issue during development is generally faster and cheaper than discovering the same issue during code review or CI.
What a Successful SonarQube Implementation Looks Like
A successful implementation does not require the total issue count to drop immediately. More meaningful indicators are operational ones, such as quality-gate failures that have clear and actionable reasons, developers receiving automated feedback on common issues, code reviews can focus more on design and business logic, security hotspots receive explicit decisions, and legacy files do not accumulate additional issues as they are modified.
The practical outcome is not an instantly clean codebase. It is a development process that prevents new technical debt from accumulating at the same rate and creates a structured path for improving existing code over time.
Key takeaways
- Focus the SonarQube quality gate on new code. Legacy issues remain context for technical-debt planning, not an immediate release target.
- Set a realistic code-coverage threshold, measure it consistently, and increase the target as the team matures.
- SonarQube imports test coverage reports rather than calculating coverage itself. A 0.0% result often indicates a report-path or scanner configuration issue.
- Verify SonarQube edition requirements for pull-request analysis, security features, and quality-gate workflows before committing to a blocking CI/CD setup.
