Automate Your GitHub Work Reports with gh-weekly: The AI-Powered Weekly Digest Generator

Why Developers Need Automated Progress Reporting

Every Friday, countless developers face the same challenge: translating a week’s worth of GitHub commits into a meaningful progress report. How often have you:

• Scrolled through dozens of commits trying to remember their significance?
• Struggled to explain technical work to non-technical stakeholders?
• Wasted valuable development time on administrative reporting?

Code commits ≠ meaningful insights. While GitHub perfectly tracks what changed, it doesn’t articulate why those changes matter. That’s why I created gh-weekly – an open-source tool that transforms your raw commit history into professional, ready-to-share weekly reports using AI.

“The most powerful tool isn’t the one that does the work, but the one that helps you articulate the value of that work.” – Inspired by tech industry wisdom

What Exactly Is gh-weekly?

gh-weekly is a Python command-line tool that analyzes your GitHub commit history and generates structured weekly reports in natural English. Here’s how it works:

graph LR
    A[GitHub Commits] --> B(gh-weekly Collection)
    B --> C[AI Analysis Engine]
    C --> D[Customized Report]
    D --> E[Terminal/File/Clipboard]

Key Capabilities

1. Commit Intelligence

   • Automatically detects all commits from the past week
   • Understands technical context and business impact
   • Transforms “fixed #123 bug” into “resolved checkout flow stability issues”

2. Style Customization

   # Manager-focused reporting
   ./gh-weekly.py "executive summary highlighting business impact"
   
   # Technical deep dive
   ./gh-weekly.py "detailed technical analysis including implementation approach"
   

3. Precision Filtering

   # Focus on core projects
   ./gh-weekly.py --filter "core|main"
   
   # Exclude experimental work
   ./gh-weekly.py --exclude "experimental|prototype"
   

4. AI Service Flexibility

   • Default DeepSeek API integration
   • Compatible with OpenAI, OpenRouter, and other OpenAI-compatible services
   • Supports locally hosted LLM APIs

Getting Started: Installation Guide

System Requirements

Component	Minimum Requirement	Verification Command
Python	3.6+	python --version
GitHub CLI	Latest	gh --version
Terminal	Bash/Zsh compatible	Not applicable

Step-by-Step Setup

1. Install Required Components

   # macOS installation
   brew install gh
   
   # Ubuntu/Debian installation
   sudo apt update && sudo apt install gh
   
   # Authenticate GitHub CLI
   gh auth login
   

2. Configure Python Environment

   # Clone repository
   git clone https://github.com/yourusername/gh-weekly.git
   cd gh-weekly
   
   # Install Python dependencies
   pip install openai
   

3. Set Up AI Service Keys

   # DeepSeek (recommended)
   export DEEPSEEK_API_KEY="your_api_key_here"
   
   # Alternative OpenAI configuration
   export OPENAI_API_KEY="your_openai_key"
   export OPENAI_BASE_URL="https://api.openai.com/v1"
   export OPENAI_MODEL="gpt-4"
   

Practical Usage Scenarios

Scenario 1: Basic Weekly Summary

./gh-weekly.py

Sample output:

📊 This week's key developments:
1. Authentication system upgraded to OAuth 2.1 standard
2. Order processing throughput increased by 40%
3. Fixed concurrency issues in payment API

Scenario 2: Stakeholder Reporting

./gh-weekly.py "business impact focus, non-technical language"

Output characteristics:

• Connects technical work to business objectives
• Quantifies impact in business terms
• Uses accessible language for non-technical readers

Scenario 3: Technical Post-Mortem

./gh-weekly.py "include implementation details" --chars 1000

Output characteristics:

• Explains technical decision rationale
• Highlights key algorithmic improvements
• Documents challenges and solutions

Scenario 4: Multi-Repository Management

./gh-weekly.py --filter "payment|auth" --exclude "legacy"

Ideal for:

• Tech leads managing multiple codebases
• Extracting signal from repository noise
• Generating project-specific updates

Scenario 5: Automated Daily Standups

# Scheduled daily report generation
0 9 * * * cd /path/to/gh-weekly && ./gh-weekly.py daily > ~/daily_report.txt

Advanced Customization Techniques

Style Customization Formula

[Tone] + [Focus Area] + [Report Type]

Examples:
"Concise infrastructure update"
"Comprehensive security review"
"In-depth performance analysis"

Filtering Patterns

Pattern Type	Example	Functionality
Inclusion	`”core	main”`
Exclusion	--exclude "test"	Omits repositories with “test” in name
RegEx	"feat(.*)"	Matches feature branches

Length Control Methods

# Standup-length report (under 300 characters)
./gh-weekly.py --chars 300

# Detailed weekly summary (800-1000 characters)
./gh-weekly.py --chars 1000

Supported AI Services Comparison

Service Provider	Configuration Method	Strengths	Best Use Cases
DeepSeek	export DEEPSEEK_API_KEY	Optimized for technical content	Daily/weekly summaries
OpenAI	export OPENAI_API_KEY	Handles complex scenarios	Technical deep dives
OpenRouter	Custom base URL	Multiple model support	Style experimentation
Local LLMs	Custom API endpoint	Data privacy	Sensitive projects

Real-World Implementation Examples

Case Study: Frontend Team Reporting

Challenge:

• 3+ hours weekly preparing stakeholder updates
• Technical explanations confusing product team

Solution:

./gh-weekly.py "user impact focus, non-technical terminology"

Results:

• Reporting time reduced to 15 minutes
• Product team engagement increased 40%

Case Study: Open Source Maintenance

Challenge:

• Contributors across 12 repositories
• Release notes took days to compile

Solution:

./gh-weekly.py --filter "core|plugin" --exclude "docs"

Results:

• Release note draft generated automatically
• Contributor recognition improved

Frequently Asked Questions

Q1: Does this expose my private code?

Absolutely not. gh-weekly:

• Accesses only commit messages (not code content)
• Works with public and private repositories
• Supports self-hosted AI solutions

Q2: Is GitLab/Bitbucket supported?

Currently supports GitHub exclusively because:

1. Uses GitHub CLI for standardized access
2. GitHub hosts majority of open-source projects
3. Enterprise Edition will add multi-platform support

Q3: How accurate are the reports?

Verification safeguards:

1. Original commits available via --raw flag
2. Source references included (e.g., #2622)
3. Optional human review step

Q4: What time period does it cover?

Default configuration:

• Last 7 days (ideal for weekly reporting)
• Custom date ranges coming in v1.2
• Historical analysis in Enterprise Edition

Technical Architecture

Data Processing Workflow

sequenceDiagram
    participant U as User
    participant C as gh-weekly
    participant G as GitHub
    participant A as AI Service
    
    U->>C: Execute command
    C->>G: Request commits via gh CLI
    G-->>C: Return commit data
    C->>C: Apply filters/transformations
    C->>A: Send structured data
    A-->>C: Return generated report
    C->>U: Output final report

AI Analysis Engine

1. Contextual Understanding

   • Recognizes technical terms (e.g., “Raft-Log”)
   • Maps commits to project components

2. Value Extraction Logic

   # Simplified logic example
   def categorize_commit(message):
       if "feat" in message: 
           return f"Feature: {extract_description(message)}"
       elif "perf" in message:
           return f"Optimization: {extract_description(message)}"
   

3. Adaptive Styling

   • Dynamically adjusts terminology complexity
   • Maintains consistent voice across reports

Start Automating Your Reporting Today

Immediate Action Plan

1. Install and Test

   git clone https://github.com/yourusername/gh-weekly.git
   cd gh-weekly
   ./gh-weekly.py
   

2. Configure Your Environment

   # Permanent environment setup (Linux/macOS)
   echo 'export DEEPSEEK_API_KEY="your_key"' >> ~/.bashrc
   
   # Schedule weekly reports (Fridays at 5 PM)
   (crontab -l ; echo "0 17 * * 5 cd /path/to/gh-weekly && ./gh-weekly.py > weekly_report.md") | crontab -
   

3. Join Our Community

   • Submit issues and feature requests
   • Contribute filter plugins
   • Share report templates

“The most productive developers aren’t those who write the most code, but those who best articulate the value of their code.” – Inspired by software industry principles

Stop manually translating commits into reports. Let gh-weekly transform your GitHub activity into professional progress updates, giving you more time for what matters – building great software.