SonarQube: Setup, Configuration, and Best Practices

Introduction to SonarQube

SonarQube is an open-source platform developed by SonarSource for continuous inspection of code quality. It performs automatic static code analysis to detect bugs, code smells, security vulnerabilities, and code duplications across more than 30 programming languages including Java, JavaScript, TypeScript, Python, C#, Go, and more. By integrating SonarQube into your development workflow, you can enforce quality gates, track technical debt, and maintain a healthy codebase over time.

Why Code Quality Matters

Poor code quality leads to increased maintenance costs, slower feature delivery, higher defect rates, and reduced developer productivity. SonarQube addresses these challenges by providing actionable metrics and visibility into the health of your code. It shifts quality checks left in the development lifecycle, catching issues before they reach production. Teams that adopt SonarQube typically report fewer production incidents, faster onboarding for new developers, and more predictable release cycles.

Key Concepts and Terminology

Before diving into setup, it is important to understand the core concepts that SonarQube uses to evaluate your code.

Quality Profile: A set of rules that define what constitutes a bug, vulnerability, or code smell in your project. Each language has a default profile you can customize.
Quality Gate: A set of conditions that your code must meet to be considered "ready for release." For example, coverage must be above 80% and no new critical issues are allowed.
Issues: Individual problems detected by the analyzer, categorized as Bug, Vulnerability, Code Smell, or Security Hotspot.
Technical Debt: An estimate of the time required to fix all code smells and maintainability issues.
Security Hotspots: Security-sensitive pieces of code that require manual review to determine whether they represent actual vulnerabilities.
Measures: Quantitative metrics such as lines of code, complexity, duplication percentage, and test coverage.

Installing SonarQube

The fastest way to get SonarQube running locally is using Docker. SonarQube requires a database for persistent storage, but for development purposes, the bundled H2 database works fine. For production, you should use PostgreSQL, MySQL, or Oracle.

Quick Start with Docker Compose

Create a docker-compose.yml file with the following content to run SonarQube alongside a PostgreSQL database:

version: "3.8"

services:
  sonarqube:
    image: sonarqube:community
    depends_on:
      - db
    environment:
      SONAR_JDBC_URL: jdbc:postgresql://db:5432/sonar
      SONAR_JDBC_USERNAME: sonar
      SONAR_JDBC_PASSWORD: sonar
    volumes:
      - sonarqube_data:/opt/sonarqube/data
      - sonarqube_extensions:/opt/sonarqube/extensions
      - sonarqube_logs:/opt/sonarqube/logs
    ports:
      - "9000:9000"

  db:
    image: postgres:15
    environment:
      POSTGRES_USER: sonar
      POSTGRES_PASSWORD: sonar
      POSTGRES_DB: sonar
    volumes:
      - postgresql:/var/lib/postgresql
      - postgresql_data:/var/lib/postgresql/data

volumes:
  sonarqube_data:
  sonarqube_extensions:
  sonarqube_logs:
  postgresql:
  postgresql_data:

Start the stack with the following command:

docker-compose up -d

Wait a minute or two for SonarQube to initialize, then navigate to http://localhost:9000 in your browser. The default credentials are admin for both username and password. You will be prompted to change the password on first login.

System Requirements

SonarQube is memory-intensive. For production deployments, ensure your host has at least 2GB of RAM available for SonarQube alone, plus additional memory for the database. On Linux, you may also need to increase the vm.max_map_count kernel setting:

sysctl -w vm.max_map_count=524288

To make this change persistent, add the following line to /etc/sysctl.conf:

vm.max_map_count=524288

Configuring Your First Project

Once SonarQube is running, the next step is to analyze a project. SonarQube supports two main analysis methods: using the SonarScanner CLI or integrating directly with your build tool such as Maven, Gradle, or MSBuild.

Creating a Project Token

From the SonarQube web interface, click Manually under the "Create a new project" section. Provide a project key and display name. SonarQube will generate a token that the scanner uses to authenticate. Save this token securely because it is shown only once.

Using the SonarScanner CLI

The SonarScanner is a standalone tool you can download and install on any machine. After installing it, create a configuration file named sonar-project.properties in the root of your project:

# Project identification
sonar.projectKey=my-awesome-project
sonar.projectName=My Awesome Project
sonar.projectVersion=1.0

# Source directories
sonar.sources=src

# Test directories
sonar.tests=tests

# Exclusions
sonar.exclusions=**/node_modules/**,**/*.spec.ts

# Language-specific settings
sonar.javascript.lcov.reportPaths=coverage/lcov.info
sonar.python.coverage.reportPaths=coverage.xml

# Encoding
sonar.sourceEncoding=UTF-8

Run the scanner from the project root, passing your SonarQube server URL and token:

sonar-scanner \
  -Dsonar.host.url=http://localhost:9000 \
  -Dsonar.login=your_project_token_here

After the scan completes, open the project dashboard in SonarQube to review the results.

Integrating with Maven

If you use Maven, you can run analysis without a separate properties file. Add the SonarQube plugin to your pom.xml:

<build>
  <plugins>
    <plugin>
      <groupId>org.jacoco</groupId>
      <artifactId>jacoco-maven-plugin</artifactId>
      <version>0.8.11</version>
      <executions>
        <execution>
          <goals>
            <goal>prepare-agent</goal>
          </goals>
        </execution>
        <execution>
          <id>report</id>
          <phase>test</phase>
          <goals>
            <goal>report</goal>
          </goals>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

Then run the analysis with a single command:

mvn clean verify sonar:sonar \
  -Dsonar.host.url=http://localhost:9000 \
  -Dsonar.login=your_project_token_here

The JaCoCo plugin generates coverage data that SonarQube imports automatically, giving you a complete picture of both code quality and test coverage.

Integrating with CI/CD Pipelines

To get the most value from SonarQube, you should run analysis on every pull request and on every merge to your main branch. Below are examples for popular CI/CD platforms.

GitHub Actions

name: SonarQube Analysis

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main, develop]

jobs:
  sonarqube:
    name: SonarQube Scan
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Set up JDK 17
        uses: actions/setup-java@v4
        with:
          java-version: '17'
          distribution: 'temurin'

      - name: Cache SonarQube packages
        uses: actions/cache@v4
        with:
          path: ~/.sonar/cache
          key: ${{ runner.os }}-sonar
          restore-keys: ${{ runner.os }}-sonar

      - name: Cache Maven packages
        uses: actions/cache@v4
        with:
          path: ~/.m2
          key: ${{ runner.os }}-m2-${{ hashFiles('**/pom.xml') }}
          restore-keys: ${{ runner.os }}-m2

      - name: Build and analyze
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
          SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}
        run: |
          mvn -B verify org.sonarsource.scanner.maven:sonar-maven-plugin:sonar \
            -Dsonar.projectKey=my-awesome-project \
            -Dsonar.host.url=$SONAR_HOST_URL \
            -Dsonar.login=$SONAR_TOKEN

Note the fetch-depth: 0 setting, which is required for SonarQube to perform blame analysis and detect new issues introduced by the pull request.

GitLab CI

sonarqube-check:
  stage: test
  image: maven:3.9-eclipse-temurin-17
  variables:
    SONAR_USER_HOME: "${CI_PROJECT_DIR}/.sonar"
    GIT_DEPTH: "0"
  cache:
    key: "${CI_JOB_NAME}"
    paths:
      - .sonar/cache
  script:
    - mvn verify sonar:sonar
        -Dsonar.projectKey=my-awesome-project
        -Dsonar.host.url=$SONAR_HOST_URL
        -Dsonar.login=$SONAR_TOKEN
  allow_failure: true
  only:
    - main
    - merge_requests

Configuring Quality Gates

A Quality Gate is the single most important configuration in SonarQube because it defines the pass/fail criteria for your code. The default "Sonar way" quality gate is a good starting point, but most teams customize it to fit their standards.

Creating a Custom Quality Gate

Navigate to Quality Gates in the top menu and click Create. Give your gate a descriptive name, then add conditions. A practical example for a mature team might include:

New code coverage is greater than 80%
Duplicated lines on new code is less than 3%
Blocker issues on new code is 0
Critical issues on new code is 0
Security hotspots reviewed on new code is 100%
Maintainability rating on new code is A
Reliability rating on new code is A
Security rating on new code is A

The key principle is to focus on new code rather than the entire codebase. This approach, called the "Clean as You Code" methodology, prevents teams from being overwhelmed by legacy issues while ensuring that no new problems are introduced.

Using the Web API to Manage Quality Gates

SonarQube exposes a comprehensive REST API. You can automate quality gate creation as part of your infrastructure-as-code strategy:

curl -u admin_token: -X POST "http://localhost:9000/api/qualitygates/create" \
  -d "name=Strict%20Gate"

curl -u admin_token: -X POST "http://localhost:9000/api/qualitygates/create_condition" \
  --data-urlencode "gateName=Strict Gate" \
  --data-urlencode "metric=new_coverage" \
  --data-urlencode "op=LT" \
  --data-urlencode "warning=80"

curl -u admin_token: -X POST "http://localhost:9000/api/qualitygates/create_condition" \
  --data-urlencode "gateName=Strict Gate" \
  --data-urlencode "metric=new_blocker_violations" \
  --data-urlencode "op=GT" \
  --data-urlencode "error=0"

Customizing Quality Profiles

Quality Profiles define which rules are active for each language. While the default profiles are well-curated, you may want to activate additional rules or deactivate ones that do not apply to your project.

Creating a Custom Profile

Go to Quality Profiles in the top navigation.
Select the language you want to customize.
Click Create and give your profile a name.
Click Activate More Rules to browse and enable additional rules.
Set the profile as the default for that language.

You can also extend an existing profile, which inherits all rules from the parent and lets you add or override specific rules. This is useful when you have multiple teams sharing a common baseline but with team-specific additions.

Importing and Exporting Profiles

Profiles can be exported as XML files and version-controlled alongside your code. This makes it easy to replicate configurations across environments:

curl -u admin_token: \
  "http://localhost:9000/api/qualityprofiles/export?language=java&qualityProfile=My%20Custom%20Profile" \
  -o my-custom-profile.xml

To import a profile into another SonarQube instance:

curl -u admin_token: -X POST \
  "http://localhost:9000/api/qualityprofiles/import" \
  --data-urlencode "language=java" \
  --data-urlencode "name=My Custom Profile" \
  -F "backup=@my-custom-profile.xml"

Handling Security Hotspots

Security Hotspots differ from regular vulnerabilities because they highlight code that might be security-sensitive but requires human judgment. Common examples include the use of cryptography, random number generation, and SQL queries. Not every hotspot is a real vulnerability, but each one deserves review.

Review Workflow

Open the Security Hotspots view for your project.
Click on each hotspot to see the code context and the rule description.
If the code is safe, mark it as Acknowledged or Safe.
If the code is vulnerable, mark it as Fixed after remediating the issue.

Setting a Quality Gate condition requiring 100% of hotspots to be reviewed on new code ensures that no security-sensitive code slips through without human attention.

Best Practices

Adopt the Clean as You Code Philosophy

Focus exclusively on new code. Trying to fix all legacy issues at once is rarely practical and often introduces risk. By ensuring that every new commit is clean, your codebase gradually improves over time without disruptive refactoring sprints.

Fail Builds on Quality Gate Failure

A Quality Gate is only effective if it has teeth. Configure your CI pipeline to fail the build when the gate does not pass. In GitHub Actions, you can use the SonarQube Quality Gate check action:

- name: SonarQube Quality Gate check
  uses: sonarsource/sonarqube-quality-gate-action@master
  timeout-minutes: 5
  env:
    SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
    SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}

Use Pull Request Decoration

Pull request decoration injects SonarQube analysis results directly into your pull request interface, showing inline comments and an overall quality gate status. This gives reviewers immediate visibility into code quality without leaving the PR. To enable this with GitHub, configure an ALM integration under Administration > Pull Requests using a GitHub App or personal access token.

Exclude Generated and Third-Party Code

Generated code, vendored dependencies, and minified assets should be excluded from analysis. They inflate metrics and create noise. Use the sonar.exclusions and sonar.coverage.exclusions properties strategically:

sonar.exclusions=**/generated/**,**/vendor/**,**/*.min.js
sonar.coverage.exclusions=**/generated/**,**/migrations/**,**/*Config.java

Run Analysis Incrementally

For large codebases, full analysis can take significant time. Use the sonar.scm.revision and branch parameters to perform incremental analysis on pull requests, which only evaluates changed files and their dependencies. This keeps feedback loops fast.

Regularly Update SonarQube

SonarQube releases new versions frequently, often with improved analyzers, new rules, and security patches. Stay on a supported LTS (Long Term Support) version and plan upgrades during maintenance windows. Always back up your database before upgrading.

Monitor and Alert on Metrics

Use the SonarQube Web API to export metrics and feed them into dashboards like Grafana. Track trends such as technical debt ratio, duplication percentage, and issue count over time. Set alerts when metrics cross thresholds so you can intervene early.

curl -u admin_token: \
  "http://localhost:9000/api/measures/component?component=my-awesome-project&metricKeys=sqale_index,duplicated_lines_density,bugs,vulnerabilities,code_smells"

Train Your Team on Rule Interpretation

SonarQube reports are only valuable if developers understand what the rules mean and how to fix the issues. Invest time in team training sessions, create internal documentation for common false positives, and encourage developers to review the rule descriptions directly in the SonarQube interface.

Conclusion

SonarQube is a powerful platform that brings visibility and accountability to code quality. By setting it up properly, integrating it into your CI/CD pipelines, configuring meaningful quality gates, and following the Clean as You Code methodology, you can systematically reduce technical debt and prevent new issues from entering your codebase. The key to success is consistency: run analysis on every pull request, enforce quality gates as blocking checks, and foster a culture where code quality is a shared responsibility. Start with the defaults, measure your results, and iteratively tighten your standards as your team matures. Over time, SonarQube becomes not just a tool but a cornerstone of your engineering excellence strategy.