/githubRemoveOldRepos

A tool for safely identifying and cleaning up inactive GitHub repositories based on configurable criteria.

Primary LanguagePythonMIT LicenseMIT

GitHub Repository Cleanup Tool

A tool for safely identifying and cleaning up inactive GitHub repositories based on configurable criteria.

Caution

Remember to use this with caution, as deleting repositories is an irreversible action!

Features

  • 🔍 Smart repository analysis based on multiple criteria

    • Age-based filtering
    • Activity tracking
    • Star/fork/download analysis
    • Dependency checking
    • Resource usage calculation

  • 📊 Comprehensive reporting

    • Markdown formatted reports
    • Deletion impact assessment
    • Resource usage metrics
    • Activity timelines
    • Interactive deletion checklist

  • 🔒 Safety measures

    • Multiple validation checks
    • Protected branch detection
    • Repository archival option
    • Backup before deletion
    • Detailed audit logging

  • 🛠 Advanced capabilities

    • Rate limit handling
    • Batch processing
    • Progress tracking
    • Dry-run mode
    • Environment-based configuration

Prerequisites

  • Python 3.9 or higher
  • uv package manager
  • GitHub Personal Access Token with required permissions:
    • repo - Full repository access
    • delete_repo - For repository deletion
    • read:org - For organization repository access (if needed)

Installation

  1. Install uv package manager:
curl -LsSf https://astral.sh/uv/install.sh | sh
  1. Clone this repository:
git clone https://github.com/d-oit/github-repo-cleanup.git
cd github-repo-cleanup
  1. Create virtual environment and install dependencies:
uv venv
source .venv/bin/activate  # Unix
.venv\Scripts\activate     # Windows
uv pip install -r requirements.txt

Configuration

  1. Copy the example environment file:
cp .env.example .env
  1. Configure your environment variables in .env:
# GitHub Authentication
GITHUB_TOKEN=your_personal_access_token
GITHUB_API_URL=https://api.github.com

# Analysis Criteria
MIN_AGE_MONTHS=6
MIN_INACTIVITY_DAYS=180
IGNORE_STARS=false
IGNORE_FORKS=true

# Safety Settings
DRY_RUN=true
BACKUP_REQUIRED=true
PROTECTED_REPOS=main-repo,docs
MIN_CONFIRMATION_WAIT=30

# Performance Tuning
BATCH_SIZE=50
MAX_CONCURRENT=5
CACHE_TTL=3600

Usage

Basic Usage

Run with dry-run mode (safe, no deletions):

python -m ghcleanup

Advanced Usage

  1. Generate analysis report only:
python -m ghcleanup --report-only
  1. Override environment settings via command line:
python -m ghcleanup --min-age 12 --min-inactive 90
  1. Execute with backup:
python -m ghcleanup --backup --backup-dir ./backups

Safety Features

  • Dry Run Mode: Test without making changes
  • Validation Checks: Multiple safety validations
  • Protected Repos: Prevent deletion of critical repositories
  • Backup Option: Archive repositories before deletion
  • Audit Logging: Detailed logs of all operations

Development

Code Quality

  1. Format code:
uv pip install black
black .
  1. Run linter:
uv pip install ruff
ruff check .
  1. Run type checker:
uv pip install mypy
mypy .
  1. Run tests:
uv pip install pytest
pytest

Architecture

See Architecture Documentation for detailed technical information about:

  • System components
  • Data flow
  • Security considerations
  • Error handling
  • Monitoring and logging

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Commit your changes
  4. Push to the branch
  5. Create a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

  • GitHub API documentation and team
  • Python and its community
  • All contributors to this project

Badges

Python Version Build Status Coverage

Quick Start

# Install dependencies
uv pip install -r requirements.txt

# Run the tool
python -m ghcleanup

API Documentation

See API Documentation for detailed information about available endpoints and usage.

Changelog

See CHANGELOG.md for recent changes and updates.