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

2. Clone this repository:

git clone https://github.com/d-oit/github-repo-cleanup.git
cd github-repo-cleanup

3. 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

2. 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

2. Override environment settings via command line:

python -m ghcleanup --min-age 12 --min-inactive 90

3. 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 .

2. Run linter:

uv pip install ruff
ruff check .

3. Run type checker:

uv pip install mypy
mypy .

4. 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

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.