GitHub, GitLab, Azure DevOps, and Bitbucket Integration: Diagnostics, Failure Modes, and Production Practices

1. Evidence-first diagnostic sequence

1. Preserve CI/scanner log, report-task.txt, ceTaskId, Compute Engine response, Quality Gate response, provider response/check state, and exact Git SHA.
2. Confirm SonarQube Community/Server edition/version, scanner/runtime, integration/provider version, and relevant extension/plugin version.
3. Confirm project key, binding, provider organization/repository identity, PR/MR key/target, and server base URL.
4. Confirm which credential is failing: SonarQube analysis token, provider App/PAT/OAuth credential, repository-import token, or CI service connection.
5. Inspect only metadata: credential owner, scope, installation/repository reach, expiry, revocation status, and secret-store location. Never print the value.
6. Confirm network/TLS/API endpoint behavior.
7. Apply the least-destructive correction to that trust edge.
8. Rerun the smallest equivalent request; do not rerun the entire pipeline when a provider-only call can be tested independently.

2. Failure: personal administrator token used for automation

Symptom: integration works, but a developer leaves or the token is discovered in multiple pipelines. The technical function may be green while governance is red.

Diagnosis: inventory where the token is stored and what repositories/organization resources it can access. Replace it with a dedicated GitHub App, GitLab technical/group token, Azure technical PAT, or Bitbucket OAuth/API identity as appropriate. Verify the replacement before revocation.

3. Failure: organization-wide privileges for one repository

A 403 is not evidence that “admin” is required. Compare the requested API operation with the documented provider permission. For GitHub PR reporting, Checks/Pull Requests read-write are materially different from organization Administration. For Azure, Code read/write is different from Project/Organization administrator. Grant only the documented operation scope.

4. Failure: assuming all providers use identical semantics

5. Failure: webhook confused with analysis authentication

If a webhook callback returns 200 but scanner upload returns 401, the webhook is irrelevant to scanner authentication. Inspect SONAR_TOKEN, project execute-analysis permission, server URL, and token revocation. Conversely, if scanner/CE/gate succeed but provider decoration is absent, inspect provider binding/credential/API delivery—not the scanner token.

6. Failure: provider secret exposed in YAML or logs

Rewriting Git history may be appropriate under your repository governance, but revocation comes first; history rewriting does not invalidate a credential.

7. Failure: Bitbucket Cloud OAuth setup follows stale labels

Symptom: the runbook says “Create OAuth Consumer / OAuth Key,” but Bitbucket Cloud only offers an OAuth Client / Client ID. Sonar staff acknowledged this documentation/UI mismatch in August 2026 and advised Client credentials with Pull requests Read. Older maintained Sonar lines also required specific patch levels after Bitbucket changed an OAuth response field.

Repair: record current Bitbucket and SonarQube versions, use the current OAuth Client model, and upgrade to a current patch if the server line contains a known compatibility defect. Do not weaken OAuth/TLS or switch to an administrator App password.

8. Failure: Azure PAT expires or technical account becomes invalid

Azure PAT expiry is expected lifecycle state. A provider 401/403 after months of successful decoration can be a credential-expiry or account-access problem while SonarQube analysis still succeeds. Check PAT metadata and technical-account access type/status, rotate deliberately, test the new PAT, then revoke the old one.

9. Intentionally broken example: gate succeeds, provider permission fails

Use the Lesson 2 simulator with checks=read instead of read_write. Preserve:

• same Git revision;
• same scanner log/report-task/ceTaskId;
• same Compute Engine SUCCESS;
• same Quality Gate response;
• SIMULATED_PROVIDER_403 plus the insufficient permission manifest.

This failure proves causality: the provider write contract is broken while analysis state is healthy. The repair restores only the missing provider write permission.

10. Causal failure map

11. Production shortcuts to reject

• Do not grant organization/project administrator because the minimum scope is unclear.
• Do not disable TLS verification for provider/SonarQube callbacks or API calls.
• Do not paste PATs/client secrets/private keys into source, logs, screenshots, or tickets.
• Do not delete a SonarQube project or change project key to repair provider binding.
• Do not lower a Quality Gate because provider delivery failed.
• Do not blanket retry the entire scanner/build when the failure is a provider-only 401/403.
• Do not keep sandbox credentials after the lab “just in case.”

Knowledge check

Official references and version notes

• SonarQube downloads / edition matrix — current Community Build and Server editions; branch/PR analysis and provider decoration begin in Developer Edition.
• GitHub App integration — dedicated App, Checks/Pull Requests permissions, private repository Contents read, optional permissions, and webhook guidance.
• GitHub project integration — bound project and pull-request Quality Gate/check behavior.
• GitLab global integration — dedicated Reporter account or Group Access Token with API scope and stored/revocable token.
• GitLab repository import — import token read_api flow and repository binding.
• Azure DevOps integration — global configuration, technical PAT, extension/pipeline model, Quality Gate reporting and PR feedback.
• Azure repository import — project import PAT and bound-project behavior.
• Bitbucket Cloud global integration — SonarQube’s global OAuth configuration and pull-request permission model.
• Bitbucket Cloud repository import — API token with read:repository:bitbucket; App passwords deprecated.
• Sonar staff clarification on Bitbucket Cloud OAuth Client terminology (Aug–Sep 2026) — current UI uses OAuth Client / Client ID / Secret, client credentials, Pull requests Read; older maintained Sonar lines needed specific patched releases after a Bitbucket OAuth field change.
• SonarQube Web API — bearer authentication and API guidance used for local evidence queries.
• SonarScanner CLI 8.1.0.6389 — scanner baseline used by the mandatory lab.