CI Integration with GitHub Actions, GitLab CI, Jenkins, and Other Runners: Diagnostics, Failure Modes, and Production Practices

1. Evidence-first diagnostic sequence

1. Preserve CI job logs, checkout SHA/depth, build/test logs, report files, scanner log, and .scannerwork/report-task.txt.
2. Record SonarQube edition/version, scanner/action/plugin/runtime versions, runner image, and build/test producer versions.
3. Confirm exact source revision, workspace/base directory, effective analysis parameters, and report paths.
4. Confirm scanner indexing/report upload and preserve ceTaskId.
5. Inspect Compute Engine task status/error before rerunning.
6. Inspect project profile/gate/New Code/security state and only then the Quality Gate result.
7. Inspect CI/provider secret/network/status state if the server result is healthy but orchestration failed.
8. Inspect database/search/JVM/host/container only when evidence points to server infrastructure.
9. Apply the smallest correction and rerun the same revision/scenario where possible.

2. Failure: token stored literally in YAML

# BAD — credential becomes repository/history data.
env:
  SONAR_TOKEN: FAKE_SONAR_TOKEN_DO_NOT_USE

The correct response is not merely to replace the line in the latest commit. If a real credential was committed, revoke/rotate it immediately, preserve the incident trail, assess repository/history exposure, and move the replacement into the provider secret store. In this course, the string above is intentionally fake and nonfunctional.

3. Intentionally broken example: scan before coverage exists

This failure is ideal for causal diagnosis because the source revision, profile, gate, and token can remain constant. Only pipeline order changes.

rm -f coverage.xml
mkdir -p evidence/broken-order

# BROKEN: scanner is told to import coverage.xml before the producer creates it.
set +e
sonar-scanner -X 2>&1 | tee evidence/broken-order/scanner.log
BROKEN_SCAN_RC=${PIPESTATUS[0]}
set -e
cp .scannerwork/report-task.txt evidence/broken-order/report-task.txt 2>/dev/null || true

# Too late: this report was not part of the already-uploaded analysis.
python -m pytest -q --cov=src --cov-report=xml:coverage.xml \
  2>&1 | tee evidence/broken-order/test-after-scan.log

git rev-parse HEAD | tee evidence/broken-order/revision.txt
printf 'broken_scanner_exit=%s\n' "$BROKEN_SCAN_RC" \
  | tee evidence/broken-order/final-state.txt

Interpret the scanner log. Expect evidence that the configured coverage path could not be imported or no coverage report was found. Even if the scanner exits successfully and coverage.xml exists by the end of the job, the SonarQube analysis cannot have consumed a file that did not exist when the scanner built its report.

4. Repair the order without gaming scope or policy

mkdir -p evidence/repaired-order
rm -rf .scannerwork coverage.xml

# Same Git revision; correct only the pipeline order.
git rev-parse HEAD | tee evidence/repaired-order/revision.txt

python -m pytest -q \
  --cov=src --cov-report=xml:coverage.xml \
  2>&1 | tee evidence/repaired-order/test.log
test -s coverage.xml

sonar-scanner -X 2>&1 | tee evidence/repaired-order/scanner.log
cp .scannerwork/report-task.txt evidence/repaired-order/report-task.txt
sed -n 's/^ceTaskId=/ceTaskId=/p' .scannerwork/report-task.txt \
  | tee evidence/repaired-order/ce-task-id.txt

The repair is valid because it does not exclude uncovered files, lower a gate, deactivate coverage, change the project key, or delete history. It changes only when a required report is created.

5. Failure: shallow checkout breaks SCM context

Current Sonar guidance for GitHub and GitLab recommends disabling shallow clone. Diagnose it with Git—not with the SonarQube database:

git rev-parse --is-shallow-repository
git log --oneline --decorate -5

# Provider repair examples:
# GitHub: checkout with fetch-depth: 0
# GitLab: GIT_DEPTH: "0"

Do not disable SCM attribution merely to suppress blame/ref warnings. Restore the required history and rerun the smallest equivalent job.

6. Failure: the job fails and the evidence disappears with the runner

Ephemeral runners are valuable for clean state, but they make artifact retention mandatory. A job that says only “failed” after its workspace vanished cannot distinguish test failure, scanner failure, Compute Engine failure, or gate failure.

• GitHub: use an if: always() artifact step.
• GitLab: use artifacts: when: always.
• Jenkins: use post { always { archiveArtifacts ... } }.
• Generic CI: copy logs/reports/task metadata to the platform artifact store before teardown.

Never delete logs/cache before preservation as a troubleshooting habit.

7. Failure: floating or unreviewed action/plugin revision

# BAD: code can change without a workflow review.
- uses: some-org/some-sonar-wrapper@main

# Better: reviewed publisher and immutable commit, with release annotation.
- uses: SonarSource/sonarqube-scan-action@22918119ff8e1ca75a623e15c8296b6ea4fbe28f # v8.2.1

Version drift is not only a security risk. Scanner action upgrades can change bundled Scanner CLI/JRE behavior, argument parsing, required runner utilities, signature verification, and cache behavior. Record the resolved revision in the evidence packet.

8. Failure: parallel jobs race analyses for one project/revision

Suppose Linux, Windows, and macOS jobs all submit the same project key and commit. You now have multiple server tasks, possibly different report populations, and no simple rule for which dashboard state represents the canonical build. The repair is orchestration:

• Choose one canonical analysis job.
• Make it depend on the required matrix tests.
• Merge only supported report formats with proven provenance.
• Use provider concurrency/resource-group controls when duplicate runs must be prevented.
• Do not solve the race by creating a new SonarQube project key per runner.

9. Failure: “job success means gate pass”

A direct scanner invocation without gate waiting can exit successfully after upload. If the pipeline then ends, the job can be green while Compute Engine is still processing or while the gate later fails. Repair by choosing an explicit enforcement contract:

• GitHub: Quality Gate Check Action or explicit scanner wait.
• GitLab/generic runner: sonar.qualitygate.wait=true.
• Jenkins: waitForQualityGate with the mandatory webhook.

Record the gate result and CI exit independently. Do not retroactively claim the scanner failed simply because the gate did.

10. Causal failure map

11. Production anti-patterns to reject

• Do not commit or echo tokens.
• Do not disable TLS verification to solve runner certificate problems; establish the correct CA trust.
• Do not use global/admin tokens everywhere.
• Do not run tests after the scan when their reports are analysis inputs.
• Do not hide a failing gate by lowering policy thresholds or suppressing issues.
• Do not clear logs/caches before preserving first failure.
• Do not reuse a stale report-task.txt from cache.
• Do not replace a failed analysis with a new project key.
• Do not restart SonarQube blindly when the failure is clearly runner-side.

Knowledge check

Official references and version notes

• SonarQube Community Build — CI integration overview — current gate-wait mechanisms, Jenkins/GitHub/Bitbucket options, sonar.qualitygate.wait, and 300-second default timeout.
• Adding analysis to GitHub Actions — current Scan Action v8 guidance, SONAR_TOKEN/SONAR_HOST_URL, Community Build main-only workflow, and full-history checkout recommendation.
• SonarQube Scan Action v8.2.1 — current action release used/pinned in the teaching workflow.
• SonarQube Quality Gate Check Action v1.2.0 — current gate-action release; default scanner metadata file is .scannerwork/report-task.txt.
• Adding analysis to GitLab CI/CD — Docker executor, GIT_DEPTH: "0", SONAR_USER_HOME cache, CI variables, and gate wait guidance.
• Jenkins integration key features — SonarQube Scanner plugin behavior and Quality Gate integration.
• Jenkins pipeline pause — withSonarQubeEnv, mandatory /sonarqube-webhook/, and waitForQualityGate.
• Verifying code checkout — full SCM history and shallow-clone failure guidance.
• SonarScanner CLI 8.1.0.6389 — scanner baseline.
• SonarQube release announcements — Community Build 26.9.0.129388, Server 2026 Release 4.1, and 2026 Release 1.5 LTA.