SonarQube Jenkins Integration: Complete Pipeline Setup Guide

Jenkins remains the most popular CI/CD server in enterprise environments, and SonarQube is the most widely deployed static analysis platform. Combining the two gives you automated code quality enforcement on every build - catching bugs, vulnerabilities, and code smells before they reach production. This guide walks you through the complete integration from installing the Jenkins plugin to configuring quality gate webhooks, multi-branch pipelines, and build system-specific setups for Maven and Gradle.

By the end, you will have a Jenkins pipeline that runs SonarQube analysis on every commit and blocks merges when your code does not meet quality standards.

If you have not installed SonarQube yet, start with our SonarQube Docker installation guide or the complete SonarQube setup guide first.

Prerequisites

Before setting up the SonarQube Jenkins integration, make sure you have the following in place:

• Jenkins 2.387 or later - running and accessible with admin permissions
• A SonarQube server - Community, Developer, or Enterprise Edition running on a reachable URL (for example, http://sonarqube.yourcompany.com:9000). See our SonarQube Docker guide for installation instructions
• A SonarQube authentication token - generated from My Account, then Security, then Generate Tokens in the SonarQube web interface
• Java 17 or later on the Jenkins agent - required by the SonarScanner CLI
• A project to scan - any codebase in a language SonarQube supports (Java, JavaScript, TypeScript, Python, C#, Go, PHP, and 25+ others)

You should also have a basic understanding of Jenkins pipelines and Jenkinsfile syntax. This guide uses Declarative Pipeline syntax throughout, which is the recommended approach for most teams.

Step 1 - Install the SonarQube Scanner plugin

The SonarQube Scanner for Jenkins plugin provides the pipeline steps needed to connect Jenkins to your SonarQube server. Without it, you would need to manually configure environment variables and handle the quality gate callback yourself.

Install from the Jenkins UI

1. Navigate to Manage Jenkins, then Plugins, then Available Plugins
2. Search for SonarQube Scanner
3. Check the box next to SonarQube Scanner for Jenkins (plugin ID: sonar)
4. Click Install and wait for the installation to complete
5. Restart Jenkins if prompted

Verify the installation

After the restart, go to Manage Jenkins, then Plugins, then Installed Plugins and confirm that SonarQube Scanner for Jenkins appears in the list. The plugin adds several capabilities to Jenkins:

• The withSonarQubeEnv pipeline step for injecting SonarQube credentials
• The waitForQualityGate pipeline step for quality gate evaluation
• A SonarQube Scanner tool installation option under Global Tool Configuration
• A SonarQube Scanner build step for freestyle jobs

Install the SonarScanner CLI tool (optional)

If your project does not use Maven or Gradle (which have their own SonarQube plugins), you need the SonarScanner CLI available on the Jenkins agent. You can install it globally through Jenkins:

1. Navigate to Manage Jenkins, then Tools
2. Scroll to SonarQube Scanner installations
3. Click Add SonarQube Scanner
4. Give it a name like SonarScanner and check Install automatically
5. Select the latest version from the dropdown
6. Click Save

Jenkins will download and install the scanner on any agent that needs it during the first build.

Step 2 - Configure the SonarQube server in Jenkins

With the plugin installed, you need to tell Jenkins where your SonarQube server lives and how to authenticate.

Add the SonarQube token as a credential

1. Navigate to Manage Jenkins, then Credentials
2. Select the appropriate scope (global or a specific folder)
3. Click Add Credentials
4. Set the Kind to Secret text
5. Paste your SonarQube authentication token into the Secret field
6. Set the ID to sonarqube-token (you will reference this ID later)
7. Add a description like “SonarQube authentication token”
8. Click Create

Configure the SonarQube server

1. Navigate to Manage Jenkins, then System
2. Scroll to the SonarQube servers section
3. Check Environment variables - this enables the withSonarQubeEnv pipeline step to inject SONAR_HOST_URL and SONAR_AUTH_TOKEN automatically
4. Click Add SonarQube
5. Fill in the details:
   • Name - SonarQube (this name is referenced in your Jenkinsfile)
   • Server URL - your SonarQube instance URL (for example, http://sonarqube.yourcompany.com:9000)
   • Server authentication token - select the sonarqube-token credential you created
6. Click Save

You can configure multiple SonarQube servers if your organization runs separate instances for different teams or environments. Each server gets a unique name that you reference in the withSonarQubeEnv step.

Step 3 - Create a Jenkins Declarative Pipeline

Now that Jenkins knows about your SonarQube server, it is time to create a pipeline that runs the analysis. This section provides a complete Declarative Jenkinsfile that scans your code and checks the quality gate.

Basic Jenkinsfile with SonarQube analysis

Create a Jenkinsfile in your repository root with the following content:

pipeline {
    agent any

    stages {
        stage('Checkout') {
            steps {
                checkout scm
            }
        }

        stage('Build & Test') {
            steps {
                sh 'echo "Run your build and test commands here"'
            }
        }

        stage('SonarQube Analysis') {
            steps {
                withSonarQubeEnv('SonarQube') {
                    sh """
                        sonar-scanner \
                          -Dsonar.projectKey=my-project \
                          -Dsonar.projectName='My Project' \
                          -Dsonar.sources=src \
                          -Dsonar.sourceEncoding=UTF-8
                    """
                }
            }
        }

        stage('Quality Gate') {
            steps {
                timeout(time: 5, unit: 'MINUTES') {
                    waitForQualityGate abortPipeline: true
                }
            }
        }
    }

    post {
        failure {
            echo 'Pipeline failed - check SonarQube dashboard for details'
        }
        success {
            echo 'Pipeline passed - code meets quality standards'
        }
    }
}

There are two critical elements in this pipeline. The withSonarQubeEnv('SonarQube') block injects the server URL and authentication token as environment variables so you do not hardcode credentials in your Jenkinsfile. The waitForQualityGate abortPipeline: true step polls SonarQube for the quality gate result and fails the build if the code does not pass.

Jenkinsfile for a Node.js/TypeScript project

Here is a more complete example for a JavaScript or TypeScript project with test coverage:

pipeline {
    agent any

    tools {
        nodejs 'Node-20'
    }

    environment {
        SCANNER_HOME = tool 'SonarScanner'
    }

    stages {
        stage('Install Dependencies') {
            steps {
                sh 'npm ci'
            }
        }

        stage('Run Tests') {
            steps {
                sh 'npm test -- --coverage --coverageReporters=lcov'
            }
        }

        stage('SonarQube Analysis') {
            steps {
                withSonarQubeEnv('SonarQube') {
                    sh """
                        ${SCANNER_HOME}/bin/sonar-scanner \
                          -Dsonar.projectKey=my-node-app \
                          -Dsonar.projectName='My Node App' \
                          -Dsonar.sources=src \
                          -Dsonar.tests=src \
                          -Dsonar.test.inclusions='**/*.test.ts,**/*.spec.ts' \
                          -Dsonar.exclusions='**/node_modules/**,**/dist/**,**/coverage/**' \
                          -Dsonar.javascript.lcov.reportPaths=coverage/lcov.info \
                          -Dsonar.sourceEncoding=UTF-8
                    """
                }
            }
        }

        stage('Quality Gate') {
            steps {
                timeout(time: 5, unit: 'MINUTES') {
                    waitForQualityGate abortPipeline: true
                }
            }
        }
    }

    post {
        always {
            junit allowEmptyResults: true, testResults: '**/test-results/*.xml'
        }
    }
}

The environment block uses the tool function to resolve the SonarScanner installation path, so the scanner binary is referenced as ${SCANNER_HOME}/bin/sonar-scanner. This works with the automatic installation configured in Step 1.

Using a sonar-project.properties file

Instead of passing all parameters on the command line, you can create a sonar-project.properties file in your repository root:

sonar.projectKey=my-project
sonar.projectName=My Project
sonar.projectVersion=1.0.0

sonar.sources=src
sonar.tests=tests
sonar.sourceEncoding=UTF-8

sonar.exclusions=**/node_modules/**,**/dist/**,**/coverage/**
sonar.javascript.lcov.reportPaths=coverage/lcov.info

Then simplify the Jenkinsfile analysis stage:

stage('SonarQube Analysis') {
    steps {
        withSonarQubeEnv('SonarQube') {
            sh "${SCANNER_HOME}/bin/sonar-scanner"
        }
    }
}

The scanner automatically reads the properties file from the current directory. The server URL and token are still injected by withSonarQubeEnv and do not need to appear in the properties file.

Step 4 - Configure the quality gate webhook

The waitForQualityGate step in your Jenkinsfile works by waiting for SonarQube to push the quality gate result back to Jenkins via a webhook. Without this webhook, the step will time out after 5 minutes and fail the build even if the analysis passed.

Create the webhook in SonarQube

1. Log in to SonarQube as an administrator
2. Navigate to Administration, then Configuration, then Webhooks
3. Click Create
4. Fill in the details:
   • Name - Jenkins
   • URL - http://your-jenkins-url/sonarqube-webhook/
   • Secret - leave empty unless you want to verify webhook payloads (recommended for production)
5. Click Create

The trailing slash in the URL is important. Jenkins expects the webhook at /sonarqube-webhook/ - omitting the slash can cause a 302 redirect that drops the POST body.

Verify the webhook works

After configuring the webhook, run your Jenkins pipeline. In the SonarQube webhook administration page, you can see the delivery history for each webhook. A successful delivery shows a 200 response code. If you see 404 or 403, check the following:

• The Jenkins URL is correct and reachable from the SonarQube server
• There is no firewall blocking traffic between SonarQube and Jenkins
• If Jenkins requires authentication, the webhook URL may need to bypass CSRF protection (this is handled automatically by the SonarQube Scanner plugin)

Project-level webhooks

You can also create webhooks at the project level instead of globally. Navigate to your project in SonarQube, then Project Settings, then Webhooks. Project-level webhooks only fire for that specific project, which is useful when different projects report to different Jenkins instances.

Step 5 - Multi-branch pipeline setup

Multi-branch pipelines in Jenkins automatically create jobs for every branch and pull request in your repository. Combined with SonarQube, this gives you branch-specific analysis and PR-level quality gate enforcement.

Create a multi-branch pipeline job

1. In Jenkins, click New Item
2. Enter a name and select Multibranch Pipeline
3. Under Branch Sources, add your Git repository URL and credentials
4. Under Build Configuration, set the Script Path to Jenkinsfile
5. Click Save - Jenkins will scan your repository and create jobs for each branch

Jenkinsfile with branch and PR detection

Update your Jenkinsfile to pass the correct SonarQube parameters depending on whether the build is for a branch or a pull request:

pipeline {
    agent any

    environment {
        SCANNER_HOME = tool 'SonarScanner'
    }

    stages {
        stage('Build & Test') {
            steps {
                sh 'npm ci && npm test -- --coverage --coverageReporters=lcov'
            }
        }

        stage('SonarQube Analysis') {
            steps {
                withSonarQubeEnv('SonarQube') {
                    script {
                        def scannerParams = "-Dsonar.projectKey=my-project"

                        if (env.CHANGE_ID) {
                            // Pull request build
                            scannerParams += " -Dsonar.pullrequest.key=${env.CHANGE_ID}"
                            scannerParams += " -Dsonar.pullrequest.branch=${env.CHANGE_BRANCH}"
                            scannerParams += " -Dsonar.pullrequest.base=${env.CHANGE_TARGET}"
                        } else {
                            // Branch build
                            scannerParams += " -Dsonar.branch.name=${env.BRANCH_NAME}"
                        }

                        sh "${SCANNER_HOME}/bin/sonar-scanner ${scannerParams}"
                    }
                }
            }
        }

        stage('Quality Gate') {
            steps {
                timeout(time: 5, unit: 'MINUTES') {
                    waitForQualityGate abortPipeline: true
                }
            }
        }
    }
}

The CHANGE_ID environment variable is set by Jenkins only for pull request builds. When it is present, the pipeline passes PR-specific parameters to SonarQube. When it is absent, the pipeline passes the branch name instead. This distinction is important because SonarQube analyzes branches and pull requests differently - PR analysis compares against the target branch, while branch analysis compares against the main branch or the New Code definition.

Note that PR decoration (SonarQube posting comments on the pull request) requires Developer Edition or higher. Community Edition only supports main branch analysis. For a detailed comparison of editions, see our SonarQube pricing guide.

Maven integration

Java teams using Maven can skip the SonarScanner CLI entirely. The SonarQube Maven plugin handles the analysis directly through the Maven build lifecycle.

Jenkinsfile for Maven projects

pipeline {
    agent any

    tools {
        maven 'Maven-3.9'
        jdk 'JDK-17'
    }

    stages {
        stage('Build & Test') {
            steps {
                sh 'mvn clean verify'
            }
        }

        stage('SonarQube Analysis') {
            steps {
                withSonarQubeEnv('SonarQube') {
                    sh 'mvn sonar:sonar'
                }
            }
        }

        stage('Quality Gate') {
            steps {
                timeout(time: 5, unit: 'MINUTES') {
                    waitForQualityGate abortPipeline: true
                }
            }
        }
    }
}

The mvn sonar:sonar command uses the SonarQube Maven plugin (org.sonarsource.scanner.maven:sonar-maven-plugin). It automatically detects the project structure, source directories, compiled classes, and test results from your pom.xml. The withSonarQubeEnv block injects the server URL and token as system properties that the Maven plugin reads automatically.

Configure Maven for multi-module projects

For multi-module Maven projects, add the SonarQube plugin to the parent pom.xml:

<build>
    <pluginManagement>
        <plugins>
            <plugin>
                <groupId>org.sonarsource.scanner.maven</groupId>
                <artifactId>sonar-maven-plugin</artifactId>
                <version>4.0.0.4121</version>
            </plugin>
        </plugins>
    </pluginManagement>
</build>

Run the analysis from the parent module and SonarQube will analyze all child modules as a single project:

stage('SonarQube Analysis') {
    steps {
        withSonarQubeEnv('SonarQube') {
            sh 'mvn sonar:sonar -Dsonar.projectKey=my-multi-module-app'
        }
    }
}

JaCoCo code coverage for Maven

To include code coverage in SonarQube’s analysis, add the JaCoCo Maven plugin to your pom.xml:

<plugin>
    <groupId>org.jacoco</groupId>
    <artifactId>jacoco-maven-plugin</artifactId>
    <version>0.8.12</version>
    <executions>
        <execution>
            <goals>
                <goal>prepare-agent</goal>
            </goals>
        </execution>
        <execution>
            <id>report</id>
            <phase>verify</phase>
            <goals>
                <goal>report</goal>
            </goals>
        </execution>
    </executions>
</plugin>

The mvn clean verify step in the Jenkinsfile generates the JaCoCo report, and the SonarQube Maven plugin picks it up automatically from target/site/jacoco/jacoco.xml.

Gradle integration

Gradle projects use the SonarQube Gradle plugin for analysis instead of the CLI scanner.

Add the SonarQube Gradle plugin

In your build.gradle:

plugins {
    id 'org.sonarqube' version '5.1.0.4882'
}

sonar {
    properties {
        property 'sonar.projectKey', 'my-gradle-app'
        property 'sonar.projectName', 'My Gradle App'
        property 'sonar.sources', 'src/main/java'
        property 'sonar.tests', 'src/test/java'
    }
}

For Kotlin DSL (build.gradle.kts):

plugins {
    id("org.sonarqube") version "5.1.0.4882"
}

sonar {
    properties {
        property("sonar.projectKey", "my-gradle-app")
        property("sonar.projectName", "My Gradle App")
    }
}

Jenkinsfile for Gradle projects

pipeline {
    agent any

    tools {
        jdk 'JDK-17'
    }

    stages {
        stage('Build & Test') {
            steps {
                sh './gradlew clean build jacocoTestReport'
            }
        }

        stage('SonarQube Analysis') {
            steps {
                withSonarQubeEnv('SonarQube') {
                    sh './gradlew sonar'
                }
            }
        }

        stage('Quality Gate') {
            steps {
                timeout(time: 5, unit: 'MINUTES') {
                    waitForQualityGate abortPipeline: true
                }
            }
        }
    }
}

The Gradle SonarQube plugin reads SONAR_HOST_URL and SONAR_AUTH_TOKEN from environment variables, which are injected by withSonarQubeEnv. The jacocoTestReport task generates the coverage report that the SonarQube plugin picks up automatically.

Troubleshooting

Even with a correct setup, SonarQube Jenkins integration can hit several common issues. Here are the most frequent problems and their solutions.

waitForQualityGate times out

Symptom: The Quality Gate stage hangs for 5 minutes and then fails with a timeout error.

Cause: The SonarQube webhook is not configured, misconfigured, or blocked by a firewall.

Fix: Verify the webhook exists in SonarQube under Administration, then Configuration, then Webhooks. The URL must point to http://your-jenkins-url/sonarqube-webhook/ with a trailing slash. Check the webhook delivery history in SonarQube for failed deliveries. If Jenkins is behind a reverse proxy or load balancer, ensure the proxy forwards POST requests to the webhook endpoint.

Scanner reports “Not authorized” or “401”

Symptom: The sonar-scanner command fails with an authentication error.

Fix: Verify that the SonarQube token credential in Jenkins is correct and has not expired. Navigate to Manage Jenkins, then System, then SonarQube Servers and confirm the token credential is selected. In SonarQube, regenerate the token under My Account, then Security if needed, and update the Jenkins credential.

SonarQube analysis runs but shows zero coverage

Symptom: The SonarQube dashboard shows 0% coverage even though tests are running.

Fix: Ensure your test stage runs before the SonarQube analysis stage and generates a coverage report in the correct format. Verify the coverage report path in your scanner configuration matches the actual file location. For JavaScript/TypeScript, check that sonar.javascript.lcov.reportPaths points to your lcov.info file. For Java, confirm that JaCoCo is generating jacoco.xml in the expected directory.

Pipeline fails with “No such DSL method ‘waitForQualityGate’”

Symptom: Jenkins throws an error saying waitForQualityGate is not recognized.

Fix: The SonarQube Scanner for Jenkins plugin is either not installed or is an older version that does not include the waitForQualityGate step. Update the plugin to the latest version from Manage Jenkins, then Plugins, then Updates. Restart Jenkins after updating.

Scanner cannot find the SonarQube server

Symptom: The scanner fails with a connection refused or timeout error.

Fix: If SonarQube and Jenkins run on the same machine, ensure the URL uses the correct port (default 9000). If they run on different machines, verify network connectivity between the Jenkins agent and the SonarQube server. When using Docker, use host.docker.internal or the container’s network hostname instead of localhost.

Build is slow due to SonarQube analysis

Symptom: Adding SonarQube adds 10+ minutes to your build time.

Fix: Review your source and exclusion configuration. Exclude generated code, vendored dependencies, and build artifacts. Add memory to the scanner with -Dsonar.scanner.javaOpts=-Xmx2048m. For very large projects, consider running the SonarQube analysis in a parallel stage that does not block other build steps.

Alternatives to SonarQube for Jenkins

SonarQube is a powerful platform, but self-hosting it adds operational overhead - especially when combined with Jenkins infrastructure that also requires maintenance. If you are looking for alternatives that reduce this burden, here are options worth evaluating.

CodeAnt AI

CodeAnt AI combines static analysis with AI-powered code review in a single managed platform. At $24 to $40 per user per month, it provides automated PR reviews, security scanning, code quality checks, and auto-fixes with no infrastructure to manage. CodeAnt AI connects directly to your repositories and integrates with CI/CD pipelines including Jenkins. For teams that want code quality enforcement without running and maintaining SonarQube servers, CodeAnt AI eliminates the self-hosting overhead entirely.

SonarQube Cloud

If you want the SonarQube analysis engine without the self-hosting burden, SonarQube Cloud (formerly SonarCloud) is the SaaS version managed by SonarSource. It provides the same rules and quality gates as self-hosted SonarQube with PR decoration included on all tiers. See our SonarQube pricing breakdown for a detailed cost comparison.

For a broader look at the landscape, our SonarQube alternatives guide covers additional options including Codacy, DeepSource, Semgrep, and Checkmarx.

Conclusion

Integrating SonarQube with Jenkins creates a robust automated quality gate that catches bugs, vulnerabilities, and code smells on every build. The setup involves four key pieces - the Jenkins plugin, the SonarQube server configuration, the Declarative Jenkinsfile, and the quality gate webhook. Once these are in place, every commit is analyzed automatically and builds that do not meet your quality standards are blocked before they can be merged.

Here is a summary of what this guide covered:

• Plugin installation - adding the SonarQube Scanner for Jenkins plugin and configuring the SonarScanner CLI tool
• Server configuration - connecting Jenkins to your SonarQube instance with secure credential management
• Declarative Pipeline - complete Jenkinsfile examples for Node.js, Maven, and Gradle projects
• Quality gate webhook - configuring SonarQube to push quality gate results back to Jenkins in real time
• Multi-branch pipelines - branch and PR detection with dynamic scanner parameters
• Build system integration - Maven and Gradle-specific configuration with JaCoCo code coverage
• Troubleshooting - solutions for the most common integration issues

For teams that want to avoid the operational overhead of maintaining both Jenkins and SonarQube infrastructure, CodeAnt AI ($24-$40/user/month) and SonarQube Cloud offer managed alternatives. If you are using GitHub Actions instead of Jenkins, see our SonarQube GitHub Actions guide for a GitHub-native approach.

For more SonarQube content, check out our SonarQube review for an honest assessment of the platform’s strengths and weaknesses.