SonarQube

SonarQube is a static code-quality and security analysis platform: a scanner walks your source tree, a server turns every rule violation it finds into a tracked issue — a bug, a vulnerability, a code smell, or a security hotspot flagged for human review — and a single pass/fail verdict called a quality gate decides whether that analysis is good enough to let the build through. Testing in the pipeline already made the case for shift-left as a principle: catch a defect at the cheapest, earliest layer that can honestly catch it. SonarQube is that principle turned into an actual pipeline stage with the authority to fail a build, aimed at exactly the class of defect a green test suite doesn't see — a raw string concatenated into a SQL query with no failing test anywhere near it, a forty-branch function nobody ever proposed a test for, a block of logic copy-pasted into six files, or a coverage number that slid from 82% to 61% over forty unremarkable-looking commits. This page assumes the shift-left case is already made and goes straight to the mechanics: how the server and scanner actually talk to each other, the config you write to wire a real project in, and the specific way an unconfigured pipeline lets a failed gate through green.

What SonarQube is, and the problem it solves

☺ Like you're 10: It never runs your tests — it reads your finished code and your test's coverage report, and turns "this code looks a little off" into an actual number a robot can act on.

Every issue SonarQube finds falls into one of four buckets. A Bug is code that is provably wrong — a null dereference the analyzer can trace, a resource that's opened and never closed. A Vulnerability is code that's provably exploitable — string-built SQL, a hard-coded credential, a weak cipher. A Code Smell is not necessarily wrong today but expensive tomorrow — a function with cyclomatic complexity of 40, a duplicated block, an empty catch block, a class that violates its own naming convention. A Security Hotspot is the honest middle case: code the analyzer can't classify as safe or unsafe on its own — a regex that could be a ReDoS vector, a cookie that might need the secure flag — so it's routed to a human reviewer to mark Safe or To Fix, with a reason, rather than silently scored either way.

The one thing SonarQube deliberately does not do is run your tests. It reads a coverage report your own test runner already produced — JaCoCo's XML, an lcov.info, a Python coverage.xml — and reports the percentage back as a metric it can gate on. That's a boundary worth holding onto: SonarQube instruments code quality the same way the DORA metrics instrument delivery — it turns a subjective impression ("this file looks messy") into a number a team can track over time and a gate can act on, but it's measuring code that was already built and already tested by something else.

Where it fits in the pipeline

☺ Like you're 10: It goes right after your tests run — because it needs their coverage numbers — and right before anything gets allowed to move on toward production.

CI/CD pipelines names a generic stage list — lint, unit test, build, integration test, security scan, package, deploy — without saying which tool owns which box. SonarQube's analysis stage sits after the test stages, because it depends on a coverage report those stages produce, and it belongs somewhere in the neighborhood of the "security scan" stage shift-left security for DevOps already covers in the SAST row — SonarQube ships a baseline SAST engine of its own, so many teams run it alongside a dedicated tool like Semgrep or CodeQL rather than instead of one; Sonar's vulnerability rules are broad but shallower on newer frameworks, and its Security Hotspot review workflow is the piece those other tools don't really have.

The part that makes it a genuine shift-left mechanism rather than a late report is where the feedback actually surfaces. PR decoration posts the same issues as inline comments on the pull request, before merge, and SonarLint — the free IDE plugin for VS Code, IntelliJ, Eclipse, and Visual Studio — runs the identical rule set live in the editor in "Connected Mode" against the team's real Quality Profile, so a developer sees the same finding CI would raise while they're still typing the line, not twenty minutes later in a PR comment. That's the innermost loop the inner loop & developer experience is about — the cheapest possible place to catch anything.

Architecture: the scanner, the Compute Engine, and where analysis actually happens

☺ Like you're 10: A small program reads your code on your own machine and mails a report home; a bigger program back at headquarters opens the mail, files everything away, and decides pass or fail — and that second part takes a moment.

Sonar (the company, formerly SonarSource) ships two products that share the same engine. SonarQube Server — the self-hosted product, still commonly just called "SonarQube" — is a Java application made of three cooperating processes: a Web Server serving the UI and REST API, a Compute Engine that processes analysis reports as a background job queue, and a bundled Elasticsearch index behind the search and issue-list UI, all backed by a PostgreSQL database as the actual system of record — Postgres is the only production database SonarQube supports on current releases, so double-check that against the install docs if you're planning against an older deployment. SonarQube Cloud (the SaaS product, formerly branded SonarCloud) is the same engine hosted for you. Both are licensed across a tier ladder — a free, open-source Community tier (LGPL v3) plus paid Developer, Enterprise, and Data Center tiers that add branch/PR analysis at scale, more languages (C, C++, Objective-C, COBOL, and a few others have historically sat behind the paid tiers), and portfolio-level reporting — Sonar has renamed and reshuffled these tiers more than once, so treat any specific tier boundary here as a starting point to verify on their current pricing page, not gospel.

The workflow that actually matters for a pipeline is the split between what happens on your CI runner and what happens on the server, because it's asynchronous in a way that causes the single most common SonarQube outage in a CI pipeline — covered fully in the gotchas below.

Quality Profiles, issue ratings, and the quality gate

☺ Like you're 10: A Quality Profile is the list of rules turned on for a language; a quality gate is the short list of numbers that actually have to pass, and by default it only checks the lines you touched today.

A Quality Profile is the active rule set for one language — the built-in default is called "Sonar way," and teams fork it to activate, deactivate, or re-tune the severity of individual rules, then assign the tuned profile to a project. Every issue an active rule produces also drives three letter-grade ratings per project — Reliability, Security, and Maintainability, each A through E — where Maintainability's grade is driven by a technical-debt ratio: estimated remediation time for every open code smell, divided against the estimated cost of writing the file from scratch. Newer SonarQube releases layer a "Clean Code" taxonomy on top of that — every issue also carries which Software Qualities it impacts and a severity of Blocker, High, Medium, Low, or Info — worth confirming against your installed version's docs, since Sonar has iterated on this naming since it shipped.

New Code vs. Overall Code: the Clean as You Code idea

The single most important concept on this page is the New Code Definition. Every project has one — the previous version, a fixed number of days, a specific reference branch, or (for a pull request) an automatic diff against the target branch — and it draws a line between code that existed before that point and code that changed after it. The default "Sonar way" quality gate evaluates its conditions only against New Code:

• Coverage on New Code < 80% → fail
• Duplicated Lines (%) on New Code > 3% → fail
• Maintainability Rating on New Code worse than A → fail
• Reliability Rating on New Code worse than A → fail
• Security Rating on New Code worse than A → fail
• Security Hotspots Reviewed on New Code < 100% → fail

(Confirm the exact defaults for your version under Administration → Quality Gates — Sonar has adjusted them across releases.) This is deliberate — it's the Clean as You Code methodology, and it's also the single most misread thing about the tool. A codebase can carry ten thousand old issues and a five-year-old file at 12% coverage and still show a permanently passing gate, because nothing in that old code is New Code — the gate isn't claiming the codebase is clean, only that today's diff didn't make it worse. Teams that read a green gate as "no bugs" instead of "no new bugs since the baseline" are the same teams surprised, months later, by how much technical debt "passing" quietly let accumulate underneath it.

The scanner config you actually write

☺ Like you're 10: One small file tells the scanner your project's name, where the code lives, and where to find the coverage report your tests already wrote.

There's no single scanner binary for every ecosystem — there's a family of them, and which one you invoke depends on the build tool already driving your project. All of them read the same handful of core properties.

sonar-project.properties — the generic CLI scanner

sonar.projectKey=acme_checkout
sonar.projectName=Checkout Service
sonar.organization=acme                        # SonarQube Cloud only — omit for self-hosted Server
sonar.host.url=https://sonar.acme.internal      # omit entirely on SonarQube Cloud

sonar.sources=src
sonar.tests=test
sonar.exclusions=**/generated/**,**/vendor/**
sonar.coverage.exclusions=**/*_test.go,**/migrations/**,**/*.spec.ts
sonar.cpd.exclusions=**/fixtures/**              # duplication detector: skip fixture data on purpose

# coverage is REPORTED, never measured — point at whatever your test runner already produced
sonar.python.coverage.reportPaths=coverage.xml
sonar.javascript.lcov.reportPaths=coverage/lcov.info

sonar.qualitygate.wait=true                      # block the scanner call until the gate result is known
sonar.qualitygate.timeout=300

Maven and Gradle

A Maven project runs the scanner as a goal against a build that already ran tests and produced coverage — the sonar-maven-plugin reads most of its config straight from the POM, so a separate properties file is rarely needed:

$ mvn clean verify sonar:sonar \
    -Dsonar.host.url=https://sonar.acme.internal \
    -Dsonar.token=$SONAR_TOKEN \
    -Dsonar.coverage.jacoco.xmlReportPaths=target/site/jacoco/jacoco.xml

Gradle applies the official plugin and runs a task — renamed from sonarqube to the shorter sonar in recent plugin versions, so check your plugin version if a tutorial's task name doesn't work:

// build.gradle
plugins {
  id "org.sonarqube" version "5.1.0.4882"
}
sonar {
  properties {
    property "sonar.projectKey", "acme_checkout"
    property "sonar.coverage.jacoco.xmlReportPaths", "build/reports/jacoco/test/jacocoTestReport.xml"
  }
}

$ ./gradlew test jacocoTestReport sonar -Dsonar.token=$SONAR_TOKEN

.NET is the odd one out: because MSBuild doesn't expose the hooks the other scanners rely on, dotnet-sonarscanner has to bracket the actual build rather than wrap it, which is the source of a real gotcha covered below.

$ dotnet sonarscanner begin /k:"acme_checkout" /d:sonar.token=$SONAR_TOKEN
$ dotnet build
$ dotnet test --collect:"XPlat Code Coverage"
$ dotnet sonarscanner end /d:sonar.token=$SONAR_TOKEN

Wiring the quality gate into CI as a real build gate

☺ Like you're 10: Running the scanner isn't the same as waiting to hear whether you passed — you have to ask a second time, or the pipeline moves on without ever finding out.

A CI step that runs sonar-scanner, gets exit code 0, and moves straight to deploy has proven almost nothing. The scanner's job ends at "report uploaded successfully" — gate evaluation happens on the server's Compute Engine afterward, asynchronously, and can take anywhere from a couple of seconds to a couple of minutes depending on queue depth and project size. sonar.qualitygate.wait=true (shown above) makes the scanner itself poll the server and block until the Compute Engine finishes and the gate status is known, then exit non-zero on failure — that single property is the difference between "code quality is enforced" and "code quality is a dashboard nobody's pipeline actually reads."

# .github/workflows/quality.yml — trimmed to the SonarQube-relevant steps
jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0            # full history — required for blame, New Code, and PR diffs

      - name: Run tests with coverage
        run: mvn -B test

      - name: SonarQube Scan
        uses: SonarSource/sonarqube-scan-action@v4
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
          SONAR_HOST_URL: ${{ vars.SONAR_HOST_URL }}

      - name: Quality Gate check          # separate step: poll the gate, fail the job if it's red
        uses: SonarSource/sonarqube-quality-gate-action@v1
        timeout-minutes: 5
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}

Both patterns above — a scanner set to wait, or a scanner followed by a dedicated gate-check action — do the same job: turn an asynchronous server-side verdict into a synchronous pipeline decision. Either way, PR decoration rides along for free once the pipeline runs on a pull-request event with the right token scopes: the same gate result also becomes inline comments and a status check on the GitHub, GitLab, or Bitbucket PR, which is what actually gets a developer's attention before merge rather than after.

Day-to-day commands

☺ Like you're 10: A handful of commands cover almost everything — stand up a server to try it, run the scanner, and ask the API a question when the dashboard is slower than a curl call.

# local quickstart — Community Build, NOT a production install (H2 embedded DB, single node)
$ docker run -d --name sonarqube -p 9000:9000 sonarqube:community
$ open http://localhost:9000                 # default first login: admin / admin, forced reset

# the generic scanner — reads sonar-project.properties in the current directory
$ sonar-scanner -Dsonar.token=$SONAR_TOKEN

# ask the API instead of clicking through the UI — genuinely faster once you know the endpoints
$ curl -u $SONAR_TOKEN: "$SONAR_HOST_URL/api/qualitygates/project_status?projectKey=acme_checkout" \
    | jq '.projectStatus.status'                     # "OK" or "ERROR"
$ curl -u $SONAR_TOKEN: "$SONAR_HOST_URL/api/issues/search?componentKeys=acme_checkout&types=VULNERABILITY" \
    | jq '.issues[] | {rule, message, severity}'
$ curl -u $SONAR_TOKEN: "$SONAR_HOST_URL/api/measures/component?component=acme_checkout&metricKeys=coverage,new_coverage,duplicated_lines_density"

The API is also how a webhook-based pipeline avoids polling: a project or global webhook (Administration → Webhooks) fires a POST containing the analysis result the moment the Compute Engine finishes, which a CI system can react to directly instead of running sonar.qualitygate.wait's poll loop itself — worth reaching for once you're running enough projects through one server that polling starts showing up as load.

Gotchas and failure modes

☺ Like you're 10: Most surprises come from the same root cause — something the scanner needed wasn't actually there, and it stayed quiet about it instead of failing loudly.

The scanner exiting 0 doesn't mean the gate passed

This is the gotcha above stated as a failure mode rather than a mechanism: without sonar.qualitygate.wait=true or a separate gate-check step, a pipeline can merrily deploy a build whose quality gate failed twenty seconds after the scanner returned, because nothing in the pipeline ever asked. Teams that discover this the hard way usually find out from the dashboard days later, not from CI — by which point several more red builds already shipped behind it.

Coverage is reported, never measured — and the property name is language-specific

SonarQube has no idea what "80% covered" means until you hand it a report file, and the property that does the handing is different per language — sonar.coverage.jacoco.xmlReportPaths for Java, sonar.javascript.lcov.reportPaths for JS/TS, sonar.python.coverage.reportPaths for Python, and so on. Get the property name or the path wrong and coverage silently reports as 0% — not an error, just a number that looks like a real regression until someone remembers to check the property name against the docs for that specific language.

Shallow clones break blame, New Code, and PR decoration

actions/checkout and most CI checkout steps default to a shallow clone (depth 1) for speed. SonarQube needs real git history to compute the New Code diff, run SCM blame (which is also how it auto-assigns an issue to whoever last touched that line), and decorate a PR correctly — a shallow clone makes all three either wrong or silently unavailable. fetch-depth: 0 in the checkout step, shown in the workflow above, is not optional.

NOSONAR is a blunt instrument, and it's meant to be resisted

An inline // NOSONAR comment suppresses every rule on that line, permanently, with no record of who decided it was safe or why — which is exactly the audit trail a security review will ask for and not find. The sanctioned path is marking the specific issue "Won't Fix" or "False Positive" in the UI or via the API with a required comment; that resolution is tracked per issue, survives re-analysis by matching the issue's fingerprint rather than its line number, and shows up in a report instead of vanishing into a code comment nobody reviews again.

Self-hosted has its own operational bill

Running SonarQube Server yourself means running Elasticsearch, which on Linux needs vm.max_map_count raised well above the kernel default or the server refuses to start at all — the same bootstrap check the ELK Stack hits for the identical reason. The Web Server, Compute Engine, and Elasticsearch each take their own JVM heap settings (SONAR_WEB_JAVAOPTS, SONAR_CE_JAVAOPTS, SONAR_SEARCH_JAVAOPTS), and a Compute Engine sized for one team's traffic falls behind fast once many teams share the same server — the queue is real and single-threaded per project, so a burst of merges across a large org can leave gate results arriving minutes late.

SonarQube vs. its alternatives

☺ Like you're 10: Other tools also grade your code — they just specialize in a narrower slice of the same job, faster or deeper depending on which slice.

In practice these aren't mutually exclusive — a mature pipeline commonly runs a fast linter pre-commit, SonarQube as the broad quality-and-baseline-security gate on every PR, and a deeper SAST tool like Semgrep or CodeQL for the specific vulnerability classes that matter most to that codebase, the same layered-tooling pattern compliance as code & policy enforcement takes for granted when it talks about gates stacking rather than replacing each other.