Skip to content

QuantEcon/action-weekly-report

BranchesTags

Repository files navigation

QuantEcon Weekly Report Action

CI

A powerful GitHub Action that generates comprehensive activity reports across GitHub organizations. Perfect for tracking team productivity, repository health, and development trends across any time period.

🎯 Features

  • 📊 Comprehensive Analytics: Issues, PRs, commits, and activity summaries
  • 🔗 Clickable Metrics: Numbers > 0 link directly to GitHub search results for quick navigation
  • 📝 Comment Summary Template: Auto-generates an editable highlights template with merged PR details and labels
  • ✨ Curated Highlights: Optional theme-grouped, noise-suppressed highlights.md with an LLM-drafted narrative — see docs/highlights.md
  • 🗂️ Structured Data Export: Every run emits report-data.json for downstream tooling — see docs/report-data-schema.md
  • 🌐 External Repository Tracking: Monitor repositories outside your primary organization
  • ⚡ Smart Activity Detection: Captures ALL repository activity (commits, issues, PRs, updates) with intelligent filtering
  • 🔄 Complete Coverage: Handles organizations with hundreds of repositories via pagination
  • 🛡️ Rate Limit Resilient: Built-in retry logic, token validation, and configurable delays
  • 💻 CLI Support: Run locally or in CI/CD with full command-line interface
  • 🎛️ Highly Configurable: Exclude repositories, custom date ranges, flexible reporting
  • ✅ Validated Accuracy: All metrics cross-validated against GitHub API

What It Tracks

Activity metrics by repository:

  • Current open issues (snapshot)
  • Issues opened/closed (in period)
  • PRs opened/merged (in period)
  • Direct commits (in period)
  • Activity summaries

New in v2.0: Enhanced tracking for organizations with >100 repositories, post-processing to exclude repos with zero activity, and comprehensive CLI support.

See documentation for detailed information.

Usage

As a GitHub Action

Recommended: Use the floating @v2 tag to automatically get the latest v2.x.x features and fixes:

- name: Generate activity report
  uses: QuantEcon/action-weekly-report@v2  # Always uses latest v2.x.x release
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}
    organization: 'QuantEcon'
    exclude-repos: 'lecture-.*\.notebooks'  # Supports regex patterns
    track-external-repos: 'executablebooks/sphinx-proof,executablebooks/sphinx-exercise'  # Track external repos
    api-delay: '1'  # Add 1 second delay between API calls to avoid rate limits

For specific versions: Pin to an exact release (e.g., @v2.1.0, @v2.0.0) if you need version stability.

Command Line Usage (Local Development)

Run the script directly to generate reports locally - perfect for development, testing, or ad-hoc reports:

# Show available options
./generate-report.sh --help

# Basic usage (last 7 days)
export GITHUB_TOKEN=ghp_xxxxx
./generate-report.sh

# Or use command line argument
./generate-report.sh --token=ghp_xxxxx

# Report from specific date to today
./generate-report.sh --token=ghp_xxxxx --start=2025-10-01

# Custom date range (e.g., monthly report)
./generate-report.sh --token=ghp_xxxxx --start=2025-10-01 --end=2025-10-31

# Different organization
./generate-report.sh --token=ghp_xxxxx --org=YourOrg

# Custom output filename
./generate-report.sh --token=ghp_xxxxx --output=monthly-report.md

# Exclude specific repositories
./generate-report.sh --token=ghp_xxxxx --exclude=repo1,repo2

# Exclude repositories using regex patterns (e.g., all .notebooks repos)
./generate-report.sh --token=ghp_xxxxx --exclude="lecture-.*\.notebooks"

# Track external repositories (from other organizations)
./generate-report.sh --token=ghp_xxxxx --track-external-repos=executablebooks/sphinx-proof,executablebooks/sphinx-exercise

# Generate report with comment summary template
./generate-report.sh --token=ghp_xxxxx --summary-template

# Custom summary template output file
./generate-report.sh --token=ghp_xxxxx --summary-template --summary-template-file=raw-merged-prs.md

# View the generated report
cat report.md

What happens in CLI mode:

  • ✅ Fetches data from GitHub API (read-only)
  • ✅ Generates markdown file locally (default: report.md)
  • ❌ Does NOT create issues or post anything
  • ❌ Does NOT modify your repositories

Available Options:

  • --token=TOKEN - GitHub token for API access (read-only, see Token Usage)
  • --org=ORG - Organization name (default: QuantEcon)
  • --start=YYYY-MM-DD - Start date for report (end date defaults to today)
  • --end=YYYY-MM-DD - End date for report (use with --start for custom range)
  • --output=FILE - Output filename (default: report.md)
  • --exclude=REPOS - Comma-separated list of repos or regex patterns to exclude (e.g., repo1,lecture-.*\.notebooks)
  • --track-external-repos=LIST - Comma-separated list of external repos to track (format: org/repo, e.g., executablebooks/sphinx-proof,executablebooks/sphinx-exercise)
  • --delay=SECONDS - Delay between API calls (default: 0)
  • --summary-template - Generate a comment summary template with merged PR details
  • --summary-template-file=FILE - Output filename for summary template (default: comment-template.md)
  • --highlights - Generate a curated highlights.md (themes + noise rollup) — see docs/highlights.md
  • --highlights-file=FILE - Output filename for highlights (default: highlights.md)
  • --llm-summary - With --highlights, draft 1-sentence theme summaries via Claude (requires ANTHROPIC_API_KEY)
  • --llm-model=MODEL - Claude model id (default: claude-sonnet-4-6)
  • --debug - Enable verbose debug output

The report is saved to report.md (or your specified output file) in the current directory.

Inputs

Input Description Required Default
github-token GitHub token with access to the organization Yes -
organization GitHub organization name No QuantEcon
exclude-repos Comma-separated list of repository names or regex patterns to exclude (e.g., repo1,lecture-.*\.notebooks) No ''
track-external-repos Comma-separated list of external repositories to track (format: org/repo, e.g., executablebooks/sphinx-proof,executablebooks/sphinx-exercise) No ''
api-delay Delay in seconds between API calls to avoid rate limits (0 = no delay) No 0
summary-template Generate a comment summary template with merged PR details (true/false) No false
summary-template-file Output filename for the comment summary template No comment-template.md
highlights Generate a curated highlights.md via tools/highlights.py (true/false) No false
highlights-file Output filename for curated highlights No highlights.md
llm-summary With highlights, draft 1-sentence theme summaries via Claude (requires ANTHROPIC_API_KEY) No false
llm-model Claude model id used for the LLM narrative pass No claude-sonnet-4-6
debug Enable verbose debug output (true/false) No false

Outputs

Output Description
report-content The full generated report content
report-summary A brief summary of the report metrics
comment-template The generated comment summary template content (when summary-template is enabled)
highlights The generated curated highlights content (when highlights is enabled)

Every run also writes a report-data.json file alongside the markdown report. See docs/report-data-schema.md for the schema.

How It Works

What This Action Does

  1. Fetches repository data from GitHub API (read-only, with full pagination support)
  2. Generates a markdown report file (default: report.md)
  3. Outputs report content for downstream workflow steps

Key Improvements in v2.0:

  • Handles organizations with >100 repositories (full pagination)
  • Accurate date range filtering (respects both start and end dates)
  • Post-processing removes repos with zero activity (cleaner reports)
  • Token validation on startup (fail-fast with clear errors)

This action does NOT:

  • Create GitHub issues (that's handled by your workflow using a separate action)
  • Modify any repositories
  • Post or publish anything

Token Usage

For CLI Mode (Local Development):

  • Token is used to read organization data via GitHub API
  • No issues are created - you just get a markdown file
  • Same permissions as action mode (read-only)

For Action Mode (Automated Workflows):

  • Token is used to read organization data
  • Report is saved to report.md (default)
  • Your workflow can then post the report as an issue using a separate action

Required Permissions:

  • ✅ repo - Read repository data
  • ✅ read:org - Read organization data

Not Required:

  • ❌ Issue creation permissions (unless your workflow posts issues separately)

Example Workflow

jobs:
  weekly-report:
    runs-on: ubuntu-latest
    steps:
      # Step 1: Generate the report, comment summary template, and curated highlights
      - name: Generate weekly report
        uses: QuantEcon/action-weekly-report@v2
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          organization: 'QuantEcon'
          track-external-repos: 'executablebooks/sphinx-proof,executablebooks/sphinx-exercise'
          summary-template: 'true'
          highlights: 'true'
          llm-summary: 'true'  # optional — drafts theme narratives via Claude
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}  # only needed when llm-summary: 'true'

      # Step 2: Create issue from report
      - name: Create issue from report
        id: create-issue
        uses: peter-evans/create-issue-from-file@v4
        with:
          title: Weekly Activity Report
          content-filepath: weekly-report.md
          labels: report, automated

      # Step 3: Post the curated highlights as the first comment
      - name: Post curated highlights
        if: hashFiles('highlights.md') != ''
        uses: peter-evans/create-or-update-comment@v4
        with:
          issue-number: ${{ steps.create-issue.outputs.issue-number }}
          body-path: highlights.md

How it works: Step 1 generates weekly-report.md (main table), report-data.json (structured data), comment-template.md (raw merged-PR dump for hand-curation), and highlights.md (curated theme view, optionally LLM-narrated). Step 2 creates the issue. Step 3 posts the curated highlights as the first comment — ready for a maintainer to edit or post as-is.

Note: The action outputs to weekly-report.md by default. In CLI mode, it uses report.md. report-data.json is always emitted (no flag required) and follows the same name (weekly-report-data.json in Action mode, report-data.json in CLI mode).

Report Format

The generated report includes a summary table with activity metrics and totals across all repositories. Only repositories with activity in the reporting period are included.

Interactive Hyperlinks: Metrics greater than 0 are automatically formatted as clickable links that take you directly to the filtered GitHub results. For example, clicking "7" shows the 7 merged PRs for that period. Only 0 values display as plain text.

External Repositories: When tracking external repos with track-external-repos, they appear in a separate "External Repositories" section below the main organization table. Each section has independent totals. External repos are displayed with their full org/repo format for clarity.

See Hyperlink Feature Documentation for details and example report.

Rate Limiting

For large organizations, use the api-delay parameter to add delays between requests. See documentation for details.

Documentation

Contributing

See CONTRIBUTING.md for development guidelines.

License

MIT - See LICENSE for details.

About

GitHub Action for generating weekly activity reports across GitHub organizations

Topics

github-api documentation analytics reporting quantecon github-action

Resources

Readme

License

MIT license

Contributing

Contributing

Security policy

Security policy
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 8

v2.5.0 Latest
May 21, 2026
+ 7 releases

Sponsor this project

  •  
Learn more about GitHub Sponsors

Packages

 
 
 

Contributors

Languages