Repository files navigation README Code of conduct MIT license
GitHub Pull Shark Automation
This tool is designed for educational purposes to understand GitHub automation, CI/CD workflows, and API integration. Use responsibly and in accordance with GitHub's Terms of Service.
Earn Your Pull Shark Badge
Default Bronze Silver Gold
Automate PR creation and merging to unlock all achievement tiers!
What Is Pull Shark Automation?
A powerful Python automation framework that streamlines GitHub Pull Request workflows at scale. Perfect for developers who want to:
Use Case
Benefit
Batch Documentation Updates Update README files across multiple branches
Configuration Management Apply settings changes repository-wide
CI/CD Testing Stress-test your automation pipelines
Achievement Hunting Earn GitHub badges efficiently
Learning & Research Study automation patterns and workflows
Table of Contents
Features
Architecture
Installation
Configuration
Usage
Components
Performance
Security
Troubleshooting
Optimization
Contributing
License
Features
Core Capabilities
Automated PR Creation +- Generate 100-10,000+ PRs Smart Auto-Merge +- Intelligent PR merging Dual Execution Modes +- Sequential & Parallel State Management +- Resume from interruptions Dry Run Mode +- Test without commits
Advanced Features
Multi-Token Rotation +- Automatic token switching Proxy Management +- Built-in scraping & rotation Real-Time Notifications +- Discord & Slack webhooks Rate Limit Handling +- Smart API throttling Exponential Backoff +- Intelligent retry logic
How It Works
Config[ Load Configuration]
Config --> Mode{ Choose Mode}
Mode -->|Sequential| Seq[ main.py
%%{init: {'theme':'dark','themeVariables': {'primaryColor':'#ff6b6b','primaryTextColor':'#fff','primaryBorderColor':'#ff6b6b','lineColor':'#4ecdc4','secondaryColor':'#ffe66d','tertiaryColor':'#a8dadc'}}}%%
Loading
Architecture
System Design Overview
+-----------------------------------------------------------------+
Component Matrix
Component
Role
Performance
Features
main.py Sequential
Stable
Single-thread, persistent
parallel_automation.py Parallel
Fast
Multi-thread, async
git_manager.py Git Ops
Branch, commit, push
github_tool.py API
PR create/merge, limits
token_manager.py Tokens
Multi-token rotation
proxy_manager.py Proxies
Scraping & rotation
notifier.py Alerts
Discord & Slack
logger.py Logs
File & console
Installation
Prerequisites Checklist
Python 3.8 or higher
Step 1: Clone Repository
Download the Code # Clone via HTTPS# Or clone via SSH# Navigate to directorycd Pull-Shark-Automation
Step 2: Install Dependencies
Python Packages # Install all required packages# Or use pip3 on some systems
What Gets Installed:
Package
Purpose
Version
requestsHTTP/API calls
>=2.28.0
aiohttpAsync HTTP client
>=3.8.5
aiofilesAsync file operations
>=23.1.0
gitpythonGit automation
>=3.1.31
beautifulsoup4HTML parsing
>=4.12.0
coloramaTerminal colors
>=0.4.6
scheduleTask scheduling
>=1.2.0
Step 3: Install GitHub CLI
macOS Installation # Using Homebrew# Verify installation
Linux Installation # Debian/Ubuntu| \echo " deb [arch=$( dpkg --print-architecture) " | \> /dev/null# Fedora/RHEL/CentOS# Arch Linux# Verify installation
Windows Installation # Using winget-- id GitHub.cli# Or using Chocolatey# Or using Scoop# Verify installation-- version
Step 4: Authenticate GitHub
Login to GitHub # Start authentication# Follow the interactive prompts:# 1. Choose: GitHub.com# 2. Protocol: HTTPS# 3. Authenticate Git: Yes# 4. Method: Login with a web browser# Verify authentication
Expected Output:
Logged in to github.com as YourUsername
Installation Complete!
Ready to configure? Proceed to Configuration
Configuration
File 1: Main Config (config.json)
{"repo_path" : " ." "base_branch" : " main" "readme_file" : " README.md" "pr_count" : 2000 ,"delay_seconds" : 30 ,"auto_merge" : true ,"dry_run" : false ,"max_retries" : 3 ,"use_free_proxies" : true ,"max_concurrent" : 10 ,"discord_webhook" : " https://discord.com/api/webhooks/YOUR_WEBHOOK_HERE" "slack_webhook" : " https://hooks.slack.com/services/YOUR_WEBHOOK_HERE"
Configuration Reference
Parameter
Type
Default
Description
repo_pathstring
"."Path to your Git repository
base_branchstring
"main"Target branch for PRs
readme_filestring
"README.md"File to modify in each commit
pr_countinteger
2000Total PRs to create
delay_secondsinteger
30Wait time between PRs (sequential)
auto_mergeboolean
trueAutomatically merge created PRs
dry_runboolean
falseTest mode (no actual changes)
max_retriesinteger
3Retry attempts on failure
use_free_proxiesboolean
trueEnable proxy rotation
max_concurrentinteger
10Parallel workers (parallel mode)
discord_webhookstring
""Discord notification URL
slack_webhookstring
""Slack notification URL
File 2: GitHub Tokens (github_tokens.json)
{"tokens" : ["name" : " Primary Token" "token" : " github_pat_11XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" "name" : " Secondary Token" "token" : " github_pat_11XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" "name" : " Backup Token" "token" : " github_pat_11XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
How to Generate GitHub Tokens Step-by-Step Guide:
Navigate to GitHub Settings
Click your profile - Settings
Developer settings - Personal access tokens - Tokens (classic)
Generate New Token
Click "Generate new token (classic)"
Name: Pull Shark Automation
Expiration: 90 days (recommended)
Select Required Scopes
repo - Full control of private repositories
workflow - Update GitHub Action workflows
write:packages - Upload packages
Generate & Copy Token
Click "Generate token"
Add to github_tokens.json
Rate Limits:
Single token: 5,000 requests/hour
Multiple tokens: Rotates automatically for 15,000+/hour
Security Tips:
Never commit tokens to Git
Rotate every 30-90 days
Use fine-grained tokens when possible
Enable 2FA on your account
File 3: Proxies (proxies.txt)
# Free HTTPS proxies (ip:port format)
Finding & Testing Proxies Free Proxy Sources:
Test Proxies:
# Test single proxy# Test with timeout
Type
Reliability
Speed
Cost
Free
Low
Slow
$0
Paid
High
Fast
$10-50/mo
Premium
Very High
Very Fast
$50-200/mo
Recommended Paid Services:
Bright Data - Enterprise gradeSmartproxy - Good balanceOxylabs - Large poolProxy-Cheap - Budget friendly
Optional: Webhook Setup
Discord Webhook Setup Steps:
Open Discord server
Server Settings - Integrations - Webhooks
Click "New Webhook"
Set name: GitHub Bot or similar
Choose target channel
Click "Copy Webhook URL"
Paste into config.json
Webhook Format:
https://discord.com/api/webhooks/1234567890/ABCDEFGHIJKLMNOPQRSTUVWXYZ
Test Webhook:
curl -X POST " YOUR_WEBHOOK_URL" " Content-Type: application/json" ' {"content": "Test message from Pull Shark!"}'
Slack Webhook Setup Steps:
Go to api.slack.com/apps
Create New App - From scratch
App Name: GitHub Automation
Select workspace
Incoming Webhooks - Activate
Add New Webhook to Workspace
Select channel
Copy webhook URL
Paste into config.json
Webhook Format:
https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXX
Test Webhook:
curl -X POST " YOUR_WEBHOOK_URL" " Content-Type: application/json" ' {"text": "Test from Pull Shark!"}'
Configuration Complete!
Next: Usage Guide
Usage
Quick Start Commands
# 1 Basic sequential run# 2 Fast parallel mode (recommended)# 3 Test without creating PRs# 4 Custom PR count# 5 Resume after interruption# Auto-resumes from state.json
Sequential Mode (main.py)
python main.py [OPTIONS]
Best For: Reliability, debugging, small batches (<500 PRs)
Option
Description
Example
--count NOverride PR count
python main.py --count 200
--delay NSeconds between PRs
python main.py --delay 60
--dry-runTest mode (no commits)
python main.py --dry-run
--no-mergeDisable auto-merge
python main.py --no-merge
--resetStart from PR #1
python main.py --reset
--use-proxiesEnable proxy rotation
python main.py --use-proxies
Example Output:
Starting from PR #1
Parallel Mode (parallel_automation.py)
python parallel_automation.py [OPTIONS]
Best For: Speed, large batches (500-10,000 PRs)
Option
Description
Example
--count NNumber of PRs
--count 1000
--concurrent NParallel workers
--concurrent 20
--start NStarting PR number
--start 100
--no-proxyDisable proxies
--no-proxy
--dry-runTest mode
--dry-run
Example Output:
Initializing parallel automation...
Usage Examples
Example 1: First-Time Setup (Bronze Badge) Goal: Earn Bronze Pull Shark Badge (16 PRs)
# Test with dry run first# Run actual automation# Expected time: ~5 minutes
Output:
Starting from PR #1
Example 2: Silver Badge (Parallel Mode) Goal: Earn Silver Pull Shark Badge (128 PRs)
# High-speed parallel mode# Expected time: ~3-5 minutes
Output:
Starting parallel automation
Example 3: Gold Badge (Maximum Speed) Goal: Earn Gold Pull Shark Badge (1024 PRs)
# Ultra-fast mode with 20 workers# Expected time: ~16-20 minutes with 3 tokens
Output:
Initializing parallel automation...
Example 4: Resume After Interruption Scenario: Process interrupted at PR #350
# Check current state# Output: {"last_completed_pr": 350}# Resume from PR #351# Automatically continues from #351
Output:
Resuming from PR #351 (found state.json)
Example 5: Dry Run Testing Goal: Test configuration without creating PRs
python main.py --count 5 --dry-run
Output:
DRY RUN MODE - No actual commits
Pro Tips
Tip 1
Start with --dry-run to test your configuration
Tip 2
Use parallel mode with multiple tokens for maximum speed
Tip 3
State files allow resuming - don't worry about interruptions
Tip 4
Monitor rate limits: gh api rate_limit
Tip 5
Enable proxies for extra speed and reliability
Components Deep Dive
System Architecture Breakdown
1 GitManager (git_manager.py)
Purpose: Handle all Git operations with retry logic and internet connectivity checks
Key Methods:
class GitManager :def __init__ (self , base_branch : str , max_retries : int , logger )def wait_for_internet (self , timeout : int = 10 ) -> bool :"""Wait for stable internet connection""" def run (self , command : List [str ]) -> subprocess .CompletedProcess :"""Execute git command with exponential backoff retry""" def sync_base (self ) -> bool :"""Sync base branch with remote""" def create_branch (self , name : str ) -> bool :"""Create and checkout new branch""" def commit (self , file : str , message : str ) -> bool :"""Stage and commit changes""" def push (self , branch : str ) -> bool :"""Push branch to remote"""
Features:
Exponential Backoff
Retry delays: 5s - 10s - 20s
Internet Check
Validates connection before operations
Auto-Retry
Configurable attempts (default: 3)
Timeout Protection
30-second command timeout
2 GitHubTool (github_tool.py)
Purpose: Wrap GitHub CLI with rate limit management and PR operations
Key Methods:
class GitHubTool :def check_rate_limit (self ) -> Dict :"""Query GitHub API rate limit status""" def create_pr (self , title : str , body : str , head : str ) -> Optional [str ]:"""Create pull request via GitHub CLI""" def merge_pr (self , branch : str ) -> bool :"""Auto-merge pull request"""
Rate Limit Flow:
B{Remaining > 100?}
B -->|Yes| C[Proceed]
B -->|No| D[Calculate Wait Time]
D --> E[Sleep Until Reset]
E --> A
style A fill:#3498db
style C fill:#2ecc71
style D fill:#f39c12
" dir="auto">
%%{init: {'theme':'dark'}}%%
Loading
3 TokenManager (token_manager.py)
Purpose: Manage multiple GitHub tokens with automatic rotation
Rotation Algorithm:
def get_best_token ():""" 1. Filter active tokens 2. Sort by remaining requests (descending) 3. Return token with highest limit 4. Update last_used timestamp 5. Decrement remaining count """
Token Statistics Example:
Token Status Dashboard
4 ProxyManager (proxy_manager.py)
Purpose: Rotate proxies to distribute requests
Rotation Strategy:
# Round-robin with queue proxy1 - proxy2 - proxy3 - proxy1 - ...# Get proxy (auto-rotates) proxy = proxy_queue .get () # Returns proxy1 proxy_queue .put (proxy ) # Re-add to end # Next: proxy2, then proxy3, then proxy1...
Supported Formats:
# Simple proxies "8.219.97.248:9090" "http://47.91.34.69:3128" # Authenticated proxies "http://user:pass@proxy.example.com:8080" "socks5://admin:secret@10.0.0.1:1080"
5 Notifier (notifier.py)
Purpose: Send real-time notifications
Notification Types:
Level
Color
Discord
Use Case
info Blue
5814783
Progress updates
success Green
3066993
PR created/merged
warning Yellow
16776960
Non-critical errors
error Red
15548997
Critical failures
Example Notifications:
# Success notifier .send (" PR #123 created successfully\n " "Branch: automation-123-abc\n " "PR Number: #456" ,"success" # Progress notifier .send (" Progress: 50/100 PRs\n " "Speed: 12.5 PRs/min" ,"info" # Error notifier .send (" PR #75 failed\n " "Error: Network timeout" ,"error"
6 Logger (logger.py)
Purpose: Dual-output logging system
Log Levels:
logger .info (" PR #123 created" ) # General info logger .warning (" Rate limit low" ) # Warnings logger .error (" Failed to push" ) # Errors logger .debug (" Token: abc..." ) # Debug info
Sample Log Output:
2026-02-15 10:22:11 - INFO - Starting automation from PR #1
High-Performance Modules
Turbocharged Async Implementation
The high_performance package provides async-first implementations for maximum throughput and parallel processing . Fully Windows-compatible with proper event loop policies.
Module Structure
high_performance/
Performance Comparison
Metric
Standard
High-Performance
Improvement
PR Speed 1-2 PRs/min
30-50 PRs/min
25x faster
Concurrency Single-thread
10-50 workers
50x
Token Rotation Manual
Automatic
Smart
Proxy Support Static list
Auto-fetch + test
Dynamic
Rate Limit Cached
Live API checks
Real-time
Memory Usage ~50 MB
~300-500 MB
6-10x
Real-World Performance
Test: 1000 PRs with High-Performance Modules
python parallel_automation.py --count 1000 --concurrent 20
Results:
Time: 16 minutes (vs 8+ hours sequential)
1 HighPerformanceGitManager
Key Features:
# Windows-compatible async Git operations async def sync_base (self ) -> bool :"""Fast sync with depth=1 optimization""" async def create_branch (self , name : str ) -> bool :"""Async branch creation""" async def commit (self , file : str , message : str , content : str ) -> bool :"""Single-operation async commit""" async def push (self , branch : str ) -> bool :"""Non-blocking push"""
Windows Optimization:
# Thread pool prevents blocking self .executor = ThreadPoolExecutor (max_workers = 10 )# Run git ops in executor loop = asyncio .get_event_loop ()result = await loop .run_in_executor (self .executor ,lambda : git_operation ()
2 HighPerformanceGitHubTool
Key Features:
Semaphore Control: Limit concurrent API callsSmart Token Selection: Auto-switch on rate limitsProxy Integration: Built-in proxy support
# Concurrency control self .semaphore = asyncio .Semaphore (50 ) # Max 50 concurrent async with self .semaphore :process = await asyncio .create_subprocess_exec (...)
3 HighPerformanceTokenManager
Key Features:
Real-Time Rate Limits: Live API checks every 5 minutesFair Distribution: Shuffle tokens for balanced usageAuto-Refresh: Update stale token status
# Live rate limit check async def check_token_rate_limit_async (self , token ):headers = {'Authorization' : f"token { token ['token' ]} }async with session .get ('https://api.github.com/rate_limit' , headers = headers ):# Get real-time remaining count return remaining , reset_time
4 HighPerformanceProxyManager
Proxy Sources:
sources = [# HTML Table Sources 'https://free-proxy-list.net/' ,'https://www.sslproxies.org/' ,# API/Raw Sources (More Reliable) 'https://api.proxyscrape.com/v2/' ,'https://raw.githubusercontent.com/TheSpeedX/PROXY-List/master/http.txt' ,'https://raw.githubusercontent.com/clarketm/proxy-list/master/proxy-list-raw.txt'
Concurrent Testing:
# Test 50 proxies simultaneously semaphore = asyncio .Semaphore (50 )async def limited_test (proxy ):async with semaphore :return await self .test_proxy (proxy )# Parallel execution results = await asyncio .gather (* [limited_test (p ) for p in proxies ])
Latency-Based Sorting:
# Sort by speed (fastest first) working_proxies .sort (key = lambda x : x .get ("latency" , 999 ))
5 ProxyRefresher
Background Service
# Run in separate terminal
Output:
Proxy Refresher Started
Security & Best Practices
Token Security Checklist
Never commit tokens to Git Add to .gitignore
Use environment variables export GITHUB_TOKEN="ghp_xxx"
Rotate tokens regularly Every 30-90 days
Use fine-grained tokens Limit scope to specific repos
Enable 2FA Extra security layer
Monitor token usage gh api rate_limit
API Rate Limits
GitHub Limits:
Authentication
Requests/Hour
Notes
Unauthenticated
60
Very limited
OAuth Token
5,000
Per token
GitHub App
15,000
Enterprise
Multiple Tokens
15,000+
Rotation
Rate Limit Strategies:
# 1 Token Rotation token = token_manager .get_best_token ()# 2 Monitor Limits rate_info = gh .check_rate_limit ()if rate_info ["remaining" ] < 100 :time .sleep (wait_time )# 3 Exponential Backoff for attempt in range (max_retries ):try :result = api_call ()break except RateLimitError :time .sleep (2 ** attempt )
Proxy Best Practices
[FREE] Free vs Paid Proxies
Feature
Free
Paid
Reliability (20-30%)
(99%+)
Speed Slow
Fast
Security Verified
Support None
24/7
Cost $0
$10-200/mo
Best For Testing
Production
Recommended Paid Services:
Bright Data - Enterprise ($500+/mo)Smartproxy - Balanced ($75/mo)Oxylabs - Premium ($300/mo)Proxy-Cheap - Budget ($10/mo)
Troubleshooting
Common Issues & Solutions
Issue 1: "gh: command not found"
Problem Description GitHub CLI is not installed or not in PATH.
Solution # macOS# Linux (Debian/Ubuntu)&& sudo apt install gh -y# Windows# Verify
Issue 2: "Authentication failed"
Problem Description GitHub CLI not authenticated or token expired.
Solution # Re-authenticate# Or use token directlyecho " YOUR_TOKEN" | gh auth login --with-token# Verify authentication
Issue 3: "API rate limit exceeded"
Problem Description Too many API requests in short time.
Solutions Option 1: Add More Tokens
{"tokens" : ["name" : " Token 1" "token" : " ghp_xxx1" "name" : " Token 2" "token" : " ghp_xxx2" "name" : " Token 3" "token" : " ghp_xxx3"
Option 2: Check Rate Limit
gh api rate_limit# Output shows:# - Remaining requests# - Reset time
Option 3: Increase Delay
{"delay_seconds" : 60
Issue 4: "Failed to push branch"
Problem Description Git push fails due to network or permissions.
Solutions Check 1: Internet Connection
ping github.com
Check 2: Repository Permissions
gh repo view --web# Verify you have write access
Check 3: Branch Protection
gh api repos/OWNER/REPO/branches/main/protection
Check 4: Re-authenticate
gh auth refresh
Issue 5: "No changes to commit"
Problem Description File already contains identical content.
Solutions Solution 1: Reset State
python main.py --reset
Solution 2: Change Target File
{"readme_file" : " CONTRIBUTING.md"
Solution 3: Force Content Change
Add timestamps or unique IDs to each commit.
Enable Debug Mode
# Set environment variableexport LOG_LEVEL=DEBUG# Run with debug logging# Or edit logger.py
Debug Output Example:
DEBUG - Token selected: primary (4850 remaining)
Performance Tips
Speed Optimization Matrix
Strategy
Impact
Difficulty
Implementation
Use Parallel Mode Easy
python parallel_automation.py --concurrent 20
Multiple Tokens Easy
Add 2-3 tokens to github_tokens.json
Enable Proxies Medium
Set "use_free_proxies": true
Reduce Delay Easy
--delay 10 (sequential mode)
Skip Auto-Merge Easy
--no-merge
Use SSD Storage Hard
Run on SSD drive
Resource Optimization
Optimal Settings by Hardware:
System Specs
Workers
Memory
PRs/Hour
Recommended
2 CPU, 4GB RAM
5
~150 MB
~900
Basic
4 CPU, 8GB RAM
10
~300 MB
~1,800
Good
8 CPU, 16GB RAM
20
~600 MB
~3,600
Great
16 CPU, 32GB RAM
40
~1.2 GB
~7,200
Overkill
Monitor Resources:
# CPU & Memory Usage$( pgrep -f parallel_automation) # Disk I/O$( pgrep -f parallel_automation) # Network Stats
Benchmarks
Test 1: Sequential Mode (100 PRs) Configuration:
{"pr_count" : 100 ,"delay_seconds" : 30 ,"auto_merge" : true
Results:
Time: 52 minutes
Test 2: Parallel Mode (1000 PRs, 10 workers) Configuration:
python parallel_automation.py --count 1000 --concurrent 10
Results:
Time: 28 minutes
Test 3: Maximum Speed (1000 PRs, 20 workers, 3 tokens) Configuration:
python parallel_automation.py --count 1000 --concurrent 20
Results:
Time: 16 minutes
Contributing
How to Contribute
# 1 Fork the repository# 2 Clone your forkcd Pull-Shark-Automation# 3 Create feature branch# 4 Make your changes# ... edit files ...# 5 Commit with conventional commits" feat: add amazing feature" # 6 Push to your fork# 7 Create Pull Request" Add amazing feature" " Description..."
Code Style Guide
# Good - Clear, documented, typed def create_pull_request (title : str , body : str , head : str ) -> Optional [str ]:""" Create a pull request via GitHub CLI. Args: title: PR title body: PR description head: Source branch name Returns: PR number as string, or None if failed """ try :result = gh_tool .create_pr (title , body , head )return result except Exception as e :logger .error (f"Failed to create PR: { e } )return None # Bad - Unclear, no types, no docs def createPR (t ,b ,h ):result = gh_tool .create_pr (t ,b ,h )return result
Formatting Tools:
# Auto-format with black* .py# Check style with flake8* .py# Type checking with mypy* .py
Reporting Bugs
Found a bug? Help us fix it!
Steps:
Check existing issues
Create new issue with template
Include:
OS & Python version
Full error message
Steps to reproduce
Expected vs actual behavior
Suggesting Features
Have an idea? We'd love to hear it!
Steps:
Check existing discussions
Open feature request
Describe:
Use case
Proposed solution
Alternatives considered
License
MIT License
MIT License
Acknowledgments
Built With Amazing Tools
Special Thanks
GitHub - For excellent CLI and APIPython Community - For amazing async librariesContributors - Everyone who improved this projectYou - For using Pull Shark Automation!
Support & Community
Star History
Final Words
Unleash the Pull Shark!
If this tool helped you earn your Pull Shark badge, please star the repository!
Made with by developers, for developers
Back to Top
