Skip to content
Tutorials Center
My learning

Topics

Lesson 27 of 37 ยท CI Integration

SonarQube in a CI Pipeline: The Big Picture

Understand where SonarQube analysis fits in CI: checkout, build, test, scan, quality gate. Learn the scanner properties, secrets, and failure modes, with a pipeline simulator.

Running the scanner on your laptop is a good demo. Running it in CI on every push and pull request is what makes SonarQube useful. Every CI system does the same five things in the same order: get the code, build it, run tests with coverage, run the scanner, and check the quality gate. The syntax changes; the shape does not.

This lesson explains that shape and the settings every pipeline needs. The next lessons show concrete files for GitHub Actions, GitLab, Jenkins and Azure DevOps, and pull request analysis. Because SonarQube is not runnable on this site, the TryIts simulate parts of a pipeline in JavaScript.

The five CI steps

Checkout Full history
Build Compile
Test With coverage
Scan Send to server
1 / 2

The anatomy of an analysis

sequenceDiagram
  participant CI as CI job
  participant SC as Scanner
  participant SQ as SonarQube server
  CI->>CI: build and test with coverage
  CI->>SC: run scanner with token
  SC->>SQ: upload analysis report
  SQ->>SQ: compute issues, measures, gate
  SQ-->>CI: gate status (webhook or polling)

Figure: the scanner uploads a report; the server does the heavy computation and returns the verdict later.

Analysis is asynchronous. When the scanner prints "ANALYSIS SUCCESSFUL" it only means the report was uploaded. The server processes it in a background task, so the quality gate result arrives a little afterwards. Pipelines that need the verdict either poll for it (sonar.qualitygate.wait=true) or use a webhook.

Which scanner?

Build Scanner
Maven sonar-maven-plugin (mvn ...:sonar)
Gradle the org.sonarqube Gradle plugin (./gradlew sonar)
.NET SonarScanner for .NET (begin, build, end)
Anything else (JS/TS, Python, Go, PHP, ...) SonarScanner CLI, configured by sonar-project.properties

Each CI platform also offers wrapper steps, such as the official GitHub Action, an Azure DevOps extension, and a Jenkins plugin. They call the same scanners.

The settings every pipeline needs

Property Purpose
sonar.host.url URL of the server
sonar.token or the SONAR_TOKEN environment variable Authentication; use a project analysis token
sonar.projectKey Unique project key on the server
sonar.sources Folders with source code
sonar.tests Folders with tests
sonar.qualitygate.wait Block until the gate is computed
sonar.qualitygate.timeout Seconds to wait (default 300)

Never write the token into the repository. Put it in the CI system's secret store and expose it as an environment variable. Property names changed over time (sonar.login was replaced by sonar.token), so match them to your scanner version.

A minimal sonar-project.properties:

PROPERTIES
sonar.projectKey=shop-frontend
sonar.projectName=Shop Frontend
sonar.sources=src
sonar.exclusions=**/*.spec.ts,**/generated/**
sonar.javascript.lcov.reportPaths=coverage/lcov.info

and the call in CI: sonar-scanner -Dsonar.host.url=$SONAR_HOST_URL with SONAR_TOKEN set in the environment.

Shallow clones: the classic trap

Many CI systems fetch only the last commit to be fast. SonarQube needs the full git history to assign blame (who wrote each line) and to decide which lines are new for the new code period. With a shallow clone you will see warnings about missing blame information, wrong "new code" boundaries or an empty list of changed files. Configure checkout to fetch everything (fetch-depth: 0 in GitHub Actions, GIT_DEPTH: 0 in GitLab).

Stand-in: pipeline simulator

The block simulates the ordering rules: a stage runs only if the previous stage succeeded, the scan needs a token, and the gate stage decides the final result. Change the inputs and re-run to see each failure mode.

JS Stand-in: simulate analysis stages

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Polling for the gate

With sonar.qualitygate.wait=true the scanner, after uploading, asks the server for the status of the background task and then for the gate result. It retries until done or until sonar.qualitygate.timeout passes. If the gate is ERROR the scanner exits with a non-zero code and the CI job fails, which is exactly what you want to protect a branch.

JS Stand-in: poll until the gate is ready

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Good habits

  • Run analysis for the main branch and for every pull request, not for every feature branch push if your edition lacks branch analysis.
  • Keep tokens in secrets; rotate them when people leave.
  • Cache the scanner's working directory (.sonar cache) to speed up runs.
  • Fail the build on gate failure, but allow a manual override process for emergencies.
  • Do not scan before tests when you want coverage.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. When the scanner prints ANALYSIS SUCCESSFUL, what is guaranteed?

    Server-side processing is asynchronous, so the gate result arrives after the upload.
  2. 2. Why does SonarQube need full git history in CI?

    Shallow clones break blame and new code detection.
  3. 3. Which property makes the scanner wait for the gate result?

    sonar.qualitygate.wait polls until the gate is ready and fails the run if it is ERROR.
  4. 4. Where should the analysis token live?

    Tokens are credentials and belong in secrets, passed as environment variables.

Summary

  • Pipelines follow checkout, build, test with coverage, scan, gate.
  • Analysis is asynchronous; wait by polling or with a webhook.
  • Provide host URL, token (from secrets), project key and sources.
  • Fetch full git history; shallow clones break blame and new code.

Next: GitHub Actions analysis