Skip to content

README.md

Latest commit

 

History

History
508 lines (365 loc) · 8.93 KB

README.md

File metadata and controls

508 lines (365 loc) · 8.93 KB
Raw

GitHub Weekly Activity Report Bot

GitHub Weekly Activity Report Bot

Generate beautiful weekly engineering reports from GitHub activity.
HTML Reports • Email • Slack • Multi-Repository Support

🚀 Overview

GitHub Weekly Activity Report Bot automatically collects engineering activity from one or more GitHub repositories and generates professional weekly reports.

It fetches commits, pull requests, issues, contributors, and repository metrics using the GitHub REST API, transforms them into clean HTML and plain-text reports, saves them locally, and can optionally deliver them through SMTP email or Slack Incoming Webhooks.

Perfect for:

  • Engineering Managers
  • Team Leads
  • Open Source Maintainers
  • Personal Weekly Progress Reports

✨ Features

📊 Analytics

  • Track commits
  • Track pull requests
  • Track issues
  • Top contributors
  • Average PR merge time
  • Multi-repository aggregation
  • Configurable reporting period

⚡ Automation

  • CLI interface
  • Weekly scheduled execution
  • Cron support
  • Windows Task Scheduler support
  • Local HTML & text report generation

📤 Delivery

  • HTML report
  • Plain-text report
  • SMTP Email
  • Slack Incoming Webhook
  • Local-only mode

🛡 Reliability

  • GitHub API pagination
  • Automatic retry for rate limits
  • YAML configuration
  • Environment variable secrets
  • Structured logging
  • Fully tested with mocked integrations

📸 Demo

Generated HTML Report

🏗 Architecture

                    GitHub Repositories
                              │
                              ▼
                     GitHub REST API
                              │
                    Fetch Repository Data
                              │
                              ▼
                    Activity Aggregator
                              │
          ┌───────────────────┴───────────────────┐
          ▼                                       ▼
   HTML Report Generator                  Text Report Generator
          │                                       │
          └───────────────────┬───────────────────┘
                              ▼
                     Local Output Files
                              │
              ┌───────────────┴───────────────┐
              ▼                               ▼
         SMTP Email                    Slack Webhook

🔄 Workflow

GitHub API
      │
      ▼
Fetch commits, PRs & issues
      │
      ▼
Aggregate statistics
      │
      ▼
Generate HTML & text reports
      │
      ▼
Save locally
      │
      ▼
Optional Email / Slack delivery

💡 Why I Built This

Many teams rely on manual weekly updates or expensive reporting tools.

This project demonstrates how to build a lightweight automation tool that integrates with third-party APIs, processes engineering metrics, and generates professional reports that can be automatically delivered every week.

The project showcases:

  • API Integration
  • Data Aggregation
  • Template Rendering
  • CLI Development
  • Configuration Management
  • Email Automation
  • Slack Integration
  • Testing
  • Software Architecture

📊 Metrics Included

Metric Description
📝 Commits Total commits during the reporting period
🔀 Pull Requests Opened, updated, and merged PRs
🐞 Issues Opened and closed issues
👥 Contributors Top commit authors
⏱ Average Merge Time Mean PR merge duration

⚙️ Quick Start

1. Clone Repository

git clone https://github.com/giabaow/github-weekly-report-bot.git

cd github-weekly-report-bot

2. Create Virtual Environment

python3 -m venv .venv

macOS / Linux

source .venv/bin/activate

Windows

.venv\Scripts\activate

3. Install Dependencies

pip install -r requirements.txt

4. Configure

Copy template files

cp config.example.yaml config.yaml

cp .env.example .env

Add your GitHub Personal Access Token

GITHUB_TOKEN=ghp_your_token_here

Edit config.yaml

repos:
  - "fastapi/fastapi"
  - "your-username/project"

days: 7

delivery:
  method: none

Repository names must use:

owner/repository

Example

fastapi/fastapi

NOT

https://github.com/fastapi/fastapi

5. Generate Your First Report

python report.py run --no-delivery

Generated files

output/report_YYYY-MM-DD.html

output/report_YYYY-MM-DD.txt

📬 Delivery Options

Method Description
none Save locally only
email Send via SMTP
slack Send via Slack
both Email + Slack

📧 Email

Add to .env

SMTP_USER=you@gmail.com

SMTP_PASSWORD=your_app_password

SMTP_FROM=you@gmail.com

Configuration

delivery:
  method: email

  email_to:
    - manager@company.com

💬 Slack

Create an Incoming Webhook.

Add to .env

SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...

Configuration

delivery:
  method: slack

⏰ Scheduling

macOS / Linux

Open cron

crontab -e

Run every Monday at 9:00

0 9 * * 1 cd /full/path/github_report_bot && /full/path/github_report_bot/.venv/bin/python report.py run >> logs/cron.log 2>&1

Windows

Use Task Scheduler

Program

.venv\Scripts\python.exe

Arguments

report.py run

Schedule

Weekly
Monday
09:00

💻 Commands

Command Description
python report.py run Generate and deliver report
python report.py run --no-delivery Generate report locally only
python report.py run --repo fastapi/fastapi --days 3 --no-delivery One-off report
python report.py test-delivery Test Email / Slack delivery
pytest -v Run tests

🔒 Security

  • Secrets stored in .env
  • Never commit credentials
  • GitHub token recommended
  • Supports both public and private repositories
  • Early validation for invalid configuration
  • Automatic handling of GitHub rate limits

📁 Project Structure

github_report_bot/
│
├── app/
│   ├── github_client.py
│   ├── aggregator.py
│   ├── delivery.py
│   ├── config.py
│   └── logger.py
│
├── templates/
│   ├── report.html
│   └── report.txt
│
├── tests/
│
├── output/
│
├── config.example.yaml
├── .env.example
├── requirements.txt
├── report.py
└── README.md

🧪 Testing

Run the full test suite

pytest -v

Tests include

  • GitHub API
  • Pagination
  • Retry logic
  • Aggregation
  • HTML rendering
  • SMTP email
  • Slack delivery
  • Configuration
  • CLI

External services are fully mocked, so no real network calls or credentials are required.

🛠 Tech Stack

Category Technology
Language Python 3.10+
API GitHub REST API
Templates Jinja2
Configuration YAML
Secrets python-dotenv
HTTP requests
Email SMTP
Messaging Slack Incoming Webhooks
Testing pytest
Logging Python logging

🚀 Engineering Highlights

  • REST API Integration
  • Pagination Handling
  • Retry Strategy
  • Configuration Management
  • Template Rendering
  • HTML Report Generation
  • Email Automation
  • Slack Integration
  • CLI Application
  • Modular Architecture
  • Unit Testing
  • Dependency Injection Principles

📈 Future Improvements

  • GitHub Actions integration
  • PDF export
  • Charts & visual analytics
  • GitLab support
  • Microsoft Teams notifications
  • Docker image
  • Web dashboard
  • SQLite history database
  • Report comparison between weeks

⭐ Support

If you found this project useful or interesting, consider giving it a ⭐ on GitHub.

It helps others discover the project and motivates future improvements.