An advanced, performance-optimized CLI utility designed for GitHub maintainers. It fetches, analyzes, and manages pull requests across hundreds of repositories with ease.
- 🔍 Deep PR Analysis: Automatically detects merge conflicts in open pull requests by inspecting repository internals.
- 🛠️ Interactive Cleanup & Management: Close conflicted PRs or approve and merge target PRs directly from the terminal. Supports individual confirmation or "Yes to All" ([y/N/a]).
- 🔀 Automated Approval & Conflict-Safe Merge: Automatically review, approve, and merge pull requests matching a submitting user and title phrase—strictly ensuring merge conflicts are detected and skipped.
- ⚡ Intelligent Caching:
- 24-hour TTL: Local JSON caching of repos, PR lists, and deep details.
- Auto-Sync: Automatically invalidates local cache when you close or merge a PR through the tool.
- Zero-PR Optimization: Correctly caches repositories with no PRs to maximize speed.
- ⏱️ Progress & ETA Monitoring: Real-time tracking of processing progress, elapsed time, and dynamic ETA calculation.
- 📄 Full Pagination: Seamlessly handles accounts with massive repository counts and deep PR histories.
- 📂 Fork Filtering: Automatically ignores forked repositories by default to focus on original content.
git clone https://github.com/ishandutta2007/manage-github-pull-requests.git
cd manage-github-pull-requests
pip install -r requirements.txtCreate a .env file in the root directory:
ADMIN_TOKEN=your_github_fine_grained_patTo enable the Interactive Cleanup & Management features, your PAT needs Read and Write access for:
- Go to Settings: GitHub Fine-grained Tokens
- Pull requests:
Read and Write(Required for reviews, merges, and closures) - Issues:
Read and Write(Required for posting closure comments) - Contents:
Read and Write(Required for merging pull requests into repositories)
The tool suite includes four specialized scripts for repository maintenance.
Scans all repositories and identifies open PRs that cannot be merged due to conflicts.
| Goal | Command |
|---|---|
| Default Run | python fetch_prs_and_close_conflicting.py |
| Target Owner | python fetch_prs_and_close_conflicting.py <username> |
| Include Forks | python fetch_prs_and_close_conflicting.py --include-forks |
Scans repositories and identifies open PRs submitted by a specific user (e.g., to clean up bot spam or specific contributors).
| Goal | Command |
|---|---|
| Standard Run | python fetch_prs_and_close_from_user.py --target-user <username> |
| Custom Owner | python fetch_prs_and_close_from_user.py --owner <org> --target-user <bot> |
Scans repositories and identifies open PRs whose title starts with a specific string prefix.
| Goal | Command |
|---|---|
| Standard Run | python fetch_prs_and_close_by_title_prefix.py --title-prefix "<prefix>" |
| Custom Owner | python fetch_prs_and_close_by_title_prefix.py --owner <org> --title-prefix "[WIP]" |
4. User & Title Phrase Approve and Merge (fetch_prs_and_approve_and_merge_from_user_with_a_certain_title.py)
Scans repositories and filters PRs matching both the submitting user ID and a title phrase/subtext. It submits an approving review and safely merges the PR provided there is no merge conflict.
| Goal | Command |
|---|---|
| Standard Run | python fetch_prs_and_approve_and_merge_from_user_with_a_certain_title.py --target-user <username> --title-phrase "<phrase>" |
| Using Aliases | python fetch_prs_and_approve_and_merge_from_user_with_a_certain_title.py --user-id <username> --phrase "<phrase>" |
| Custom Owner & Squash Merge | python fetch_prs_and_approve_and_merge_from_user_with_a_certain_title.py --owner <org> --target-user <bot> --title-phrase "version bump" --merge-method squash |
| Include Forks & Auto-Confirm | python fetch_prs_and_approve_and_merge_from_user_with_a_certain_title.py --target-user <username> --title-phrase "<phrase>" --include-forks -y |
All scripts support an interactive confirmation loop when candidate PRs are identified:
y: Execute the action (close, or approve & merge if no conflict).N: Skip this PR (Default).a: Yes to All. Automatically process all remaining identified PRs in the session.
The tool maintains a structured cache in the .cache/ directory:
repos/: List of user repositories.prs/: List of PRs per repository.pr_details/: Deep metadata for specific PRs (used for conflict detection).
Note: Closing or merging a PR via the tool triggers an immediate clear_cache() for that repository and PR, ensuring your next run reflects the updated state.
.
├── .cache/ # Multi-layer JSON cache
├── .env # Private GitHub token
├── github_tool/ # Core library modules
│ ├── api.py # REST API calls (reviews, merges, PRs)
│ ├── cache.py # Cache storage and expiration
│ ├── config.py # Environment and configuration
│ └── core.py # Repository retrieval logic
├── fetch_prs_and_approve_and_merge_from_user_with_a_certain_title.py # Filter, approve & merge clean PRs by author and title phrase
├── fetch_prs_and_close_by_title_prefix.py # Filter & close PRs by title prefix
├── fetch_prs_and_close_conflicting.py # Detect & close conflicting PRs
├── fetch_prs_and_close_from_user.py # Filter & close PRs by author
├── tests/ # Test suite
├── requirements.txt # Dependencies
└── README.md # Documentation
Distributed under the MIT License. See LICENSE for more information.
Made with ❤️ for efficient GitHub maintenance.