Projects, Tokens, Scanners, Analysis Parameters, and First Analysis: Core Concepts and Mental Model

1. Current baseline and scope

The executable baseline is Community Build 26.9.0.129388 and standalone SonarScanner CLI 8.1.0.6389. The server is assumed healthy from earlier chapters at a local/private endpoint. Chapter 06 deliberately performs the first source analysis, but it does not yet teach every scanner family—that comes in Chapter 07.

2. Mental model: source evidence to quality evidence

flowchart TD
R[Repository + exact revision] --> P[Effective parameters]
T[Project analysis token] --> S[SonarScanner]
P --> S
S --> I[Indexed files + analysis report]
I --> U[Report upload]
U --> C[Compute Engine task]
C --> D[(Database / search)]
D --> Q[Measures + issues + Quality Gate]
Q --> E[UI / API / delivery evidence]

The scanner owns client-side discovery, indexing, analyzer execution, report generation, and upload. The server then owns the background Compute Engine task and persistence. A successful upload therefore creates work to be processed; it is not the same event as a completed analysis or a passing Quality Gate.

3. State stores you must not blend together

4. Stable project key versus display name

sonar.projectKey is the durable, case-sensitive identity that associates analyses with a project. Current rules allow letters, digits, dash, underscore, period, and colon, with at least one non-digit character. The chapter uses academy-sonarqube-p06. The display name Academy SonarQube Prompt 06 Lab is human-facing metadata, not the automation identity.

Do not manufacture a new key per build, branch, timestamp, or workstation. Those values describe an execution context and should be recorded as evidence rather than encoded into ordinary project identity.

5. Token types are permission boundaries

Current SonarQube supports user tokens, project analysis tokens, and global analysis tokens. Project analysis tokens are encouraged for single-project analysis because leakage is constrained to that project’s Execute Analysis boundary. User tokens inherit the issuer’s UI/API permissions; global-analysis tokens can cover all projects permitted by the global Execute Analysis permission.

Scope and lifetime are separate controls. A project-scoped token can still be poorly governed if it never expires, has an unclear owner, or is copied into many uncontrolled places.

6. Parameter precedence and persistence

Current documentation defines the precedence from lowest to highest as: global UI settings → project UI settings → scanner/project configuration → scanner command-line arguments. Environment variables exist for selected connection/authentication parameters and can themselves be superseded by explicit scanner arguments. Only UI-stored values persist in the SonarQube database for reuse; config-file and command-line overrides are analysis-time inputs.

7. Scanner runtime and JRE auto-provisioning

The standalone CLI is suitable for this small build-neutral fixture. Real Maven, Gradle, .NET, NPM, or Python projects often benefit from ecosystem scanners that understand build structure. Current supported scanner generations use JRE auto-provisioning by default where supported. If an organization disables provisioning, it must supply the current compatible Java runtime; old Java 17-era scanner guidance must not be copied forward blindly.

8. report-task.txt is the client/server bridge

After successful report upload, the scanner writes report-task.txt in its working directory (or the configured sonar.scanner.metadataFilePath). Among its fields is ceTaskId. Preserve it before reruns or cleanup because it ties the client run to the exact server-side Compute Engine task.

Default analysis remains asynchronous. sonar.qualitygate.wait=true is an explicit opt-in that makes the scanner poll until the Quality Gate is known and can fail the analysis step when the gate fails. That changes CI behavior; it does not remove the underlying Compute Engine task.

9. Read-only preflight

git status --short
git rev-parse HEAD
sonar-scanner --version
curl --fail --silent http://127.0.0.1:9000/api/server/version
curl --fail --silent http://127.0.0.1:9000/api/system/status

Record the outputs. Avoid scanner debug mode until you actually need it and have controlled secret exposure; debug logs can contain sensitive environment information.

10. Pre-analysis prediction lab

1. Write the intended project key and exact Git revision.
2. Predict which file(s) should be indexed and which directory will contain scanner metadata.
3. Predict that no new Compute Engine task or gate result exists until after upload.
4. Choose the token type and justify why broader token types are unnecessary.
5. Draw revision → parameters → indexing → report → CE task → gate and label each owner.

Knowledge check

Official references and version notes

• SonarQube downloads — current Community Build and Server release identities.
• Managing your tokens — user, project-analysis, and global-analysis token semantics.
• Analysis-parameter configuration overview — precedence and persistence.
• Managing JRE auto-provisioning and scanner environment requirements.
• SonarScanner CLI 8.1.0.6389 and official scanner metadata.
• Web API — bearer authentication and the gradual Web API V2 transition.
• CI integration overview — asynchronous processing and quality-gate waiting.