Reports¶

Generate customizable reports summarizing open source activity for stakeholders.

Creating a Report¶

1. Navigate to Reports in the main menu
2. Configure your report:
3. Date Range: 7, 30, 90 days, or custom
4. Organizations: All or select specific ones
5. Sections: Choose what to include
6. Click Generate Report

Report Sections¶

Activity Summary¶

Overview of activity across selected organizations:

• Total commits, PRs, and issues
• Comparison with previous period
• Activity trend chart

Health Scores¶

Repository health analysis:

• Average health score by organization
• Repositories with declining health
• Top healthy repositories
• Health score distribution

Top Repositories¶

Most active repositories:

• By commits
• By pull requests
• By contributors

Contributors¶

Contributor analysis:

• Most active contributors
• New contributors
• Internal vs external breakdown
• Bot activity

Pull Requests¶

Pull request summary:

• Open PRs by repository
• Merge rate and time
• PRs requiring attention
• Stale PR report

Issues¶

Issue tracking:

• Open issues by repository
• Close rate
• Most active issue discussions

AI Summaries¶

When an LLM is configured (see Configuration → AI Summaries), each report includes an AI-generated executive summary at the top of the page.

• Automatic: generated alongside the report itself.
• Best-effort: if the LLM call fails the report is still saved without a summary, and nothing blocks report generation.
• Regeneratable: use the Regenerate button on the report detail page to ask for a fresh summary (e.g. after switching models or tuning prompts).
• Included in emails: scheduled report emails embed the summary at the top, so recipients see the takeaways without opening the dashboard.

If LLM_API_KEY is not set the AI Summary section does not appear and no calls are made. The feature is entirely optional.

Export Formats¶

Markdown¶

Export as Markdown for:

• GitHub/GitLab wikis
• Documentation sites
• Email as plain text

# Download via API
curl http://localhost:8000/api/reports/generate \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"format": "markdown", "days": 30}' \
  -o report.md

PDF¶

Export as PDF for:

• Executive summaries
• Printed reports
• Email attachments

Scheduling Reports¶

A saved template can email itself on a cadence:

1. Build the report you want in Reports > New report
2. Tick Save as template and give it a name
3. Choose a frequency: daily, weekly or monthly
4. Add recipients, comma-separated
5. Generate

Both a frequency and at least one recipient are required. A template carrying only one of them is saved without a schedule, since a half-scheduled report would generate and go nowhere.

How the cadence works¶

A pass runs every morning at 08:00 UTC and sends the templates whose cadence has come round: daily after a day, weekly after seven, monthly after thirty, each counted from that template's last send. There is no time-of-day or day-of-week choice, because 08:00 UTC is when the pass runs.

Sending requires SMTP to be configured (see Configuration). The email carries the rendered report and its AI summary when one is available.

Weekly digest¶

The common shape for a stakeholder update:

Reports are emailed as HTML. PDF is a manual download from the report page; email carries HTML.

Customization¶

Custom Date Ranges¶

For custom periods:

1. Select "Custom" from the date range dropdown
2. Enter start and end dates
3. Generate report

Organization Filtering¶

Create focused reports:

• All organizations: Executive overview
• Single organization: Team-specific report
• Comparison: Multiple organizations side-by-side

Section Selection¶

Choose relevant sections:

API Access¶

Generate reports programmatically:

import httpx

client = httpx.Client(
    base_url="http://localhost:8000/api",
    headers={"Authorization": f"Bearer {token}"}
)

# Generate report
response = client.post("/reports/generate", json={
    "days": 30,
    "format": "markdown",
    "sections": ["activity", "health", "contributors"],
    "organization_ids": ["uuid1", "uuid2"]  # Optional
})

report = response.json()
print(report["content"])

Email Delivery¶

Send reports via API:

response = client.post("/reports/send", json={
    "days": 30,
    "format": "pdf",
    "recipients": ["team@example.com", "manager@example.com"],
    "subject": "Weekly OSPO Report"
})

Report Templates¶

Save common configurations as templates:

1. Configure your report settings
2. Click Save as Template
3. Name your template (e.g., "Weekly Executive Summary")
4. Reuse by selecting from the template dropdown

Best Practices¶

For Executives¶

• Focus on trends and health scores
• Include month-over-month comparisons
• Highlight significant changes
• Keep it concise (1-2 pages)

For Engineering Teams¶

• Include detailed PR and issue data
• Show individual repository health
• List action items
• Weekly frequency

For OSPOs¶

• Track contributor diversity
• Monitor external contributions
• Compare with industry benchmarks
• Include all organizations