sonarqube Documentation

Technical Documentation: SonarSource/sonarqube

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

SonarQube

SonarQube is the algorithmic verification platform for code quality and security. Its static analysis applies techniques such as symbolic execution and data and control flow analysis to inspect your code, find bugs, vulnerabilities, and structural problems, and tell you exactly what to fix and why, in your IDE, your pull requests, and your CI pipeline.

This repository holds the source of the SonarQube Community Build, the free, open-source edition of the SonarQube platform. It shares the same analysis used across the SonarQube product line.

Built for the AI era Copy Chapter

AI writes code faster than teams can review it, creating verification debt: code reaching production before anyone has confirmed what it does. SonarQube applies the same consistent, explainable analysis to every line, whether a developer or an agent wrote it. Vibe, then verify: generate fast, then verify what reaches production. It is the verification stage of the Agent Centric Development Cycle, running in the outer CI verification loop to verify code before it merges.

What SonarQube finds Copy Chapter

• Bugs and reliability issues that break behavior at runtime.
• Security vulnerabilities and security hotspots, with clear guidance on the risk and the fix.
• Maintainability and structural issues that make code harder to change over time.
• Coverage on new code, so quality improves with every commit instead of stalling behind a backlog.

The SonarQube platform analyzes more than 40 programming languages and frameworks; the Community Build supports a subset of them. Analysis is repeatable, auditable, and explainable: the same code always produces the same findings, every finding is traceable, and each one tells you what the problem is and why it matters.

Commercial editions Copy Chapter

SonarQube Server and SonarQube Cloud include everything in the Community Build and add:

Detect more

• More bugs, vulnerabilities, code quality issues, and architecture issues, through broader coverage and deeper analysis.
• More languages and frameworks than the Community Build.
• Software composition analysis (SCA) for vulnerable and risky open-source dependencies.
• Advanced security with deep taint analysis (SAST) that traces vulnerabilities across data flows.
• Secrets detection for leaked credentials, tokens, and keys.
• Infrastructure as code (IaC) analysis for Terraform, Kubernetes, Docker, and CloudFormation.
• Architecture management to define architectural constraints and catch structural violations.

Analyze your whole workflow

• Branch analysis and pull request decoration, so every change is verified before it merges.

Govern, report, and see across teams

• Portfolios and applications that roll up quality and security across many projects.
• Executive dashboards and trend reporting.
• Security and compliance reports, including OWASP Top 10, CWE, and PCI DSS.
• Enterprise governance: enforce Quality Gates and permissions across teams, with full audit trails.

Fix

• SonarQube Remediation Agent to reduce technical debt by fixing SonarQube issues for you, opening verified fix pull requests you can review and merge.

Some capabilities are part of the SonarQube Advanced Security add-on. See the product line for details.

Quality gates Copy Chapter

A Quality Gate is a pass-or-fail check on your new code. Set the standard once, and SonarQube enforces it automatically in every pull request and pipeline, so issues are caught before they merge rather than found in production.

The SonarQube product line Copy Chapter

The Community Build is free and open source. The wider SonarQube line applies the same analysis across your workflow:

• SonarQube Server, self-managed, with more languages, deeper security analysis, and branch and pull request analysis.
• SonarQube Cloud, hosted, with the same capabilities as a managed service.
• SonarQube for IDE, real-time analysis as you write or generate code.
• SonarQube MCP Server, bringing SonarQube analysis into your AI agent's context.
• SonarQube CLI, running analysis from the command line.

Compare SonarQube plans and pricing to choose the appropriate product and deployment model.

Product links Copy Chapter

• Website
• Download
• Documentation
• X
• SonarSource, author of SonarQube

FAQ Copy Chapter

Is the Community Build free? Yes. It is free and open source, and this repository is its source.

What is the difference between the Community Build and SonarQube Server? The Community Build is the free, self-managed engine. SonarQube Server and SonarQube Cloud are the commercial editions. They cover more languages and add branch and pull request analysis, software composition analysis (SCA), architecture management, advanced security with taint analysis (SAST), secrets detection, infrastructure as code (IaC) analysis, the SonarQube Remediation Agent for verified fix pull requests, and enterprise reporting. Some capabilities are part of the SonarQube Advanced Security add-on. See the product line for details.

Does it work on AI-generated code? Yes. SonarQube applies the same analysis to all code, whether a developer or an agent wrote it.

Project links Copy Chapter

• Webapp source code
• Issue tracking, read-only. Only SonarSourcers can create tickets.
• Responsible Disclosure

Have Questions or Feedback? Copy Chapter

For support questions ("How do I?", "I got this error, why?", ...), please first read the documentation and then head to the SonarSource Community. The answer to your question has likely already been answered! 🤓

Be aware that this forum is a community, so the standard pleasantries ("Hi", "Thanks", ...) are expected. And if you don't get an answer to your thread, you should sit on your hands for at least three days before bumping it. Operators are not standing by. 😄

Contributing Copy Chapter

If you would like to see a new feature or report a bug, please create a new thread in our forum.

Please be aware that we are not actively looking for feature contributions. The truth is that it's extremely difficult for someone outside SonarSource to comply with our roadmap and expectations. Therefore, we typically only accept minor cosmetic changes and typo fixes.

With that in mind, if you would like to submit a code contribution, please create a pull request for this repository. Please explain your motives to contribute this change: what problem you are trying to fix, what improvement you are trying to make.

Make sure that you follow our code style and all tests are passing (a GitHub Actions build is executed for each pull request).

Willing to contribute to SonarSource products? We are looking for smart, passionate, and skilled people to help us build world-class code-quality solutions. Have a look at our current job offers here!

Building Copy Chapter

To build sources locally follow these instructions.

Requirements Copy Section

• Java 21 - Required to build the project
• Native Git - Must be installed and available in your PATH
• Tests - Can be disabled if needed by adding -x test to the gradle command (useful if you just want to build without running tests)

Build and Run Unit Tests Copy Section

Execute from the project base directory:

./gradlew build

The zip distribution file is generated in sonar-application/build/distributions/. Unzip it and start the server by executing:

# on Linux
bin/linux-x86-64/sonar.sh start
# or on MacOS
bin/macosx-universal-64/sonar.sh start
# or on Windows
bin\windows-x86-64\StartSonar.bat

Open in IDE Copy Section

If the project has never been built, then build it as usual (see previous section) or use the quicker command:

./gradlew ide

Then open the root file build.gradle as a project in IntelliJ or Eclipse.

Gradle Hints Copy Section

Building with UI changes Copy Chapter

The SonarQube UI (or webapp as we call it), is located in another repository: sonarqube-webapp.

When building the sonarqube repository, the webapp is automatically downloaded from Maven Central as a dependency, it makes it easy for you to contribute backend changes without having to care about the webapp.

But if your contribution also contains UI changes, you must clone the sonarqube-webapp repository, do your changes there, build it locally and then build the sonarqube repository using the WEBAPP_BUILD_PATH environment variable to target your custom build of the UI.

Here is an example of how to do it:

cd /path/to/sonarqube-webapp/server/sonar-web
# do your changes

# install dependencies, only needed the first time
yarn

# build the webapp
yarn build


cd /path/to/sonarqube

# build the sonarqube repository using the custom build of the webapp
WEBAPP_BUILD_PATH=/path/to/sonarqube-webapp/server/sonar-web/build/webapp ./gradlew build

You can also target a specific version of the webapp by updating the webappVersion property in the ./gradle.properties file and then building the sonarqube repository normally.

Translations files Copy Chapter

Historically our translations were stored in sonar-core/src/main/resources/org/sonar/l10n/core.properties, but this file is now deprecated and not updated anymore.
Default translations (in English) are now defined in the webapp repository, here:
https://github.com/SonarSource/sonarqube-webapp/blob/master/libs/sq-server-shared/src/l10n/default.ts

The format has changed but you can still have it as a .properties file format by running the following command:

cd /path/to/sonarqube-webapp/server/sonar-web

# install dependencies, only needed the first time
yarn

# generate a backward compatible .properties file with all the translation keys
yarn generate-translation-keys

Note that contributing extensions for translations into other languages still work the same way as before. It's just the source of truth for the default translations that changed.

License Copy Chapter

Copyright (C) SonarSource Sàrl.

Licensed under the GNU Lesser General Public License, Version 3.0

Overview (`sonar-ws-generator/README.md`) Copy Section

What is this project used for?

The sonar-ws-generator must be used to generate the java sources used to access the Web API (HTTP) of SonarQube.
The generated sources are not compilable on their own, but require to be copied in the sonar-ws module.

How do I use it?

• Make your changes on the SonarQube Web API (protobuf specification of responses in sonar-ws or WebService implementations in sonar-server)
• Build SonarQube with ./gradlew build -x test -x obfuscate)
• Run generator: sonar-ws-generator/run.sh
• Check your git status: the generated sources are copied in sonar-ws/src/main/java. Please double check the changed code.
• Now you can rebuild sonar-ws and use it in integration tests

Hints

• A request parameter has type List<String> if its description contains "comma-separated" or "list of" (case insensitive). Examples:
  • "Comma-separated list of metric keys"
  • "List of metric keys"

Overview (`scripts/patches/README.md`) Copy Section

Patches

This directory contains patches to be used by any script which uses function call_patches from patches_utils.sh.

start.sh disables telemetry by default (pointing it at http://localhost) so dev instances don't
report to production. Use -p telemetry to re-enable it against your own endpoint (see telemetry.sh).

Patches are files with extension .sh. Name of the patch is the name of the file without extension (so name of patch "debug.sh" is "debug").

Patches run in the same directory as the calling script provided patches_utils.sh has been sourced in the calling script.

Patches are passed on to start.sh script using command line argument -p by their name.
More than one can be specified using comma as separator.
Each patch is invoked with one argument:

• SQ_HOME: path to the home of the started SQ instance

To enable custom patches not part of this directory, set the environment variable SONARQUBE_USER_PATCHES_HOME to the directory of the scripts.
If a script with the same name exists in this directory and under your custom script directory,
the one in the custom script directory will be used.

Example scripts Copy Chapter

Debug Copy Section

#!/usr/bin/env bash
#
# sets property sonar.web.javaAdditionalOpts in sonar.properties to activate debug
#

set -euo pipefail

source scripts/property_utils.sh

SQ_HOME=$1

port=5005
echo "enabling debug in conf/sonar.properties, listening on port $port"
set_property sonar.web.javaAdditionalOpts "-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=$port" "$SQ_HOME/conf/sonar.properties"

Views Copy Section

#!/usr/bin/env bash
#
# copies the sonar-views plugin jar to the extension directory
#

set -euo pipefail

source scripts/property_utils.sh

SQ_HOME=$1

VIEWS_FILE=~/DEV/views/target/sonar-views-plugin-2.9-SNAPSHOT.jar
EXT_DIR=$SQ_HOME/extensions/plugins
cp -v "$VIEWS_FILE" "$EXT_DIR"

Overview (`sonar-sarif/src/main/resources/sarif/README.md`) Copy Section

Diff from the official schema

• Remove all default from the schema. This is mostly to fix Issue #105 but also to prevent all indexes and ids to have -1 as default value, while null is better in Java.

PULL REQUEST TEMPLATE (`docs/PULL_REQUEST_TEMPLATE.md`) Copy Section

Please be aware that we are not actively looking for feature contributions. The truth is that it's extremely difficult for someone outside SonarSource to comply with our roadmap and expectations. Therefore, we typically only accept minor cosmetic changes and typo fixes. If you would like to see a new feature, please create a new thread in the forum "Suggest new features".

With that in mind, if you would like to submit a code contribution, make sure that you adhere to the following guidelines and all tests are passing (a GitHub Actions build is executed for each pull request):

• Please explain your motives to contribute this change: what problem you are trying to fix, what improvement you are trying to make
• Use the following formatting style: SonarSource/sonar-developer-toolset
• Provide a unit test for any code you changed
• If there is a JIRA ticket available, please make your commits and pull request start with the ticket ID (SONAR-XXXX)

We will try to give you feedback on your contribution as quickly as possible.

Thank You!
The SonarSource Team

Contributing (`docs/contributing.md`) Copy Section

Contributing

If you would like to see a new feature, please create a new thread in the forum "Suggest new features".

Please be aware that we are not actively looking for feature contributions. The truth is that it's extremely difficult for someone outside SonarSource to comply with our roadmap and expectations. Therefore, we typically only accept minor cosmetic changes and typo fixes.

Submitting a pull request Copy Chapter

With that in mind, if you would like to submit a code contribution, please create a pull request for this repository. Please explain your motives to contribute this change: what problem you are trying to fix, what improvement you are trying to make.

Make sure that you follow our code style and all tests are passing (a GitHub Actions build is executed for each pull request).

Next steps Copy Chapter

One of the members of our team will carefully review your pull request. You might be asked at this point for clarifications or your pull request might be rejected if we decide that it doesn't fit our roadmap and vision for the product.
If your contribution looks promising then either we will decide:

• it is good to go, close your pull request and use our internal tools and processes to bring your changes into the product. Don't worry, we will persist the author information in git.

or

• that we need to think over your change and modify it to adhere to our roadmap and internal standards. We will close your pull request at this point, but we might come back to your changes later in the future when we decide it is the right time to work on it.

Thank You!
The SonarSource Team

Server Sonar Db Migration Src Docs Table Ownership (`server/sonar-db-migration/src/docs/table_ownership.md`) Copy Section

Purpose Copy Chapter

This document presents ownership of the tables in the Core database. This is intended
to facilitate the understanding which squad is responsible for which data.

Some tables have no ownership assigned yet, this is subject to change pending discussion between impacted squads.

It is expected to edit this file if the ownership of a table changes. There is no automated process to validate it, at the
same time we expect no frequent changes.

Important read: Data Ownership Principles

Table Ownership Copy Chapter

--- METRICS ---

• Files Extracted: 7
• Estimated Token Budget: ~5930 tokens
• Canonical Reference: https://codewiki.google/github.com/SonarSource/sonarqube