How to Add SonarQube PR Checks to GitHub Actions

October 30, 2026

You add SonarQube to GitHub Actions by running the official SonarSource/sonarqube-scan-action step after your tests, passing SONAR_TOKEN from repo secrets. The scan then posts a check on the pull request — but only if your SonarQube instance is Developer Edition or above.

That last clause is where most teams stall. Community Build accepts the scan, stores the results, and never decorates the PR.

What does the workflow look like?

A working JavaScript version, trimmed:

name: sonar
on: [pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - run: npm ci
      - run: npm test -- --coverage
      - uses: SonarSource/sonarqube-scan-action@v4
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
          SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}

fetch-depth: 0 is mandatory. Without full history SonarQube cannot determine which lines are new, and every issue gets blamed on the PR author. That single line causes more “why is everything new” tickets than any other setting.

Why does coverage show as 0%?

Because SonarQube does not run tests. It reads coverage reports. If your jest run does not emit lcov.info, SonarQube has nothing to import and reports zero.

Set it in sonar-project.properties:

sonar.javascript.lcov.reportPaths=coverage/lcov.info
sonar.coverage.exclusions=**/*.test.ts,**/migrations/**

For Python + pytest, use pytest --cov --cov-report=xml and point sonar.python.coverage.reportPaths at coverage.xml. For Java, JaCoCo’s XML report; the binary .exec file is not read.

Exclusions matter as much as paths. Generated code, migrations and test files in the coverage denominator drag every project below the gate. Exclude them explicitly.

How do you stop the scan from taking 8 minutes?

Cache the analysis. Two levers:

  • sonar.cpd.exclusions for vendored and generated directories — duplication detection is the slowest analyser.
  • Runner cache on ~/.sonar/cache with a key tied to the scanner version.

In practice, a 60k-line TypeScript monorepo drops from around 7 minutes cold to 2-3 minutes warm. The cache step is 8 lines of YAML and worth it on every PR.

Also scope the scan. Running the full project on every PR when only three packages changed wastes runners. Use sonar.inclusions per package job, or scan only changed modules in a matrix.

Should you fail the build on the gate?

Yes, eventually. Not on day one.

Start in report-only mode: run the scan, post results, do not block. Let the team fix the backlog of new-code issues for two or three sprints. Then flip on sonar.qualitygate.wait=true, which makes the step exit non-zero when the gate fails.

Turning it on immediately produces a wall of red checks and a team that learns to click “merge anyway”, which is worse than no gate.

What about self-hosted vs SonarCloud?

Self-hosted SonarQube gives you full control and no per-line pricing, at the cost of a server, upgrades and backups. SonarCloud skips the operations and starts free for public repos.

For a private repo with PR checks, SonarCloud’s paid tiers are roughly $10-30/month per developer depending on lines analysed. Compare that against a $40/month VM plus your own maintenance time — for fewer than five developers, hosted usually wins.

One caveat: SonarCloud means source code leaves your network. If that is a compliance problem, self-hosting is not optional.

Where this setup is fragile

  • Forked PRs cannot read repo secrets. External contributors get a scan that fails on auth, not a useful check. Use pull_request_target carefully, or skip the scan for forks.
  • Monorepos with 20 packages in one GitHub Actions job will time out at 6 hours eventually. Split.
  • sonar-scanner version drift breaks the cache key silently, so pin the action major version.

Key Takeaways

  • Run SonarSource/sonarqube-scan-action after tests with fetch-depth: 0 — required for new-code detection.
  • SonarQube imports coverage; it never runs tests. Point it at lcov.info or coverage.xml.
  • Cache ~/.sonar/cache and set CPD exclusions to cut scan time roughly in half.
  • Enable sonar.qualitygate.wait=true only after the team has cleared the initial backlog.
  • PR decoration needs Developer Edition; Community Build stores results but posts no comment.