Branches, Pull Requests, Merge Requests, and Edition-Aware Analysis: Configuration, Design Patterns, and Trade-Offs
Choose deliberately among main-branch, long-lived branch, and pull/merge-request analysis; CI auto-detection versus explicit parameters; and full-history versus shallow checkouts.
Learning objectives
- Choose main-branch, branch, or pull/merge-request analysis based on the engineering question.
- Choose CI auto-detection versus explicit scanner parameters without creating hidden precedence surprises.
- Explain why full-enough SCM history is a functional dependency, not a performance luxury.
- Design a Community Build fallback that teaches identity honestly without faking commercial features.
- Connect provider decoration, merge protection, least privilege, and auditability to the correct owning system.
1. Choose analysis mode from the decision you need to make
| Engineering decision | Best Sonar mode | Why |
|---|---|---|
| Is the deployable main line healthy? | Main-branch analysis | It preserves the project’s canonical history and configured New Code baseline. |
| Is a maintenance/release branch healthy before deployment? | Branch analysis (Developer+) | The branch gets first-class retained state and can use branch-level New Code configuration. |
| Should this proposed change merge? | PR/MR analysis (Developer+) | It evaluates changed code against the target and integrates naturally with merge policy. |
| Do I only have Community Build? | Main analysis + SCM/parameter simulation | Teaches the evidence contract without misrepresenting license capability. |
2. CI auto-detection versus manual parameters
On supported CI services, scanners can automatically obtain branch/PR metadata. This reduces duplicated pipeline configuration and lowers the chance that a user copies the wrong PR key. Manual parameters remain valuable for unusual runners and debugging, but they must be treated as high-authority inputs because they override auto-detection.
Prefer auto-detection
Standard GitHub Actions, GitLab CI/CD, Azure Pipelines, Bitbucket Pipelines, or supported Jenkins branch-source workflows where provider metadata is trustworthy.
Prefer explicit parameters
Custom CI runners or controlled diagnostics where you can prove the PR key/source/target independently.
Do not mix casually
A manually wrong sonar.pullrequest.base can
override correct provider metadata and change the analysis
question.
3. Shallow versus full-enough SCM history
Shallow checkouts save network time but remove exactly the history
branch/PR analysis needs. SonarSource recommends full depth and all
relevant branches; with GitHub Actions this commonly means
fetch-depth: 0. The operational trade-off is bandwidth
versus deterministic blame/merge-base/New Code evidence. In most CI
systems, restore history rather than disabling SCM features.
sonar.scm.disabled=true. That suppresses the evidence
dependency instead of restoring it.
4. Branch New Code versus PR New Code
Long-lived branch analysis can use the normal New Code definition framework—Previous version, Number of days, Specific analysis, or Reference branch as supported by configuration level. PR/MR analysis instead defines New Code from the source branch’s changes relative to its target branch. That target comparison is intrinsic to the PR object and should not be replaced with the project’s general date/version baseline.
5. Stable project key versus branch identity
In Developer+ the same SonarQube project key owns its main branch, analyzed branches, and PRs. Branch/PR identity is additional state. Creating a new project key for every commercial branch defeats the model: you lose shared policy context, synchronization, branch navigation, and correct comparison semantics.
The Chapter 17 Community Build fallback uses separate project keys only because the edition cannot store branch state, and the lessons repeatedly label that choice as a simulation—not a production branch strategy.
6. Advisory dashboard versus enforced provider check
SonarQube can calculate a gate without the DevOps provider blocking a merge. Merge enforcement is owned jointly: SonarQube calculates the analysis/gate; the provider receives a status/check/comment/annotation; repository branch/ruleset policy decides whether that status is required.
| State | Owner | Evidence |
|---|---|---|
| PR analysis result | SonarQube | PR key, analysis ID, measures/issues |
| Quality Gate | SonarQube | Gate status + conditions |
| Decoration delivery | SonarQube integration + provider API | Status/check/comment/annotation |
| Merge blocked | GitHub/GitLab/Bitbucket/Azure policy | Required status/branch protection policy |
7. Provider and edition design boundary
Current Developer Edition includes branch/PR analysis and pull-request quality-gate decoration for GitHub, GitLab, Bitbucket, and Azure DevOps. Enterprise adds broader scale/governance capabilities, including unlimited DevOps-platform integrations in current product packaging. Chapter 18 will configure those providers in depth; this chapter only teaches the identity and result boundary.
8. Worked scenario
A repository has main, release/2.x, and
short-lived feature branches. The organization has Developer Edition
and GitHub Actions.
| Flow | Recommended mode | SCM/parameter evidence |
|---|---|---|
Push to main |
Main analysis | Exact SHA; full checkout; no explicit branch property needed when aligned. |
Push to release/2.x |
Branch analysis |
Exact SHA; sonar.branch.name=release/2.x or
trusted CI auto-detection.
|
PR feature/a → main |
PR analysis | PR key/source/base; full history; target analyzed first; provider binding. |
| Community-only developer laptop | Local simulation | Git merge base/diff + parameter manifest; do not pass commercial properties. |
9. Rollback and change control
Scanner parameter mistakes are usually corrected by changing CI configuration and rerunning the same intended revision. Do not delete the SonarQube project, change project keys, rewrite Git history, or lower gates to erase a bad run. Preserve the wrong task/configuration first, then run the smallest equivalent correction.
Knowledge check
Why is manual sonar.pullrequest.base dangerous in
a provider-managed CI?
Manual values override auto-detection; a wrong base changes the comparison target and New Code semantics.
When is branch analysis preferable to PR analysis?
When the branch itself is a retained development/release line that must be evaluated independently of a pull request.
Who ultimately blocks a merge on a SonarQube status?
The DevOps provider’s branch/ruleset/policy configuration; SonarQube calculates and reports the status.
Why is a new project key per feature branch a poor Developer+ design?
It fragments project identity/history and loses true branch/PR comparison semantics.
What is the safer response to missing blame in CI?
Restore full-enough SCM history and target refs rather than disabling SCM integration.
ceTaskId so the
branch/PR identity can be tied to one asynchronous Compute Engine
result before interpreting the gate or provider status.
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/baseparameters. -
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.
Rechecked 2026-09-08. Mandatory examples target SonarQube
Community Build 26.9.0.129388 and SonarScanner
CLI 8.1.0.6389. Current commercial reference
points are SonarQube Server 2026 Release 4.1 and
2026.1.5 LTA. Current product packaging places
analysis of feature/maintenance branches, pull/merge requests, and
PR quality-gate decoration in
Developer Edition and above. Pull-request
analysis must run in a CI pipeline; the source branch must be
checked out, the target fetched, valid .git metadata
retained, and full-enough history available. SonarSource
recommends full depth; for GitHub Actions the documented pattern
is fetch-depth: 0. Supported CI systems can
auto-detect branch/PR parameters; manually supplied PR properties
override automatic detection. Recheck provider-specific
integration limits and CI auto-detection behavior before
production rollout.
Keep the academy open
Support free, practical DevOps education.
Every lesson is designed to remain readable in a browser, downloadable from GitHub, and usable without a paid learning platform. Contributions help expand and maintain the curriculum.
0x716c4Ab160C4B66F31a28AE2448BfF68fc3a2ef0Send only Ethereum/ERC-20 compatible assets to this
address.