Skip to content
Tutorials Center
My learning

Topics

Lesson 30 of 37 ยท CI Integration

Pull Request Analysis, Decoration and Quality Gate Wait

How SonarQube analyses pull requests, which parameters identify them, how decoration reports status to GitHub or GitLab, and how to enforce the quality gate before merging.

The cheapest time to fix an issue is before it is merged. Pull request analysis runs the scanner on the changes in a PR, compares them with the target branch, and reports only what the PR introduces. With decoration, the result shows up inside the PR as a status check and inline comments, so reviewers never have to open SonarQube.

This lesson explains the parameters, the editions, and the enforcement setup. The product cannot run on this site, so the examples are configuration to copy and the TryIts simulate the decisions.

Edition note

Branch and pull request analysis are features of Developer Edition and above (and SonarQube Cloud). The free Community Build analyses a single branch only, which is why many teams on it run the scanner on the main branch after merge. Check which edition you run before planning a PR workflow.

What the scanner needs to know

For a pull request the scanner has to learn three facts:

Parameter Meaning
sonar.pullrequest.key The PR number or identifier
sonar.pullrequest.branch The source (feature) branch name
sonar.pullrequest.base The target branch, such as main

The official GitHub Action, the Azure DevOps and Jenkins integrations and the GitLab setup detect these from their environment variables automatically. When you call the scanner by hand in another system, pass them with -D, for example:

Terminal
sonar-scanner \
  -Dsonar.pullrequest.key=482 \
  -Dsonar.pullrequest.branch=feature/cart-totals \
  -Dsonar.pullrequest.base=main

The server keeps each PR as a separate "branch-like" entity under the project, with its own issues, coverage and gate result, and deletes inactive ones after a configured number of days (Administration > General Settings > Housekeeping).

What counts as new in a PR

In a PR the new code is the set of changed lines compared with the target branch. So:

  • new_coverage covers only the lines the PR touches.
  • new_violations are issues on those lines.
  • new_security_hotspots_reviewed considers hotspots the PR introduces.

This is the Clean as You Code idea applied at the smallest unit. A PR that edits one line of a messy file is judged on that line.

Decoration and ALM binding

For the results to reach the pull request, an administrator links the project to the code host:

  1. Administration > Configuration > DevOps Platform Integrations: add a GitHub, GitLab, Bitbucket or Azure DevOps configuration. For GitHub that usually means a GitHub App with permissions to read code and write checks and pull request comments.
  2. In each project, Project Settings > General Settings > DevOps Platform Integration, choose the configuration and enter the repository identifier.
  3. Provide a token to the scanner as before.

After analysis the host shows a status check named after SonarQube, with a link to the dashboard, and in several integrations a summary comment listing new issues, coverage and duplications. Inline comments on the changed lines depend on the platform.

Enforcing the gate

A red status is only a hint until the host refuses to merge:

  • GitHub: mark the SonarQube check as required in the branch protection rule or ruleset.
  • GitLab: enable "Pipelines must succeed" and make the Sonar job fail with sonar.qualitygate.wait=true.
  • Azure DevOps: add a build validation policy for the target branch, and let SonarQubePublish fail the build.
  • Bitbucket: use merge checks with the build status.
flowchart LR
  A["Open pull request"] --> B["CI: build, test, scan"]
  B --> C["Server computes gate on changed lines"]
  C -- "OK" --> D["Check passes, merge allowed"]
  C -- "ERROR" --> E["Check fails, merge blocked"]
  E --> F["Developer fixes and pushes"]
  F --> B

Figure: the loop repeats until the gate on changed lines is green.

Stand-in: evaluate a PR against gate conditions

This block takes the measures of a PR and a list of gate conditions with an operator and threshold, evaluates them and prints a status like the check on a pull request. The condition list resembles the built-in Sonar way gate on new code; verify the current conditions on your server.

JS Stand-in: pull request gate evaluator

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

No output.

Stand-in: which lines are new?

A PR gate depends on correctly knowing which lines changed. The simplified diff parser below reads unified-diff hunk headers (@@ -a,b +c,d @@) and returns the added line ranges, the same idea the server uses to scope new code. Real diffs are computed by git, so this is only a model.

JS Stand-in: changed lines from hunk headers

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

No output.

The third hunk only deletes lines (new count 0), so it adds none.

Troubleshooting

  • No PR appears on the server. The scanner did not get PR parameters, or the edition does not support PRs.
  • Check passes but no comments. The ALM binding or token lacks permission to write comments or checks.
  • Gate fails on code you did not touch. Ensure the target branch has been analysed and the full history was fetched; otherwise SonarQube cannot compute the changed lines correctly.
  • Coverage on new code missing. Coverage reports from the PR build must be imported like for any analysis; a new file without tests shows 0%.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which edition level adds pull request analysis?

    Branch and PR analysis start at Developer Edition (and SonarQube Cloud).
  2. 2. What is new code in a pull request analysis?

    The PR is judged on the lines it adds or changes.
  3. 3. How can the gate actually block a merge?

    Branch protection or policies on the code host enforce the status.
  4. 4. Which parameter names the target branch for a PR analysis?

    sonar.pullrequest.base carries the target branch; key is the PR id and branch is the source branch.

Summary

  • PR analysis needs Developer Edition or above and the PR key, branch and base parameters (often automatic).
  • Only changed lines count as new, so legacy code does not block small PRs.
  • ALM binding adds decoration; branch protection or build policies enforce the gate.
  • Always fetch full history and analyse the target branch first.

Next: Users, groups and permissions