Analyze your repository with GitHub Actions

To configure an analysis of your project using GitHub Actions, you should follow the in-product tutorial when creating a new project. When it's time to Choose your Analysis Method during setup, simply 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.
2. Set the essential analysis parameters, sonar.projectKey, sonar.organization, and sonar.host.url. The tutorial will be populated with the correct values for your specific account. These 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 (See Analysis Parameters).
3. Create the .github/workflows/build.yml 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. This is done differently depending on your project type:
   • A Maven plugin for Java Maven projects.
   • A Gradle plugin for Java Gradle projects.
   • A dedicated .NET scanner for .NET projects.
   • The SonarQube Cloud GitHub Action for other projects. The tutorial will provide the specific details for your project type.

The example below shows how you could set up a yml file for a single project.

GitHub Actions for SonarQube Cloud

 The workflow, usually declared in .github/workflows/build.yml, looks something like this:

name: My Test Single Project
on:
  push:
    branches:
      - main
  pull_request:
    types: [opened, synchronize, reopened]
jobs:
  sonarqube:
    name: SonarQube
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0  
      - name: SonarQubeScan
        uses: SonarSource/sonarqube-scan-action@v4
        env: 
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}

Users have reported that when working with GitHub Actions reusable workflows, your SONAR_TOKEN is not intrinsically passed to the reusable workflow. Even though your SONAR_TOKEN is defined in the source repository, GitHub Actions will output the SONAR_TOKEN value with asterisks (which make it look like it is working as expected), when in fact it is not reusing the value.  

When setting up your GitHub reusable workflow, we recommend using the GitHub feature secret: inherit to completely remove the intrinsic sending of your SONAR_TOKEN.

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

Failing the workflow when the quality gate fails

SonarQube Cloud adds the quality gate status as a GitHub check. You can set up your workflow to fail when the GitHub check is marked as failed.

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@v3
        with:
          fetch-depth: 0  
      - name: SonarQube Scan
        uses: SonarSource/sonarqube-scan-action@v4
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
        with:
          projectBaseDir: repo1/
          
  sonarqubeScan2:
    name: SonarQubeScan2
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0  
      - name: SonarQube Scan
        uses: SonarSource/sonarqube-scan-action@v4
        env: 
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
        with:
          projectBaseDir: repo2/

Use of Docker in the SonarQube Scan GitHub Action

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

v4 removes the Docker dependency, making the action composite. The action now runs in the environment of the runner executing the GitHub workflow. 

• If your runner is GitHub-hosted, all required utilities should be already provided by default. 
• If your runner is self-hosted, before moving to v4, you would need to ensure that the following utilities are installed and available in the PATH: unzip, wget or curl, and node (v20 or above - only required when analyzing JS code against SonarQube 10.2 or below).

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 of a secured proxy with a 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.