Branches, Pull Requests, Merge Requests, and Edition-Aware Analysis: Core Concepts and Mental Model

1. The practical problem: the same files can mean different analyses

In Chapters 12–16 you learned that SonarQube results are meaningful only when you know the exact source revision, effective inputs, policy, and asynchronous task. Branches and pull requests add another identity layer. Two scanner runs can read almost the same files yet answer different questions because one is the project’s main branch, another is a long-lived commercial branch, and another is a pull request whose target branch defines the comparison population.

The common mistake is to look only at the current working tree and assume that SonarQube can infer every relationship from it. It cannot. Reliable branch/PR analysis depends on valid SCM metadata, enough history to find the common commit, correct branch or pull-request identity, a supported edition, and—when decoration is wanted—a correctly bound DevOps provider.

2. Edition boundary first

This distinction matters because a scanner invoked from a Git feature branch against Community Build does not magically create a branch object. Passing commercial multi-branch properties to an edition that does not support them is not a free branch-analysis technique. The mandatory labs therefore use Community Build for executable learning and simulate the commercial identity contract honestly.

3. Mental model: identity before metrics

flowchart TD
  A[Checkout: SHA + full-enough Git history] --> B[Scanner identity]
  P[PR key + source branch + target branch] --> B
  E[Edition + project key] --> B
  B --> C[Comparison target / reference]
  C --> D[New Code files + issues + measures]
  D --> F[Analysis report upload]
  F --> G[Compute Engine task]
  G --> H[Quality Gate]
  H --> I[CI result / provider decoration]

Every arrow represents a dependency. If the target branch is wrong, the New Code population is wrong. If Git history is shallow, SonarQube may not find the common commit or blame information. If the project is Community Build, commercial branch/PR parameters do not create licensed capability. If the Quality Gate is green but provider decoration is absent, the analysis may be fine while provider binding/permissions are wrong.

4. Three analysis modes that must not be collapsed

GitLab calls the object a merge request; Sonar’s PR-analysis model treats it equivalently. A PR analysis uses the project Quality Gate, but only conditions on New Code metrics are evaluated for the pull request.

5. Scanner identity parameters

When manual parameters are required, current SonarQube Server documentation defines:

# Developer+ branch analysis
sonar.branch.name=feature/payments

# Developer+ pull/merge request analysis
sonar.pullrequest.key=42
sonar.pullrequest.branch=feature/payments
sonar.pullrequest.base=main

sonar.pullrequest.key is the provider’s PR/MR identifier, sonar.pullrequest.branch is the source branch containing the changes, and sonar.pullrequest.base is the target branch. Supported CI systems can auto-detect these values; manually supplied values override auto-detection. Do not combine branch-analysis identity with pull-request identity in one run.

6. PR New Code is a comparison, not a date window

For pull requests, New Code is the code changed in the pull-request branch compared with the target branch. Only issues on that New Code are reported in the PR analysis. This is why target identity and SCM history are central. Sonar must have enough history to determine the common commit; the target branch should be analyzed first to produce useful PR results.

7. SCM history: fetch-depth: 0 is evidence infrastructure

SonarSource recommends a full Git clone. In PR analysis, all commits on the source branch that are not on the target can participate in identifying New Code; enough history is needed to find their common commit. Full history also supports blame, automatic issue assignment, and issue backdating. A shallow clone can cause blame retrieval to be skipped and analysis may fail.

git rev-parse HEAD
git rev-parse --is-shallow-repository
git branch --show-current
git log --oneline --decorate --graph --all -12
git merge-base HEAD origin/main

# Common CI pattern:
# GitHub Actions checkout: fetch-depth: 0

8. Provider decoration is a separate state

Developer+ can report analysis and Quality Gate status into supported GitHub, GitLab, Bitbucket, and Azure DevOps pull/merge requests when the SonarQube project is correctly integrated/bound to the repository. Provider decoration can fail even after scanner upload, Compute Engine processing, and gate calculation succeed.

9. Read-only inspection before analysis

git rev-parse HEAD
git branch --show-current
git rev-parse --is-shallow-repository
git remote -v
git log --oneline --decorate --graph --all -12

# For a feature branch whose target is main:
git merge-base HEAD main
git diff --name-status main...HEAD
git rev-list --left-right --count main...HEAD

sonar-scanner --version
curl -fsS "$SONAR_HOST_URL/api/system/status"

Record those values before altering CI checkout depth or scanner identity. A useful incident report begins with what was actually checked out—not what the pipeline author expected to be checked out.

Knowledge check

Official references and version notes

• SonarQube downloads / edition matrix — Community Build 26.9.0.129388; Server 2026 Release 4.1; 2026.1.5 LTA; branch and pull-request analysis plus PR decoration start in Developer Edition.
• Branch analysis introduction — retained branch state, New Code and Quality Gate behavior.
• Setting up branch analysis — branch-name identity, CI integration and branch-level New Code guidance.
• Pull request analysis introduction — changed code relative to the target, New Code-only gate conditions, and provider decoration boundary.
• Setting up pull request analysis — CI prerequisite and sonar.pullrequest.key/branch/base parameters.
• Checked-out code — full Git history, target refs, merge-base relevance and fetch-depth: 0.
• Quality standards and New Code — PR New Code is the code changed relative to the target branch.
• GitHub integration — CI auto-detection and PR quality-gate reporting; Chapter 18 expands provider setup.
• SonarScanner CLI 8.1.0.6389 — scanner baseline used by the mandatory lab.