git-contribution-stats

GitHub Activity Report ⚡

A high-performance library to generate activity reports for GitHub App installations. This library collects statistics about commits and pull requests across all repositories accessible by your GitHub App.

🚀 Key Features

• ⏱️ Timeout Controls: Individual and global timeouts to prevent Lambda timeouts
• 🛡️ Circuit Breakers: Skip large installations that cause performance issues
• 🎯 Selective Processing: Target specific installations or exclude problematic ones
• 🔄 Error Recovery: Continue processing even when individual installations fail
• 📊 Detailed Monitoring: Progress callbacks and comprehensive error reporting
• ⚡ Performance Optimized: Limit repositories and branches for faster execution

Installation

npm install git-contribution-stats

🎯 Quick Start

Basic Usage

import { generateGitHubReport } from 'git-contribution-stats'

const report = await generateGitHubReport({
  app_id: 123456,
  private_key: 'your-private-key',
  days_to_look_back: 7
});

console.log(report.summary);
console.log(`Success: ${report.success}`);
console.log(`Processed: ${report.processed_installations}/${report.total_installations}`);

Lambda-Optimized (Conservative Mode)

const report = await generateGitHubReport({
  app_id: 123456,
  private_key: 'your-private-key',
  days_to_look_back: 3,
  
  // Timeout controls
  timeout_per_installation: 15000,      // 15s per installation
  max_total_timeout: 45000,             // 45s total
  
  // Performance limits
  max_repositories_per_installation: 20,
  max_branches_per_repository: 50,
  
  // Error handling
  continue_on_error: true,
  partial_results_on_timeout: true,
  
  // Skip problematic installations
  exclude_installations: ['large-org'],
  priority_mode: 'smallest_first'
});

Background Jobs (Full Mode)

const progressCallback = {
  onInstallationStart: (installation, index, total) => {
    console.log(`Processing ${index}/${total}: ${installation.account.login}`)
  },
  onTimeout: (installation, elapsed) => {
    console.log(`⚠️ ${installation.account.login} timed out after ${elapsed}ms`)
  }
}

const report = await generateGitHubReport({
  app_id: 123456,
  private_key: 'your-private-key',
  days_to_look_back: 7,
  timeout_per_installation: 120000,     // 2min per installation
  continue_on_error: true,
  retry_failed_installations: 2
}, progressCallback);

📋 Configuration Options

interface GitHubActivityConfig {
  // Required
  app_id: number
  private_key: string
  
  // Basic options
  days_to_look_back?: number              // Default: 7
  logger?: Logger
  
  // ⏱️ Timeout controls
  timeout_per_installation?: number       // Timeout per installation (ms)
  max_total_timeout?: number             // Global timeout (ms)
  
  // 🛡️ Performance filters
  max_repositories_per_installation?: number
  max_branches_per_repository?: number
  skip_large_installations?: boolean
  installation_size_threshold?: number
  
  // 🎯 Selective processing
  target_installations?: string[]         // Process only these
  exclude_installations?: string[]        // Skip these
  priority_mode?: 'smallest_first' | 'largest_first' | 'sequential'
  
  // 🔄 Error handling
  continue_on_error?: boolean            // Default: false
  retry_failed_installations?: number    // Default: 0
  partial_results_on_timeout?: boolean   // Default: false
}

📊 Progress Monitoring

const progressCallback = {
  onInstallationStart: (installation, index, total) => {
    console.log(`🚀 Starting ${index}/${total}: ${installation.account.login}`)
  },
  onInstallationComplete: (installation, stats) => {
    console.log(`✅ Completed: ${installation.account.login}`)
  },
  onInstallationError: (installation, error) => {
    console.log(`❌ Error: ${installation.account.login} - ${error.message}`)
  },
  onTimeout: (installation, elapsed) => {
    console.log(`⏱️ Timeout: ${installation.account.login} after ${elapsed}ms`)
  }
}

📈 Report Data Structure

Enhanced Result Format

interface GitHubReportResult {
  success: boolean                    // Overall success
  total_installations: number         // Total installations found
  processed_installations: number     // Successfully processed
  failed_installations: string[]      // Failed installation names
  partial_timeout: boolean           // Whether global timeout occurred
  execution_time: number             // Total execution time (ms)
  summary: string                    // Formatted text report
  detailed_results: (InstallationStats | InstallationError)[]
  errors: Array<{                    // Detailed error log
    installation_id: string
    error: string
    timestamp: number
  }>
}

Example Output

📊 Statistics for my-org (Organization) - Last 3 days:

👤 user1 (ID: 12345):
  Total: 15 commits, 3 PRs opened, 2 PRs closed
  Contributions by repository:
    - repo1: 10 commits, 2 PRs opened, 1 PRs closed
    - repo2: 5 commits, 1 PRs opened, 1 PRs closed

� Common Use Cases

1. AWS Lambda (60s timeout)

const report = await generateGitHubReport({
  app_id: 123456,
  private_key: key,
  days_to_look_back: 1,
  timeout_per_installation: 12000,      // 12s per installation
  max_total_timeout: 50000,             // 50s total (safety margin)
  max_repositories_per_installation: 10,
  exclude_installations: ['huge-org'],
  continue_on_error: true,
  partial_results_on_timeout: true
});

2. Skip Large Organizations

const report = await generateGitHubReport({
  app_id: 123456,
  private_key: key,
  skip_large_installations: true,
  installation_size_threshold: 50,      // Skip if >50 repos
  continue_on_error: true
});

3. Process Specific Organizations Only

const report = await generateGitHubReport({
  app_id: 123456,
  private_key: key,
  target_installations: ['my-org', 'partner-org'],
  priority_mode: 'smallest_first'
});

4. High Availability Mode

const report = await generateGitHubReport({
  app_id: 123456,
  private_key: key,
  continue_on_error: true,
  retry_failed_installations: 2,
  timeout_per_installation: 30000
});

🔍 Troubleshooting

Problem: Lambda timeouts on large installations Solution: Use conservative mode with timeouts and filters

Problem: Some installations have too many repositories Solution: Use max_repositories_per_installation and skip_large_installations

Problem: Need to process only specific organizations Solution: Use target_installations or exclude_installations

Problem: Want to continue even if some installations fail Solution: Set continue_on_error: true and partial_results_on_timeout: true

🏃‍♂️ Running Locally

npx ts-node src/run.ts

Create .env file:

GITHUB_APP_ID=123456
GITHUB_PRIVATE_KEY_PATH=./path/to/private-key.pem

Running Locally

run on terminal:

```npx ts-node src/run.ts````

.env:

GITHUB_APP_ID=
GITHUB_PRIVATE_KEY_PATH=

License

MIT