Branches, Pull Requests, Merge Requests, and Edition-Aware Analysis: Diagnostics, Failure Modes, and Production Practices

1. Evidence-first diagnostic sequence

1. Preserve CI checkout logs, scanner command/effective context, report-task.txt, task ID, and provider status.
2. Record server edition/version, scanner version/runtime, analyzer/plugin versions, and integration versions.
3. Record Git SHA, current branch, shallow state, refs, target branch, and merge base.
4. Record effective project key and branch/PR parameters or auto-detected provider metadata.
5. Inspect scanner indexing/report upload and Compute Engine result.
6. Inspect SonarQube PR/branch identity, New Code, profile/gate, and issue population.
7. Inspect provider binding/permissions/status delivery only after SonarQube analysis state is proven.
8. Apply the least-destructive correction and rerun the same intended revision/question.

2. Failure: wrong PR target or key

Symptom: the PR analysis exists but New Code contains unexpected files, or decoration appears on the wrong pull request.

Likely cause: sonar.pullrequest.base or sonar.pullrequest.key was manually set incorrectly and overrode correct CI metadata.

git branch --show-current
git rev-parse HEAD
git merge-base HEAD origin/main
git diff --name-status origin/main...HEAD

# Preserve intended identity separately:
printf '%s\n' \
  'sonar.pullrequest.key=17' \
  'sonar.pullrequest.branch=feature/demo' \
  'sonar.pullrequest.base=main' \
  | tee evidence/intended-pr.properties

Repair the CI identity parameters; do not create a replacement SonarQube project key to escape the incorrect PR analysis.

3. Failure: shallow clone breaks comparison/blame

Evidence: git rev-parse --is-shallow-repository returns true, the target ref is absent or merge-base fails, and scanner logs report missing SCM/blame context.

Repair: fetch full history and all required target refs. In GitHub Actions, use actions/checkout with fetch-depth: 0. Do not remove .git after checkout.

4. Failure: teaching commercial branch analysis as Community Build

Anti-pattern: “Just add -Dsonar.branch.name=feature/a to Community Build.” This confuses a scanner parameter with a licensed server feature. The correct Community Build fallback is main-branch analysis plus a clearly labeled Git/configuration simulation, or a separate simulation project if an executable feature revision must be analyzed.

5. Failure: comparing PR New Code metrics to main overall metrics

A PR can have 100% New Code coverage while main overall coverage is 62%. Both can be correct because they describe different code populations. Likewise, a PR may report only issues on changed lines while the first main analysis after merge can reveal issues on old code that PR analysis did not report. Interpret the population before interpreting the number.

6. Failure: reusing/changing project keys to model branches

In Developer+, branches and PRs belong to the same project identity. Creating myapp-feature-a, myapp-feature-b, and myapp-release as unrelated projects fragments history and prevents proper comparison/synchronization. In Community Build, a second project key is acceptable only as an explicitly temporary simulation—not as a claim of branch support.

7. Failure: analysis succeeds but decoration is missing

8. Intentionally broken example: wrong base + shallow checkout

Suppose a CI job manually sets sonar.pullrequest.base=develop for a PR that actually targets main, and the checkout has depth 1. Preserve both defects before changing anything:

mkdir -p evidence/broken

git rev-parse HEAD | tee evidence/broken/sha.txt
git branch --show-current | tee evidence/broken/branch.txt
git rev-parse --is-shallow-repository | tee evidence/broken/is-shallow.txt
git show-ref | tee evidence/broken/refs.txt
printf '%s\n' 'sonar.pullrequest.base=develop' \
  | tee evidence/broken/effective-override.txt

# Expected to fail or show missing target context; preserve output:
git merge-base HEAD origin/main 2>&1 \
  | tee evidence/broken/merge-base.txt || true

Repair one layer at a time: restore Git history/target ref first, prove the merge base, then remove/fix the incorrect manual base parameter. Rerun the same feature SHA. This lets you attribute the corrected behavior causally.

9. Troubleshooting shortcuts to reject

• Do not switch to a different project key after a failed PR analysis.
• Do not delete SonarQube branch/PR history before preserving evidence.
• Do not disable SCM to hide shallow-clone warnings.
• Do not lower Quality Gate thresholds to make a misidentified PR green.
• Do not use administrator tokens for routine analysis/decoration.
• Do not disable TLS verification or directly edit database/search state.
• Do not repeatedly retry before recording the first Compute Engine/provider failure.

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.