Portfolios, Applications, Enterprise Reporting, and Governance Boundaries: Diagnostics, Failure Modes, and Production Practices

1. Evidence-first diagnostic sequence

1. Preserve the generated report, membership definition, script/version, API responses, report timestamp, and access errors.
2. Confirm exact Community Build/Server edition/version, instance mode, scanner/runtime, and commercial feature entitlement.
3. For every included project, confirm project key, selected branch, revision, source/report inputs, scanner log, ceTaskId, and Compute Engine success.
4. Confirm latest project analysis date, Quality Gate, ratings/measures, and permissions.
5. If native Application/Portfolio is used, inspect definition, member branches, recomputation/background-task state, and aggregate permissions.
6. Validate each aggregation formula against current documentation; never assume all metrics use the same math.
7. Inspect report recipient/export controls only after the data itself is proven.
8. Apply the smallest correction and regenerate the same report population.

2. Failure: teaching Enterprise aggregation as universally free

A Community Build learner who cannot find Portfolios has not misconfigured the server. Applications begin at Developer; Portfolios and PDF reports begin at Enterprise. Diagnose the edition first. Do not install untrusted plugins, copy commercial files, or modify the database to manufacture a feature.

3. Failure: naive percentage averaging

Suppose Project A has 90% coverage across 1,000 opportunities and Project B has 50% across 20. The naive average is 70%. The denominator-aware result is:

The 70% figure is mathematically valid only for the question “what is the arithmetic mean of two percentages?” It is not the coverage of the combined code population.

4. Failure: aggregate green hides a failing project

A portfolio-style A means more than 80% of included branches pass. With ten projects, nine green and one red still yields A. Therefore every executive status card needs at least one of: failing count, breakdown link, project table, or explicit exception list.

5. Failure: fresh report, stale analysis

“Generated 2026-09-08” says nothing about whether a member project was last analyzed today, last week, or last quarter. Define a freshness policy such as “production-governance reports must flag any project older than seven days,” then calculate age from the project analysis timestamp.

On licensed installations also distinguish project freshness from Application/Portfolio recomputation. A component project can finish analysis while its aggregate background task is still queued or failed.

6. Failure: exposing restricted project data

A report generated by an administrator and emailed widely can reveal names, ratings, issue counts, or security state from private projects that recipients could not browse directly. Use a dedicated reporting identity with exactly the visibility intended for the audience. If a component returns 403, preserve that as an authorization result rather than silently rerunning with an administrator token.

7. Failure: treating reporting as remediation

A red row becoming visible in a PDF does not fix the project. The report should route action back to the project owner, exact failing gate condition, revision, and issue/measure evidence. A governance process is complete only when action is assigned, remediation is performed in the owning system, and later analysis verifies the new state.

8. Intentionally broken report

Preserve this code and its output before repairing it:

# broken_governance.py -- intentionally wrong
projects = [
    {"key": "A", "coverage": 90.0, "gate": "OK", "weight": 1000},
    {"key": "B", "coverage": 50.0, "gate": "ERROR", "weight": 20},
]

# BUG 1: percentages averaged without denominators.
coverage = sum(p["coverage"] for p in projects) / len(projects)

# BUG 2: aggregate says PASS if most projects pass and hides the failed row.
status = "PASS" if sum(p["gate"] == "OK" for p in projects) / len(projects) >= 0.5 else "FAIL"

print({"coverage": coverage, "status": status})

Expected misleading output:

{'coverage': 70.0, 'status': 'PASS'}

The script produced syntactically valid data and no scanner error. The defect is governance semantics.

9. Repair without hiding the original cause

# repaired excerpt
covered = 0.90 * 1000 + 0.50 * 20
total = 1000 + 20
exact_coverage = 100 * covered / total

passing = [p for p in projects if p["gate"] == "OK"]
failing = [p for p in projects if p["gate"] != "OK"]
pass_ratio = 100 * len(passing) / len(projects)

# Portfolio-style grade; still list every failed project.
if pass_ratio > 80: grade = "A"
elif pass_ratio > 60: grade = "B"
elif pass_ratio > 40: grade = "C"
elif pass_ratio > 20: grade = "D"
else: grade = "E"

print({
    "exact_coverage": round(exact_coverage, 2),
    "portfolio_style_releasability": grade,
    "pass_ratio": pass_ratio,
    "failing_projects": [p["key"] for p in failing],
})

The repair makes two changes only: denominator-aware coverage and explicit failure visibility. It does not lower a Quality Gate, remove a project, suppress issues, or change source.

10. Causal failure map

11. Production anti-patterns to reject

• Do not use an administrator token just because a reporting query gets 403.
• Do not lower Quality Gate thresholds to improve an executive report.
• Do not remove failing members without a governed definition change.
• Do not backdate or overwrite analysis/report timestamps.
• Do not directly edit SonarQube database/search data to change aggregate state.
• Do not delete the misleading first report before preserving it.
• Do not publish private-project details to recipients who are not authorized to see them.

Knowledge check

Official references and version notes

• SonarQube downloads and editions — current Community Build, commercial release stream, Developer/Enterprise/Data Center feature boundaries, and current LTA.
• SonarQube Server — Applications — lifecycle-oriented synthetic aggregation, consolidated application view/gate, and recalculation model.
• Managing applications — creation/admin permissions, project/branch membership, and background recalculation.
• SonarQube Server — Portfolios — Enterprise boundary, releasability, rating conversion/averaging, breakdown, trend, and last-analysis context.
• Managing portfolios — permissions, project/branch selection, applications/nested portfolios, and recalculation.
• PDF reports — Enterprise Edition+ reports for projects/applications/portfolios, subscriptions, and permanent-branch constraints.
• Measures and metrics — coverage numerator/denominator, ratings, Quality Gate metrics, and portfolio-visible metric boundaries.
• Community Build Web API — bearer authentication and documented project evidence retrieval used by the free lab.