Start Free
SonarQube Community Build | DevOps platform integration | GitHub integration | Adding analysis to GitHub Actions workflow

Adding the SonarQube Community Build analysis to your GitHub Actions workflow

On this page

Configuring the project analysis parameters Configuring the build.yml file Failing the workflow when the quality gate fails Managing certificates for the SonarQube Community Build scan GitHub Action

Once you have created your project in SonarQube Community Build, you can add the SonarQube Community Build analysis to your GitHub Actions workflow:

  1. Configure the project analysis parameters.
  2. Add the analysis to your GitHub Actions workflows.
  3. Commit and push your code to start the analysis.

Configuring the project analysis parameters

For general information, see Analysis parameters and the respective SonarScanner section: Maven, Gradle, NET, CLI, and NPM. 

Specific to GitHub Actions is the setting of sonar.token and sonar.host.url: With GitHub Actions, you can configure these parameters through GitHub secrets. This may be done at the global level by the global System Administrator, or at the project level by the Project Administrator as explained below (It makes sense to store the server URL at the global level.).

In addition, starting from the Developer Edition, 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. 

Setting the Server URL and the token in GitHub secrets

The parameters used in GitHub Actions workflows to connect to the SonarQube Community Build (Server URL and token) should be securely stored in GitHub secrets: see GitHub's documentation on Encrypted secrets for more information. 

To store the authentication token at the project level:

  1. In the SonarQube Community Build UI, generate a SonarQube Community Build token for your project. 
  2. Create a repository secret in GitHub with:
    • Name: SONAR_TOKEN
    • Value: the token you generated in the previous step.

To store the SonarQube Community Build URL at the project level:

  • Create a repository secret in GitHub with:
    • Name: SONAR_HOST_URL
    • Value:  <sonarQubeServerURL>

Configuring the build.yml file

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

Set up your workflow according to your SonarQube Community Build edition:

  • SonarQube Community Build: The SonarQube Community Build 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.
  • SonarQube Community Build 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 Community Build quality gate Check Action, you can instruct the scanner to wait for the SonarQube Community Build 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 Community Build 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.

Configuring the analysis parameters for each project

For each project in the monorepo, set the analysis parameters: See Configuring the project analysis parameters above. Specific to the monorepo set up is the setting of the sonar.token property explained below.

You must create the Sonar tokens used to authenticate to the SonarQube Community Build during the analysis of the monorepo projects and store them securely in GitHub secrets. You can either use one single global-level token for the monorepo or a project-level token for each project in the monorepo. 

Proceed as follows:

  1. Generate the token(s) in SonarQube Community Build:
    • For project tokens, create a token for each project (you need the Administer permission on the project): Go to the Security page of your SonarQube Community Build account and create a Project analysis token.
    • For a global token, ask your administrator (The procedure is similar but you need the global Administer system permission.).
  2. In your GitHub repository, go to Settings > Secrets.
  3. Select New repository secret.
  4. In the Name field:
    • If you use a global token: enter SONAR_TOKEN.
    • Otherwise: enter SONAR_TOKEN_1 (or another unique identifier within the monorepo) for the token of your first project in the monorepo.
  5. In the Value field, enter the corresponding token value.
  6. Select Add secret.
  7. If you use project-level tokens, repeat steps 3 to 6 for each additional project in the monorepo.

Configuring the build.yml file

In the build.yml file of your monorepo:

  • Define the paths to the projects.
  • Add a job for each project in the monorepo. 

See the file example below.

name: Build

on:
  push:
    branches:
      - master # main branch name
    paths:
      - 'PROJECT1_PATH/**' # monorepo projects paths from the monorepo root directory
      - 'PROJECT2_PATH/**'
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  sonarQubeScan1:
    name: sonarQubeScan1
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v4
        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: SonarQube Scan 1
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN_1 }}  # analysis token associated to your project
          SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}
        run: |
            cd PROJECT1_PATH/
            mvn -B verify org.sonarsource.scanner.maven:sonar-maven-plugin:sonar -Dsonar.projectKey=SONAR_PROJECT1_KEY -Dsonar.projectName='SONAR_PROJECT1_NAME' 
        # Replace variables with project path, key and name
  sonarQubeScan2:
    name: sonarQubeScan2
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v4
        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: SonarQube Scan 2
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN_2 }} # analysis token associated to your project
          SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}
        run: run: |
            cd PROJECT2_PATH/
            mvn -B verify org.sonarsource.scanner.maven:sonar-maven-plugin:sonar -Dsonar.projectKey=SONAR_PROJECT2_KEY -Dsonar.projectName='SONAR_PROJECT2_NAME'
        # Replace variables with project path, key and name
  # Add other scan jobs if you wish to scan more projects in the monorepo   
name: Build

on:
  push:
    branches:
      - master # main branch name
    paths:
      - 'PROJECT1_PATH/**' # monorepo projects paths from the monorepo root directory
      - 'PROJECT2_PATH/**'
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  sonarQubeScan1:
    name: sonarQube Scan 1
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v4
        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: sonarQube Scan 1
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN_1 }}  # analysis token associated to your project
          SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}
        run: |
            cd PROJECT1_PATH/
            ./gradlew build sonar --info
        #Replace variable with the project path
  sonarQubeScan2:
    name: sonarQubeScan2
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v4
        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: sonarQube Scan 2
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN_2 }}  # analysis token associated to your project
          SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}
        run: |
            cd PROJECT2_PATH/
            ./gradlew build sonar --info
        #Replace variable with the project path
  # Add other scan jobs if you wish to scan more projects in the monorepo
name: Build

on:
  push:
    branches:
      - master # main branch name
    paths:
      - 'PROJECT1_PATH/**' # monorepo projects paths from the monorepo root directory
      - 'PROJECT2_PATH/**'
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  sonarQubeScan1:
    name: sonarQube Scan 1
    runs-on: windows-latest
    
    steps:
      - uses: actions/checkout@v4
        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 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: sonarQube Scan 1
        shell: powershell
        run: |
          .\.sonar\scanner\dotnet-sonarscanner begin /k:"SONAR_PROJECT1_KEY" /d:sonar.token="${{ secrets.SONAR_TOKEN_1 }}" /d:sonar.host.url="${{ secrets.SONAR_HOST_URL }}"
          dotnet build PROJECT1_PATH\SLN_FILE.SLN
          .\.sonar\scanner\dotnet-sonarscanner end /d:sonar.token="${{ secrets.SONAR_TOKEN_1 }}"
        # Replace variables with the project key and the path to the project solution file
  sonarQubeScan2:
    name: sonarQube Scan 2
    runs-on: windows-latest
    
    steps:
      - uses: actions/checkout@v4
        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 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: sonarQube Scan 2
        shell: powershell
        run: |
          .\.sonar\scanner\dotnet-sonarscanner begin /k:"SONAR_PROJECT2_KEY" /d:sonar.token="${{ secrets.SONAR_TOKEN_2 }}" /d:sonar.host.url="${{ secrets.SONAR_HOST_URL }}"
          dotnet build PROJECT2_PATH\SLN_FILE.SLN
          .\.sonar\scanner\dotnet-sonarscanner end /d:sonar.token="${{ secrets.SONAR_TOKEN_2 }}"
        # Replace variables with the project key and the path to the project solution file
  # Add other scan jobs if you wish to scan more projects in the monorepo   
name: Build

on:
  push:
    branches:
      - master # main branch name
    paths:
      - 'PROJECT1_PATH/**' # monorepo projects paths from the monorepo root directory
      - 'PROJECT2_PATH/**'
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  sonarQubeScan1:
    name: sonarQube Scan 1
    runs-on: ubuntu-latest
    env:
      BUILD_WRAPPER_OUT_DIR: build_wrapper_output_directory # Directory where build-wrapper output will be placed
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Shallow clones should be disabled for a better relevancy of analysis
      - name: Install sonar-scanner and build-wrapper
        env:
          SONAR_HOST_URL: ${{secrets.SONAR_HOST_URL}}
        uses: SonarSource/sonarqube-github-c-cpp@v1
      - name: Run build-wrapper for project 1
        run: |
          build-wrapper-linux-x86-64 --out-dir ${{ env.BUILD_WRAPPER_OUT_DIR }} <insert_your_clean_build_command_for_project1>
      - name: Run sonar-scanner for project 1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN_1 }}
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN_1 }}
          SONAR_HOST_URL: ${{secrets.SONAR_HOST_URL}}
        run: |
          sonar-scanner --define sonar.cfamily.compile-commands="${{ env.BUILD_WRAPPER_OUT_DIR }}/compile_commands.json" -Dsonar.projectBaseDir="PROJECT1_PATH/"
        #Replace variable with project path
  sonarQubeScan2:
    name: sonarQube Scan 2
    runs-on: ubuntu-latest
    env:
      BUILD_WRAPPER_OUT_DIR: build_wrapper_output_directory # Directory where build-wrapper output will be placed
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Shallow clones should be disabled for a better relevancy of analysis
      - name: Install sonar-scanner and build-wrapper
        env:
          SONAR_HOST_URL: ${{secrets.SONAR_HOST_URL}}
        uses: SonarSource/sonarqube-github-c-cpp@v1
      - name: Run build-wrapper for project 2
        run: |
          build-wrapper-linux-x86-64 --out-dir ${{ env.BUILD_WRAPPER_OUT_DIR }} <insert_your_clean_build_command_for_project2>
      - name: Run sonar-scanner for project 2
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN_2 }}
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN_2 }}
          SONAR_HOST_URL: ${{secrets.SONAR_HOST_URL}}
        run: |
          sonar-scanner --define sonar.cfamily.build-wrapper-output="${{ env.BUILD_WRAPPER_OUT_DIR }}" -Dsonar.projectBaseDir="PROJECT2_PATH/"4
        #Replace variable with project path
  # Add other scan jobs if you wish to scan more projects in the monorepo   
name: Build

on:
  push:
    branches:
      - master # main branch name
    paths:
      - 'PROJECT1_PATH/**' # monorepo projects paths from the monorepo root directory
      - 'PROJECT2_PATH/**'
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  sonarQubeScan1:
    name: sonarQubeScan1
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Shallow clones should be disabled for a better relevancy of analysis
      - name: SonarQube Scan 1
        uses: sonarsource/sonarqube-scan-action@master
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN_1 }}  # analysis token associated to your project
          SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}
        with:
          projectBaseDir: PROJECT1_PATH/ # the path to your project from the monorepo root directory
      # If you wish to fail your job when the Quality Gate is red, uncomment the
      # following lines. This would typically be used to fail a deployment.
      # We do not recommend to use this in a pull request. Prefer using pull request
      # decoration instead.
      # - uses: sonarsource/sonarqube-quality-gate-action@master
      #   timeout-minutes: 5
      #   env:
      #     SONAR_TOKEN: ${{ secrets.SONAR_TOKEN_1 }}
  sonarQubeScan2:
    name: sonarQubeScan2
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Shallow clones should be disabled for a better relevancy of analysis
      - name: SonarQube Scan 2
        uses: sonarsource/sonarqube-scan-action@master
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN_2 }}  # analysis token associated to your project
          SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}
        with:
          projectBaseDir: PROJECT2_PATH/ # project path from the monorepo root directory
      # If you wish to fail your job when the Quality Gate is red, uncomment the
      # following lines. This would typically be used to fail a deployment.
      # We do not recommend to use this in a pull request. Prefer using pull request
      # decoration instead.
      # - uses: sonarsource/sonarqube-quality-gate-action@master
      #   timeout-minutes: 5
      #   env:
      #     SONAR_TOKEN: ${{ secrets.SONAR_TOKEN_2 }}

  # Add other scan jobs if you wish to scan more projects in the monorepo

Managing certificates for the SonarQube Community Build scan GitHub Action

If you use the sonarqube-scan-action for your GitHub Action and your SonarQube Community Build has root certificates that need to be recognized by the GitHub runner, you'll need to set the SONAR_ROOT_CERT environment variable in GitHub (See Managing the TLS certificates on the client side).

Was this page helpful?

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

Creative Commons License