Monorepos, Multi-Module Builds, Generated Code, and Complex Repository Layouts: Core Concepts and Mental Model

1. The practical problem: a repository tree is not an analysis model

Chapter 23 automated SonarQube policy safely. Chapter 24 applies that discipline to repositories where one checkout contains several independently built pieces, generated source, shared libraries, nested build files, and multiple report locations. The dangerous assumption is that SonarQube will infer the intended business boundary from directory names. It does not.

You must decide which files belong to which SonarQube project, from which directory each scanner resolves relative paths, which test and coverage reports belong to that project, and whether two analyses may run concurrently. A green dashboard is not trustworthy if another module was silently omitted or the same file was analyzed twice under unrelated project keys.

2. Define the boundaries before configuring them

3. Mental model: tree → ownership → base directory → evidence

flowchart TD
  R[One Git revision] --> G[Build graph]
  G --> A[api module]
  G --> W[worker module]
  A --> PA[Project key: repo-api]
  W --> PW[Project key: repo-worker]
  PA --> BA[projectBaseDir: modules/api]
  PW --> BW[projectBaseDir: modules/worker]
  BA --> RA[src/tests/coverage.xml]
  BW --> RW[src/tests/coverage.xml]
  RA --> CA[Distinct scanner work/task]
  RW --> CW[Distinct scanner work/task]
  CA --> QA[API gate/history]
  CW --> QW[Worker gate/history]
  QA --> AG[Optional aggregation]
  QW --> AG

The arrow from module to SonarQube project is a governance decision. SonarQube does not discover it from a build graph unless the scanner/build integration explicitly supplies the structure. Even then, the project key and lifecycle boundary remain yours to define.

4. sonar.projectBaseDir: the coordinate system for analysis

For SonarScanner CLI, sonar.projectBaseDir changes the analysis directory. Relative source/test paths are interpreted from that base directory, and many report/import paths are also relative to the project root/base directory unless their parameter documentation says otherwise.

repo/
  modules/
    api/
      src/
      tests/
      coverage.xml
    worker/
      src/
      tests/
      coverage.xml

If the scanner starts at repo/ but receives -Dsonar.projectBaseDir=modules/worker, then sonar.sources=src correctly targets repo/modules/worker/src. But sonar.python.coverage.reportPaths=modules/worker/coverage.xml is now wrong: that relative value is interpreted from the worker base and effectively points one module path too deep.

5. Source and test scope are ownership declarations

sonar.sources and sonar.tests take simple file/directory paths; wildcard patterns are not allowed for the initial roots. Inclusions/exclusions filter those roots afterward. Source and test populations must remain disjoint.

# From modules/api as projectBaseDir
sonar.sources=src
sonar.tests=tests
sonar.exclusions=generated/**,vendor/**

Do not start with a large exclusion catalog. First choose the correct base and initial roots, run the scanner with useful logs, and inspect what was indexed. Add exclusions only when a specific ownership reason exists.

6. Generated code is a policy category, not a synonym for “ignore”

Generated source can mean several things: disposable compiler output, checked-in API clients, ORM code, protobuf stubs, vendored third-party source, or templates that developers partly edit. Each has different ownership and risk.

7. Reports must match the same ownership coordinate system

Coverage/test/external reports are produced outside SonarQube and imported by the scanner. Most report-path parameters are relative to the project root/base directory unless documented otherwise. The paths recorded inside a report must also be resolvable to files the scanner has indexed for that project.

A report can exist on disk and still contribute nothing to the intended project if either coordinate system is wrong. Preserve the report header/path entries and scanner import log before changing anything.

8. Scanner working directories and concurrency

Current analysis-parameter documentation says sonar.working.directory must be unique for each project and warns that the scanner deletes the specified directory before each analysis. This matters immediately in parallel CI.

Good parallel shape:
job-api    → projectKey=repo-api    → base=modules/api    → work=.scannerwork-api
job-worker → projectKey=repo-worker → base=modules/worker → work=.scannerwork-worker

Bad parallel shape:
job-A ─┐
       ├→ same checkout + same .scannerwork + same report filename
job-B ─┘

Separate project keys are not enough if jobs write into the same scanner/report artifact path. Conversely, separate work directories do not make concurrent analyses of the same project/branch logically safe. Serialize same-project/revision policy unless you have a documented reason and can explain how resulting histories and tasks are ordered.

9. Community Build versus native monorepo and aggregation features

The mandatory learning path uses Community Build and explicit project keys/base directories. Current SonarQube Server documentation labels native monorepo project onboarding/binding as an Enterprise Edition feature. That feature helps bind multiple SonarQube projects to the same provider repository and distinguish PR gate reports; it does not magically discover your module ownership.

Commercial aggregation is separate again: Applications are available starting in Developer Edition and group projects that share a lifecycle; Portfolios start in Enterprise Edition and provide higher-level governance views. Neither replaces correct per-project scope, report mapping, or task evidence.

10. Read-only inspection before any redesign

git rev-parse --show-toplevel
git rev-parse HEAD
git status --short
find . -maxdepth 3 -type f \( -name 'pom.xml' -o -name 'build.gradle*' -o -name '*.sln' -o -name 'pyproject.toml' -o -name 'package.json' \) -print
find . -maxdepth 4 -type f \( -name 'coverage*.xml' -o -name 'lcov.info' -o -name '*.sarif' \) -print

# Record scanner/runtime separately.
sonar-scanner --version

Then write an ownership table: module, owner, release lifecycle, intended project key, project base directory, sources, tests, generated/vendor policy, report paths, working directory, token owner, and expected aggregation. Do not scan until every row is explainable.

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.