Monorepos, Multi-Module Builds, Generated Code, and Complex Repository Layouts: Configuration, Design Patterns, and Trade-Offs

1. One project versus multiple projects

The correct boundary is usually the smallest unit whose quality policy and lifecycle can be governed coherently. A monorepo with ten packages may still be one product; a repository with two independently deployed services may need two SonarQube projects.

2. Build-native modules versus manual scanner slicing

For Maven, Gradle and .NET, prefer the scanner integrated with the build system when it understands the actual module graph, compiled outputs and test layout. This avoids manually reconstructing a model the build already knows.

Manual sonar.projectBaseDir slicing is appropriate for CLI-managed repositories, language ecosystems without a build-integrated scanner, or genuinely independent project boundaries. Record the base and every relative path as part of the configuration contract.

3. Base directory versus changing the shell working directory

These two commands can target the same files but have different operational evidence:

# A: explicit coordinate from repository root
sonar-scanner -Dsonar.projectBaseDir=modules/api -Dsonar.sources=src

# B: shell coordinate change
(cd modules/api && sonar-scanner -Dsonar.sources=src)

Option A makes the module base explicit in scanner parameters. Option B can simplify tool/report paths because the test producer and scanner share a working directory. Choose one convention and standardize it; mixing both styles casually is a common source of doubled prefixes.

4. Generated-code treatment: choose the narrowest exclusion

Broad source exclusion is the most destructive option. Use it only when the file truly sits outside the project’s code-quality ownership contract.

5. Single versus merged reports

A one-project topology can import multiple language-specific coverage reports when the parameter supports a list/wildcards, or an intentionally aggregated report produced by the test tool. A multi-project topology should normally give each project only the report that corresponds to files in its indexed scope.

• Do not concatenate XML formats unless the producing tool documents that operation.
• Do not feed one module’s report to another project merely because the filename exists.
• Do not assume a report-relative source path means the same thing after changing projectBaseDir.
• Verify the report’s internal filenames before scanner invocation.

6. Serial versus parallel analyses

Parallelism is safe only when the state surfaces are isolated. For distinct projects, use separate checkouts or module directories, unique sonar.working.directory values, unique report destinations, project-scoped tokens and distinct artifact names. Preserve each report-task.txt separately.

For the same SonarQube project/branch, serialization is the safer default. Even if the scanner processes can run concurrently, two reports for the same project identity can race semantically: the build that finishes last may not correspond to the revision you intended to treat as authoritative. CI concurrency controls should cancel/stale-suppress superseded runs or serialize by project/branch.

7. Aggregation is a view over correct projects, not a substitute for topology

Never create an application or portfolio first and hope it will expose incorrect project scopes. Validate each component project independently before aggregating it.

8. Worked scenarios

9. Topology manifest as policy as code

revision: "<git-sha>"
projects:
  - key: sq-ch24-api
    owner: team-api
    base_dir: modules/api
    sources: [src]
    tests: [tests]
    reports: [coverage.xml]
    generated_policy: "exclude none inside module"
    scanner_workdir: .scannerwork-ch24-api
    concurrency_key: sq-ch24-api-main
  - key: sq-ch24-worker
    owner: team-worker
    base_dir: modules/worker
    sources: [src]
    tests: [tests]
    reports: [coverage.xml]
    scanner_workdir: .scannerwork-ch24-worker
aggregation:
  community_fallback: "timestamped markdown/API summary"
  optional_application: "Developer+ only if shared lifecycle"
  optional_portfolio: "Enterprise+ governance view"

Treat this manifest as a reviewable contract. A CI implementation can derive commands from it, but changes to ownership/scope should require the same scrutiny as a Quality Gate or permission change.

Knowledge check

Official references and version notes

• Community Build — analysis parameters not settable in UI — sonar.projectBaseDir, sonar.sources, sonar.tests, sonar.working.directory, report-task path and token guidance.
• Community Build — setting initial scope — source/test roots are simple paths relative to project base directory; no wildcards in initial roots.
• Community Build — analysis-scope introduction — generated/library code, coverage/duplication exclusions and verification workflow.
• Community Build — test coverage parameters — externally generated reports and project-root-relative path rules.
• Community Build — SonarScanner CLI — alternate project base directory behavior and CLI configuration.
• Community Build — Java/multi-module coverage — build-native JaCoCo generation and multi-module aggregation patterns.
• SonarQube Server — managing monorepo projects — Enterprise monorepo feature, multiple SonarQube projects bound to one repository, unique project keys and manual project definition.
• SonarQube Server — Applications — synthetic aggregation for projects sharing a lifecycle; commercial feature.
• SonarQube Server — Portfolios — Enterprise governance aggregation.
• SonarScanner CLI releases — current public scanner release baseline.
• SonarQube downloads — current Community Build/Server/LTA release identities.