This version of the SonarQube documentation is no longer maintained. It relates to a version of SonarQube that is not active.

See latest version
Start Free
10.5 | DevOps platform integration | GitHub integration | Adding analysis to GitHub Actions workflow

Adding the SonarQube analysis to your GitHub Actions workflow

On this page

Creating your GitHub secrets Configuring your .github/workflows/build.yml file Failing the workflow when the quality gate fails Preventing pull request merges when the quality gate fails

SonarScanners running in GitHub Actions can automatically detect branches and pull requests being built so you don't need to specifically pass them as parameters to the scanner.

To analyze your projects with GitHub Actions, you need to:

  1. Create your GitHub Secrets.
  2. Configure your workflow YAML file.
  3. Commit and push your code to start the analysis.

Creating your GitHub secrets

You can create repository secrets from your GitHub repository. See GitHub's documentation on Encrypted secrets for more information.

You need to set the following GitHub repository secrets to analyze your projects with GitHub Actions:

  • Sonar Token: Generate a SonarQube token and, in GitHub, create a new repository secret in GitHub with SONAR_TOKEN as the Name and the token you generated as the Value.
  • Sonar Host URL: In GitHub, create a new repository secret with SONAR_HOST_URL as the Name and your SonarQube server URL as the Value.

Configuring your .github/workflows/build.yml file

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

You'll set up your build according to your SonarQube edition:

  • Community Edition: Community Edition doesn't support multiple branches, so you should only analyze your main branch. You can restrict analysis to your main branch by setting it as the only branch in your on.push.branches configuration in your workflow YAML file, and not using on.pull_request.
  • Developer Edition and above: 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.

Click the scanner you're using below to expand the example configuration:

SonarScanner for Gradle

Note: A project key might have to be provided through a build.gradle file, or through the command line parameter. For more information, see the SonarScanner for Gradle documentation.

Add the following to your build.gradle file:

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

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@v2
        with:
          fetch-depth: 0  # Shallow clones should be disabled for a better relevancy of analysis
      - name: Set up JDK 17
        uses: actions/setup-java@v1
        with:
          java-version: 17
      - name: Cache SonarQube packages
        uses: actions/cache@v1
        with:
          path: ~/.sonar/cache
          key: ${{ runner.os }}-sonar
          restore-keys: ${{ runner.os }}-sonar
      - name: Cache Gradle packages
        uses: actions/cache@v1
        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 }}
          SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}
        run: ./gradlew build sonar --info
SonarScanner for Maven

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

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@v2
        with:
          fetch-depth: 0  # Shallow clones should be disabled for a better relevancy of analysis
      - name: Set up JDK 17
        uses: actions/setup-java@v1
        with:
          java-version: 17
      - name: Cache SonarQube packages
        uses: actions/cache@v1
        with:
          path: ~/.sonar/cache
          key: ${{ runner.os }}-sonar
          restore-keys: ${{ runner.os }}-sonar
      - name: Cache Maven packages
        uses: actions/cache@v1
        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 }}
          SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}
        run: mvn -B verify org.sonarsource.scanner.maven:sonar-maven-plugin:sonar
SonarScanner for .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 17
        uses: actions/setup-java@v1
        with:
          java-version: 1.17
      - uses: actions/checkout@v2
        with:
          fetch-depth: 0  # Shallow clones should be disabled for a better relevancy of analysis
      - name: Cache SonarQube packages
        uses: actions/cache@v1
        with:
          path: ~\.sonar\cache
          key: ${{ runner.os }}-sonar
          restore-keys: ${{ runner.os }}-sonar
      - name: Cache SonarQube scanner
        id: cache-sonar-scanner
        uses: actions/cache@v1
        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: powershell
        run: |
          New-Item -Path .\.sonar\scanner -ItemType Directory
          dotnet tool update dotnet-sonarscanner --tool-path .\.sonar\scanner
      - name: Build and analyze
        shell: powershell
        run: |
          .\.sonar\scanner\dotnet-sonarscanner begin /k:"example" /d:sonar.token="${{ secrets.SONAR_TOKEN }}" /d:sonar.host.url="${{ secrets.SONAR_HOST_URL }}"
          dotnet build
          .\.sonar\scanner\dotnet-sonarscanner end /d:sonar.token="${{ secrets.SONAR_TOKEN }}"
SonarScanner CLI


You can easily set up a basic configuration using the SonarQube Scan GitHub Actions:

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

Failing the workflow when the quality gate fails

You can use the SonarQube quality gate check GitHub Action to ensure your code meets your quality standards by failing your workflow when your Quality gate fails.

If you do not want to use the SonarQube quality gate Check Action, you can instruct the scanner to wait for the SonarQube quality gate status at the end of the analysis. To enable this, pass the -Dsonar.qualitygate.wait=true parameter to the scanner in the workflow YAML file.

This will make the analysis step poll SonarQube regularly until the quality gate is computed. This will increase your workflow duration. Note that, if the quality gate is red, this will make the analysis step fail, even if the actual analysis itself is successful. We advise only using this parameter when necessary (for example, to block a deployment workflow if the quality gate is red). It should not be used to report the quality gate status in a pull request, as this is already done with pull request decoration.

You can set the sonar.qualitygate.timeout property to an amount of time (in seconds) that the scanner should wait for a report to be processed. The default is 300 seconds.

Preventing pull request merges when the quality gate fails

In GitHub, you can block pull requests from being merged if it is failing the quality gate. To do this:

  1. In GitHub, go to your repository Settings > Branches > Branch protection rules and select either the Add rule or Edit button if you already have a rule on the branch you wish to protect.
  2. Complete the Branch protection rule form:
    • Define the Branch name pattern (the name of the branch you wish to protect)
    • Select Require status checks to pass before merging to open supplementary form fields.
    • In the Search for status checks in the last week for this repository field, select Require branches to be up to date before merging, then find SonarQube Code Analysis and add it to the list of required checks.
Define the 'SonarQube Code` value as the status check to perform before permitting a PR merge.

Was this page helpful?

© 2008-2024 SonarSource SA. All rights reserved. SONAR, SONARSOURCE, SONARLINT, SONARQUBE, SONARCLOUD, and CLEAN AS YOU CODE are trademarks of SonarSource SA.

Creative Commons License