Skip to content
Tutorials Center
My learning

Topics

Lesson 28 of 37 ยท CI Integration

SonarQube with GitHub Actions: Workflow Files Explained

Set up SonarQube analysis in GitHub Actions: secrets, a workflow for push and pull requests, Maven, Gradle and .NET variants, the quality gate check, and a workflow linter stand-in.

GitHub Actions is the most common place to run SonarQube analysis. You need three things: a project on the server, two repository secrets, and a workflow file. SonarQube supports a GitHub integration (an ALM binding) so results also appear on pull requests; that part is covered in Pull request analysis.

The server and the Actions runners cannot run on this site. The YAML below is real configuration to copy into your own repository; the TryIt is a stand-in that checks a workflow's structure.

Step 1: create the project and a token

  1. In SonarQube choose Projects > Create project and select GitHub (or "Manually" if no binding exists). Note the project key.
  2. Open My Account > Security (or the project's analysis setup page) and generate a token. A project analysis token is limited to one project and is safer than a user token.
  3. In GitHub open Settings > Secrets and variables > Actions of the repository and add:
    • SONAR_TOKEN: the token.
    • SONAR_HOST_URL: for example https://sonar.example.com. (This one can be a repository variable, since it is not secret.)

Step 2: a workflow for a JavaScript or generic project

Create .github/workflows/sonar.yml:

YAML
name: SonarQube
on:
  push:
    branches: [main]
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  sonarqube:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci
      - run: npm test -- --coverage
      - uses: SonarSource/sonarqube-scan-action@v5
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
          SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}
      - uses: SonarSource/sonarqube-quality-gate-action@v1
        timeout-minutes: 5
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}

Points to notice:

  • fetch-depth: 0 fetches the full history, which is needed for blame and new code.
  • The scan action reads sonar-project.properties in the repository root. Pin the action to a current major version; the version numbers above are examples and change over time, so check the action's page on the GitHub Marketplace.
  • The quality gate action polls the server for the gate result of the scan that just ran and fails the job if the gate is ERROR. Alternatively set -Dsonar.qualitygate.wait=true through the scan action's args and skip this step.
  • Pull requests from forks do not receive secrets, so analysis of fork PRs fails by default. Either analyse them on a trusted workflow after review or skip the step for forks.

Maven variant

YAML
      - uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: 21
      - name: Build, test, analyse
        run: >
          mvn -B verify
          org.sonarsource.scanner.maven:sonar-maven-plugin:sonar
          -Dsonar.projectKey=shop-api
          -Dsonar.qualitygate.wait=true
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
          SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}

verify runs the tests (with JaCoCo bound in the POM) before the sonar goal reads the report.

Gradle variant

Apply the org.sonarqube plugin in build.gradle.kts, set sonar { properties { property("sonar.projectKey", "shop-api") } }, and run:

Terminal
./gradlew build jacocoTestReport sonar -Dsonar.qualitygate.wait=true

with the same two environment variables.

.NET variant

.NET uses a begin/build/end sequence, because the scanner hooks into the build:

YAML
      - run: dotnet tool install --global dotnet-sonarscanner
      - run: dotnet sonarscanner begin /k:"shop-api" /d:sonar.host.url="${{ secrets.SONAR_HOST_URL }}" /d:sonar.token="${{ secrets.SONAR_TOKEN }}" /d:sonar.cs.opencover.reportsPaths="**/coverage.opencover.xml"
      - run: dotnet build --no-incremental
      - run: dotnet test --collect:"XPlat Code Coverage;Format=opencover"
      - run: dotnet sonarscanner end /d:sonar.token="${{ secrets.SONAR_TOKEN }}"

The end step is where the report is uploaded; skipping it means nothing is analysed.

Common errors

Symptom Likely cause
Not authorized Wrong or missing SONAR_TOKEN, or a token without Execute Analysis permission
Unable to execute SonarScanner analysis with a connection error SONAR_HOST_URL unreachable from the runner (firewall, wrong URL)
"Shallow clone detected" warnings Missing fetch-depth: 0
Coverage 0% Tests ran after the scan or the report path is wrong
Secret is empty on a PR The PR comes from a fork
Project key already exists / mismatch sonar.projectKey differs from the project on the server

A self-hosted server must be reachable from GitHub's runners. If it is behind a VPN, use a self-hosted runner inside the network, or SonarQube Cloud.

Stand-in: lint a workflow for the usual mistakes

The block below receives a simplified description of a workflow (a list of steps) and checks the rules that cause most failures: checkout depth, token availability, test-before-scan order and a gate check. This is a teaching linter, not an official tool.

JS Stand-in: workflow checklist

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Branch protection

To make the gate binding, add the SonarQube status check as required in Settings > Branches > Branch protection rules (or rulesets) of the GitHub repository, once the integration reports status on pull requests. Without that, a failing gate is only advice.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why is fetch-depth: 0 set on the checkout step?

    A shallow clone breaks blame information and the detection of new code.
  2. 2. Where should SONAR_TOKEN be stored in GitHub?

    Secrets are encrypted and exposed to workflows as environment variables.
  3. 3. In the .NET flow, what does the end step do?

    dotnet sonarscanner end collects the data gathered during the build and sends it to the server.
  4. 4. Why might analysis fail on a pull request from a fork?

    Secrets are withheld from fork PR workflows by default, so the token is empty.

Summary

  • Add SONAR_TOKEN and SONAR_HOST_URL as Actions secrets, then run the scan action after tests.
  • Use fetch-depth: 0 and a quality gate step (or sonar.qualitygate.wait=true).
  • Maven and Gradle call the sonar goal; .NET needs begin, build, end.
  • Require the status check in branch protection to enforce the gate.

Next: GitLab, Jenkins and Azure DevOps