SonarQube Running Your First Scan

A scan is the process of pointing SonarQube at your code and getting a report back. This topic walks you through installing the scanner, configuring it for a project, and running your first analysis successfully.

Scanners Available

YOUR BUILD TOOL              SCANNER TO USE
-----------------            -------------------------
Maven project                sonar-maven-plugin
Gradle project               sonar-gradle-plugin
.NET project                 SonarScanner for .NET
Everything else              SonarScanner CLI (generic)

This topic uses the SonarScanner CLI because it works with any language and build system.

Downloading SonarScanner CLI

Download the SonarScanner CLI from the official SonarQube documentation at docs.sonarsource.com. Extract the archive to a permanent location and add the bin directory to your system PATH so you can run the sonar-scanner command from anywhere.

VERIFY INSTALLATION
$ sonar-scanner --version
SonarScanner 5.x.x
Java 17.x.x (...)

What the Scanner Does

YOUR PROJECT FILES
       |
       v
[SonarScanner CLI]
  1. Reads sonar-project.properties
  2. Collects source files
  3. Collects test results and coverage (if available)
  4. Sends all data to SonarQube Server
       |
       v
[SonarQube Server]
  5. Analyzes the data against rules
  6. Stores results in database
  7. Updates project dashboard

Creating sonar-project.properties

Place this file in the root folder of your project. It tells the scanner the project key, where the source code is, and how to reach the SonarQube server.

# sonar-project.properties

# Required: identifies the project in SonarQube
sonar.projectKey=com.acme:customer-portal

# Optional: shown in the SonarQube dashboard
sonar.projectName=Customer Portal
sonar.projectVersion=1.0

# Location of source files (relative to this file)
sonar.sources=src

# Location of test files
sonar.tests=tests

# Server connection
sonar.host.url=http://localhost:9000
sonar.token=sqp_abc123your_token_here

Generating a Token

The scanner needs credentials to send data to the server. Use a token instead of your username and password. Generate one in SonarQube:

1. Click your name in the top right corner
2. Go to My Account > Security
3. Enter a name like my-scanner-token
4. Click Generate
5. Copy the token immediately — SonarQube shows it only once

Running the Scan

Open a terminal, navigate to your project root (where sonar-project.properties lives), and run:

sonar-scanner

The scanner outputs progress messages as it works:

INFO: Scanner configuration file: .../sonar-scanner.properties
INFO: Project root configuration file: .../sonar-project.properties
INFO: SonarScanner 5.x
INFO: Indexing files...
INFO: 48 files indexed
INFO: Analyzed files: 48
INFO: EXECUTION SUCCESS
INFO: Total time: 23.456s
INFO: Final Memory: 28M/225M

When you see EXECUTION SUCCESS, the scan is complete and results are on the server.

Viewing Results After the Scan

Open your browser, go to http://localhost:9000, and find your project in the Projects list. The dashboard now shows all discovered issues.

RESULT AFTER FIRST SCAN
+----------------------------------------------+
| Customer Portal                              |
| Analyzed: just now                           |
|                                              |
| Quality Gate: FAILED                         |
|                                              |
| Bugs: 2  Vulnerabilities: 1  Smells: 18      |
| Coverage: 42%   Duplications: 6.2%           |
+----------------------------------------------+

Do not panic if the Quality Gate fails on the first scan. Most projects have existing issues. The goal is to understand them and fix them over time.

Running a Maven Project Scan

If your project uses Maven, add the SonarQube plugin and run:

mvn clean verify sonar:sonar \
  -Dsonar.projectKey=com.acme:customer-portal \
  -Dsonar.host.url=http://localhost:9000 \
  -Dsonar.token=sqp_abc123your_token_here

Maven compiles, tests, and then scans all in one command. The test results and coverage data flow directly into the scan.

Running a Gradle Project Scan

Add the SonarQube Gradle plugin to your build.gradle:

plugins {
    id "org.sonarqube" version "4.4.1.3373"
}

sonar {
    properties {
        property "sonar.projectKey", "com.acme:customer-portal"
        property "sonar.host.url", "http://localhost:9000"
        property "sonar.token", "sqp_abc123your_token_here"
    }
}

Then run:

./gradlew sonar

Including Code Coverage in the Scan

SonarQube displays coverage numbers, but it does not generate coverage data itself. Your test framework generates a coverage report file, and you tell the scanner where that file is.

# For Java with JaCoCo:
sonar.coverage.jacoco.xmlReportPaths=target/site/jacoco/jacoco.xml

# For JavaScript with Istanbul/NYC:
sonar.javascript.lcov.reportPaths=coverage/lcov.info

# For Python with Coverage.py:
sonar.python.coverage.reportPaths=coverage.xml

Run your tests first to generate the coverage file, then run the scanner.

Common Scan Errors and Fixes

ERROR                              FIX
-----                              ---
"Could not connect to server"      Check sonar.host.url and that server is running
"Not authorized"                   Regenerate your token; check sonar.token value
"Project not found"                Check sonar.projectKey matches what is on server
"No files to analyze"              Check sonar.sources path is correct
"Java version mismatch"            Ensure Java 17+ is in PATH

Scan Output Files

The scanner creates a .scannerwork folder in your project directory. This folder contains temporary cache files that speed up future scans. Do not commit this folder to version control. Add it to your .gitignore:

# .gitignore
.scannerwork/