Github Actions

Configure an analysis of your SonarQube Cloud project using GitHub Actions.

To configure an analysis of your project using GitHub Actions, you will use the SonarQube Scan GitHub Action.

Prerequisites

From SonarQube Scan GitHub Action version 5.0.0 (sonarqube-scan-action):

• If your runner is GitHub-hosted, all required utilities should be already provided by default.
• If your runner is self-hosted, you need to ensure that the following utilities are installed and available in the PATH: unzip, wget or curl, gpg and dirmngr.

SonarQube Scan GitHub Action update notes

In v8, the SonarQube Scan GitHub Action uses GPG to validate the integrity of the Scanner CLI.

The SonarQube Scan GitHub Action version 8 uses GPG to validate the integrity of the Scanner CLI. Please see this release note for the SonarQube Scan GitHub Action.

in v7, the SonarQube Scan GitHub Action uses Scanner CLI v8

The SonarQube Scan GitHub Action version 7 uses the Scanner CLI v8. Please see this release note for the SonarQube Scan GitHub Action.

• The main change on Scanner CLI v8 is related to the embedded JRE version which is now Java 21. Please see this release note for the SonarScanner CLI.

In v6, the SonarQube Scan GitHub Action handles arguments differently

The args input is parsed differently in v6. When updating to v6, you might have to update your workflow to change how arguments are quoted. See this release note for more information.

In v5, SonarQube Scan GitHub Action is not based on Docker

v3.1.0 and below of the GitHub Action are based on Docker: at every execution of the action, a dedicated docker container is spawned.

The advantage of using container are primarily:

• isolation, since the SonarScanner gets only access to the directory where the project is checked out
• full control of the environment where the SonarScanner is executed, in terms of required utilities such as wget and keytool

The use of Docker comes, however, with multiple disadvantages:

• issues with analyzers requiring access to a system-level directories, such as cache of dependencies in Java or Dart
• issues with DockerHub rate limit on peak workload scenarios
• requirement by GitHub to run as root user
• support for Docker-based actions limited to Linux - no Windows nor MacOS

v5 doesn't have the Docker dependency, making the action composite. The action now runs in the environment of the runner executing the GitHub workflow.

Analysis setup overview

You should follow the in-product tutorial when creating a new project. When it’s time to Choose your Analysis Method during setup, select With GitHub Actions. You can also access the tutorials for an existing project by going to Your Project > Administration > Analysis Method.

The tutorial will walk you through the precise steps to set up the analysis but the basic steps are these:

1. Define the SONAR_TOKEN environment variable in your repository by setting up a GitHub Secret. The SONAR_TOKEN identifies and authenticates you to SonarQube Cloud. The tutorial will provide the precise value for your specific account. To generate the token, see:

   • From the Team plan: Scoped Organization Tokens.
   • With the Free plan: Managing personal access tokens.
2. Set the parameters used to connect to the instance and identify the project. See:

   • Server connection

   • Project identification

   The tutorial will be populated with the correct values for your specific account. The parameters are set differently depending on your project type:

   • In the pom.xml for Java Maven projects.
   • In the build.gradle file for Java Gradle projects.
   • In the SonarScanner command line for .NET projects.
   • In the sonar-project.properties file for other types of projects.

   You can also add additional analysis parameters to further specify your analysis details. For more information about analysis parameters setup, see Configuration overview.
3. Set up your workflow file that defines the steps of your build. In addition to the usual steps that build your project, you need to invoke the SonarScanner to perform the analysis of your code. For more information, see below.

Setting up your workflow file

This section shows you how to configure your .github/workflows/build.yml file.

GitHub Actions can build specific branches and pull requests if you use on.push.branches and on.pull-requests configurations as shown in the examples below.

In the tabs below, click the scanner you’re using to expand the example configuration:

• For Maven projects: SonarScanner for Maven
• For Gradle projects: SonarScanner for Gradle
• For .NET projects: SonarScanner for .NET
• For other projects: SonarScanner CLI

In the example configurations, the EU region is used. If you want to use the US region, See Choosing your server region.

Maven

Write the following in your workflow YAML file.

A project key might have to be provided through the command line parameter. For more information, see SonarScanner for Maven.

name: Build
on:
 push:
   branches:
     - main # the name of your main branch
 pull_request:
   types: [opened, synchronize, reopened]
jobs:
 build:
   name: Build
   runs-on: ubuntu-latest
   steps:
     - uses: actions/checkout@v6
       with:
         fetch-depth: 0  # Shallow clones should be disabled for a better relevancy of analysis
     - name: Set up JDK 21
       uses: actions/setup-java@v4
       with:
         distribution: temurin
         java-version: 21
     - 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:
         SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
       run: mvn -B verify org.sonarsource.scanner.maven:sonar-maven-plugin:sonar

Gradle

1. Activate the SonarScanner for Gradle in your build. See Activate the scanner in your build.
2. Write the following in your workflow YAML file.

name: Build
on:
 push:
   branches:
     - main # the name of your main branch
 pull_request:
   types: [opened, synchronize, reopened]
jobs:
 build:
   name: Build
   runs-on: ubuntu-latest
   steps:
     - uses: actions/checkout@v6
       with:
         fetch-depth: 0  # Shallow clones should be disabled for a better relevancy of analysis
     - name: Set up JDK 21
       uses: actions/setup-java@v4
       with:
         distribution: temurin
         java-version: 21
     - name: Cache SonarQube packages
       uses: actions/cache@v4
       with:
         path: ~/.sonar/cache
         key: ${{ runner.os }}-sonar
         restore-keys: ${{ runner.os }}-sonar
     - name: Cache Gradle packages
       uses: actions/cache@v4
       with:
         path: ~/.gradle/caches
         key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle') }}
         restore-keys: ${{ runner.os }}-gradle
     - name: Build and analyze
       env:
         SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
       run: ./gradlew build sonar --info

.NET

Write the following in your workflow YAML file.

name: Build
on:
 push:
   branches:
     - main # the name of your main branch
 pull_request:
   types: [opened, synchronize, reopened]
jobs:
 build:
   name: Build
   runs-on: windows-latest
   steps:
     - name: Set up JDK 21
       uses: actions/setup-java@v4
       with:
         distribution: temurin
         java-version: 21
     - uses: actions/checkout@v6
       with:
         fetch-depth: 0  # Shallow clones should be disabled for a better relevancy of analysis
     - name: Cache SonarQube packages
       uses: actions/cache@v4
       with:
         path: ~\.sonar\cache
         key: ${{ runner.os }}-sonar
         restore-keys: ${{ runner.os }}-sonar
     - name: Cache SonarQube scanner
       id: cache-sonar-scanner
       uses: actions/cache@v4
       with:
         path: .\.sonar\scanner
         key: ${{ runner.os }}-sonar-scanner
         restore-keys: ${{ runner.os }}-sonar-scanner
     - name: Install SonarQube scanner
       if: steps.cache-sonar-scanner.outputs.cache-hit != 'true'
       shell: pwsh
       run: |
         New-Item -Path .\.sonar\scanner -ItemType Directory
         dotnet tool update dotnet-sonarscanner --tool-path .\.sonar\scanner
     - name: Build and analyze
       shell: pwsh
       run: |
         # Fail fast and propagate errors to the runner
         # https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_preference_variables?view=powershell-7.5
         $ErrorActionPreference = "Stop"
         $PSNativeCommandUseErrorActionPreference = $true
         .\.sonar\scanner\dotnet-sonarscanner begin /k:"example" /o:"example" /d:sonar.token="${{ secrets.SONAR_TOKEN }}"
         dotnet build
         .\.sonar\scanner\dotnet-sonarscanner end /d:sonar.token="${{ secrets.SONAR_TOKEN }}"

CLI

You can easily set up a basic configuration using the SonarQube Scan GitHub action, for all languages, including C, C++, Objective-C, and Dart.

You’ll find the GitHub Actions and configuration instructions page on the GitHub Marketplace.

For C, C++, and Objective-C projects relying on Build Wrapper to generate the compilation database (see the CFamily Prerequisites page), use the sonarqube-scan-action/install-build-wrapper sub-action to install the Build Wrapper.

Preventing pull request merges when the quality gate fails

See Preventing the pull request merge if the quality gate fails.

Failing the workflow when the quality gate fails

You fail a GitHub Actions workflow on quality-gate failure by making the scanner wait for the Quality Gate result and exit non-zero if it’s failed.

To do so, use the sonar.qualitygate.wait analysis parameter (optionally with sonar.qualitygate.timeout). For more information about these parameters, see Quality gate.

Analyzing Monorepo Projects: Build Configuration

The example below shows how you could set up a yml file for multiple projects in a monorepo. If you want to analyze a monorepo that contains more than one project ensure that you specify the paths to each sub-project for analysis in your build file.

To ensure that your monorepo works as expected, you need to build each project in the monorepo separately with a unique project key for each one.

GitHub Actions .yml file

name: My Test Monorepo Project
on:
  push:
      branches:
      - main
      paths:
      - 'lambdas/test/**'
  pull_request:
    types: [opened, synchronize, reopened]
jobs:
  sonarqubeScan1:
    name: SonarQubeScan1
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0  
      - name: SonarQube Scan
        uses: SonarSource/sonarqube-scan-action@v7
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
        with:
          projectBaseDir: repo1/
          
  sonarqubeScan2:
    name: SonarQubeScan2
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0  
      - name: SonarQube Scan
        uses: SonarSource/sonarqube-scan-action@v7
        env: 
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
        with:
          projectBaseDir: repo2/

Analyzing pull requests from forked repositories

GitHub doesn't expose repository secrets to workflows triggered by a pull request from a fork. Because your SONAR_TOKEN is a secret, a single combined build-and-analyze workflow can't run on fork pull requests.

Automatic Analysis supports fork pull requests without any extra setup, but doesn't produce coverage data. If you need CI-based analysis with coverage on fork pull requests, split the work across three workflows: one for regular (non-fork) pull requests, one that builds fork code without exposing secrets, and one that runs the Sonar analysis with secrets but never executes fork-provided code.

Checking out a fork's code in a workflow that has access to secrets is a sensitive pattern, even when that code is never executed. Validate every value you pull from the fork's pull request before using it, and keep the analysis job's permissions as narrow as possible.

Workflow 1: build and analyze non-fork pull requests

This workflow behaves like a standard CI workflow. Restrict it to non-fork pull requests, and analyze directly since the build runs in a trusted context:

name: CI

on:
  push:
    branches:
      - main # the name of your main branch
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest
    if: github.event.pull_request.head.repo.fork == false
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0
      - name: Set up JDK 21
        uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: 21
      - name: Build and analyze
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
        run: mvn -B verify org.sonarsource.scanner.maven:sonar-maven-plugin:sonar

Workflow 2: build fork pull requests without secrets

This workflow builds and tests fork pull requests with no secret access, then uploads the build output and the PR metadata the next workflow needs as artifacts. Interpolating untrusted values (branch names, ref names) directly into a run: shell command is a script-injection risk. Instead, pass PR metadata through an env: block:

name: CI on forks - build and tests

on:
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest
    if: github.event.pull_request.head.repo.fork == true
    steps:
      - name: Checkout sources
        uses: actions/checkout@v6
        with:
          persist-credentials: false

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

      - name: Build and test
        run: mvn -B verify

      - name: Save build output
        uses: actions/upload-artifact@v4
        with:
          name: build-output-${{ github.event.pull_request.number }}
          retention-days: 1
          path: |
            **/target/classes
            **/target/generated-sources

      - name: Save PR information
        env:
          REPO_NAME: ${{ github.event.pull_request.head.repo.full_name }}
          HEAD_REF: ${{ github.event.pull_request.head.ref }}
          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
          PR_NUMBER: ${{ github.event.pull_request.number }}
          BASE_REF: ${{ github.event.pull_request.base.ref }}
        run: |
          mkdir -p pr-info
          echo "$REPO_NAME" > pr-info/repo-name
          echo "$HEAD_REF" > pr-info/head-ref
          echo "$HEAD_SHA" > pr-info/head-sha
          echo "$PR_NUMBER" > pr-info/pr-number
          echo "$BASE_REF" > pr-info/base-ref

      - name: Upload PR information
        uses: actions/upload-artifact@v4
        with:
          name: pr-info-${{ github.event.pull_request.number }}
          path: pr-info/
          retention-days: 1

Workflow 3: run the Sonar analysis for fork pull requests

This workflow triggers on workflow_run once workflow 2 finishes, so it runs in the base repository's trusted context with secrets available. It downloads the build output and PR metadata, checks out the fork's code without executing it, and runs the scan:

name: CI on forks - Sonar analysis

on:
  workflow_run:
    workflows: [CI on forks - build and tests]
    types:
      - completed

jobs:
  sonar:
    runs-on: ubuntu-latest
    if: >
      github.event.workflow_run.event == 'pull_request' &&
      github.event.workflow_run.conclusion == 'success'
    permissions:
      actions: write
      contents: read
      pull-requests: write
    steps:
      - name: Download PR information
        uses: actions/download-artifact@v4
        with:
          pattern: pr-info-*
          path: ${{ runner.temp }}/pr-info
          merge-multiple: true
          run-id: ${{ github.event.workflow_run.id }}
          github-token: ${{ secrets.GITHUB_TOKEN }}

      - name: Extract and validate PR information
        id: pr-info
        run: |
          HEAD_SHA=$(cat ${{ runner.temp }}/pr-info/head-sha)
          HEAD_REF=$(cat ${{ runner.temp }}/pr-info/head-ref)
          PR_NUMBER=$(cat ${{ runner.temp }}/pr-info/pr-number)
          BASE_REF=$(cat ${{ runner.temp }}/pr-info/base-ref)
          [[ "$HEAD_SHA" =~ ^[0-9a-f]{40}$ ]] || { echo "Invalid HEAD_SHA"; exit 1; }
          [[ "$HEAD_REF" =~ ^[a-zA-Z0-9/_.-]+$ ]] || { echo "Invalid HEAD_REF"; exit 1; }
          [[ "$PR_NUMBER" =~ ^[0-9]+$ ]] || { echo "Invalid PR_NUMBER"; exit 1; }
          [[ "$BASE_REF" =~ ^[a-zA-Z0-9/_.-]+$ ]] || { echo "Invalid BASE_REF"; exit 1; }
          echo "head-sha=$HEAD_SHA" >> "$GITHUB_OUTPUT"
          echo "head-ref=$HEAD_REF" >> "$GITHUB_OUTPUT"
          echo "pr-number=$PR_NUMBER" >> "$GITHUB_OUTPUT"
          echo "base-ref=$BASE_REF" >> "$GITHUB_OUTPUT"

      - name: Checkout sources
        uses: actions/checkout@v6
        with:
          ref: ${{ steps.pr-info.outputs.head-sha }}
          fetch-depth: 0
          persist-credentials: false

      - name: Download build output
        uses: actions/download-artifact@v4
        with:
          pattern: build-output-*
          merge-multiple: true
          run-id: ${{ github.event.workflow_run.id }}
          github-token: ${{ secrets.GITHUB_TOKEN }}

      # This step should NOT be replaced by a direct mvn verify call — that would run
      # fork-provided code in a workflow_run workflow, which has access to secrets.
      - name: Run Sonar analysis
        uses: SonarSource/sonarqube-scan-action@v7
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
        with:
          args: >
            -Dsonar.pullrequest.key=${{ steps.pr-info.outputs.pr-number }}
            -Dsonar.pullrequest.branch=${{ steps.pr-info.outputs.head-ref }}
            -Dsonar.pullrequest.base=${{ steps.pr-info.outputs.base-ref }}
            -Dsonar.pullrequest.provider=github
            -Dsonar.pullrequest.github.repository=${{ github.repository }}
            -Dsonar.scm.revision=${{ steps.pr-info.outputs.head-sha }}

      - name: Delete artifacts used in analysis
        if: always()
        uses: actions/github-script@v7
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          script: |
            const artifacts = await github.rest.actions.listWorkflowRunArtifacts({
              owner: context.repo.owner,
              repo: context.repo.repo,
              run_id: context.payload.workflow_run.id,
            });
            for (const artifact of artifacts.data.artifacts) {
              if (artifact.name.startsWith("build-output-") || artifact.name.startsWith("pr-info-")) {
                await github.rest.actions.deleteArtifact({
                  owner: context.repo.owner,
                  repo: context.repo.repo,
                  artifact_id: artifact.id,
                });
              }
            }

sonar.scm.revision is what makes the pull request check and decoration appear — without it, the analysis runs but SonarQube Cloud can't match it to the pull request.

Security considerations

• Pass any value that comes from the fork's pull request (branch names, ref names, the head SHA) through an env: block, never by interpolating it directly into a run: shell command.
• Validate extracted values (the head SHA, head branch, PR number, base ref) with a regex before using them in the checkout or scan steps.
• Don't quote the scan action's args: values that reference ${{ }} expressions. Quoting can change how the action parses individual arguments.
• Keep the analysis workflow's permissions as narrow as the steps above require, and never run fork-provided build commands (like mvn verify) directly in this workflow.

For a full working example, see this community thread and the referenced example repository workflow files.

Managing certificates for the SonarQube Cloud scan GitHub Action

If you use the sonarqube-scan-action for your GitHub Action and SonarQube Cloud is behind a secured proxy with certificates that need to be recognized by the GitHub runner, you’ll need to set the SONAR_ROOT_CERT environment variable in GitHub.

Troubleshooting

Scanner cannot resolve file paths in test coverage report

When using GitHub Action, the SonarScanner fails to resolve the paths within the test coverage report and raises the warning "Could not resolve <n> file paths in <file>".

You may resolve this problem by switching off relative_paths=True in the coverage settings.

"Container action is only supported on Linux" error

You may encounter this error if you use the SonarQube Scan GitHub Action before version 4, i.e. sonarcloud-github-action. This action is based on Docker and is only supported on Linux runners. In that case, move to sonarqube-scan-action (see Prerequisites).

"Container action is only supported on Linux" error

You may encounter this error if you use the SonarQube Scan GitHub Action before version 4, i.e. sonarcloud-github-action. This action is based on Docker and is only supported on Linux runners. In that case, move to sonarqube-scan-action (see Preqrequisites above).

"The job was not started because recent account payments have failed" error

You may encounter this GitHub error if your GitHub options are set to use a GitHub-hosted runner instead of your self-hosted runner. In this case, we recommend checking your GitHub options to ensure your self-hosted runner is selected.

"Failed to import SonarSource public key from all keyservers."

You may encounter this error if dirmngr is not installed in the runner. It is confirmed by those logs:

gpg: error running '/usr/bin/dirmngr': probably not installed
gpg: failed to start dirmngr '/usr/bin/dirmngr': Configuration error
gpg: can't connect to the dirmngr: Configuration error
gpg: keyserver receive failed: No dirmngr

Ensure that dirmngr is installed on the runner, or disable signature verification by setting skipSignatureVerification: true on your pipeline (not recommended).

Related pages

• Choosing your server region

To analyze CI failures and get automated fix suggestions directly in pull requests, see Gitar CI failure analysis, a separate Sonar product.

Related online courses

• Configuring code analysis for SonarQube Cloud with GitHub Actions
• Configuring pull request decoration for SonarQube Cloud with GitHub Actions