Pull-Shark-Automation
<div align="center"> # 🦈 GitHub Pull Shark Automation <img src="https://capsule-render.vercel.app/api?type=waving&color=gradient&customColorList=6,11,20&height=180§ion=header&text=Pull%20Shark%20Automation&fontSize=42&fontAlignY=30&animation=twinkling&fontColor=fff" width="100%"/> <p align="center"> <img src="https://readme-typing-svg.demolab.com?font=Fira+Code&size=22&duration=3000&pause=1000&color=36BCF7¢er=true&vCenter=true&width=600&lines=Automate+Your+GitHub+PRs;Sequential+%26+Parallel+Modes;Multi-Token+Management;Smart+Proxy+Rotation;Earn+Pull+Shark+Badge" alt="Typing Animation" /> </p> <p align="center"> <a href="#-features"><img src="https://img.shields.io/badge/Features-Explore-blue?style=for-the-badge&logo=github" alt="Features"/></a> <a href="#-installation"><img src="https://img.shields.io/badge/Install-Quick%20Start-green?style=for-the-badge&logo=python" alt="Install"/></a> <a href="#-usage"><img src="https://img.shields.io/badge/Usage-Guide-orange?style=for-the-badge&logo=readme" alt="Usage"/></a> <a href="#-contributing"><img src="https://img.shields.io/badge/Contribute-Welcome-red?style=for-the-badge&logo=git" alt="Contribute"/></a> </p> <p align="center"> <img src="https://img.shields.io/badge/Python-3.8+-blue.svg?style=for-the-badge&logo=python&logoColor=white" alt="Python"/> <img src="https://img.shields.io/badge/GitHub_CLI-Required-black.svg?style=for-the-badge&logo=github" alt="GitHub CLI"/> <img src="https://img.shields.io/badge/License-MIT-green.svg?style=for-the-badge" alt="License"/> <img src="https://img.shields.io/badge/Platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey?style=for-the-badge" alt="Platform"/> </p> --- ## ⚠️ Educational Purpose Only <p align="center"> <img src="https://img.shields.io/badge/⚠️-Educational_Purpose_Only-red?style=for-the-badge" alt="Educational"/> </p> 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 <div align="center"> <img src="https://github.com/drknzz/GitHub-Achievements/blob/main/Media/Badges/Pull-Shark/PNG/PullShark.png" width="180" alt="Pull Shark Badge"/> <table> <tr> <td align="center"><img src="https://github.com/drknzz/GitHub-Achievements/blob/main/Media/Badges/Pull-Shark/PNG/PullShark.png" width="80"/><br/><b>Default</b><br/>2 PRs</td> <td align="center"><img src="https://github.com/drknzz/GitHub-Achievements/blob/main/Media/Badges/Pull-Shark/PNG/PullShark_Bronze.png" width="80"/><br/><b>Bronze</b><br/>16 PRs</td> <td align="center"><img src="https://github.com/drknzz/GitHub-Achievements/blob/main/Media/Badges/Pull-Shark/PNG/PullShark_Silver.png" width="80"/><br/><b>Silver</b><br/>128 PRs</td> <td align="center"><img src="https://github.com/drknzz/GitHub-Achievements/blob/main/Media/Badges/Pull-Shark/PNG/PullShark_Gold.png" width="80"/><br/><b>Gold</b><br/>1024 PRs</td> </tr> </table> </div> <p align="center"> <i>Automate PR creation and merging to unlock all achievement tiers!</i> </p> </div> --- <div align="center"> ## 🎯 What Is Pull Shark Automation? <img src="https://user-images.githubusercontent.com/74038190/212284158-e840e285-664b-44d7-b79b-e264b5e54825.gif" width="400"/> </div> A **powerful Python automation framework** that streamlines GitHub Pull Request workflows at scale. Perfect for developers who want to: <div align="center"> | 🎯 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 | </div> --- ## 📑 Table of Contents <div align="center"> | [🌟 Features](#-features) | [🏗️ Architecture](#️-architecture) | [📦 Installation](#-installation) | [⚙️ Configuration](#️-configuration) | |:---:|:---:|:---:|:---:| | [🚀 Usage](#-usage) | [🔧 Components](#-components-deep-dive) | [⚡ Performance](#-high-performance-modules) | [🔐 Security](#-security--best-practices) | | [🐛 Troubleshooting](#-troubleshooting) | [📈 Optimization](#-performance-tips) | [🤝 Contributing](#-contributing) | [📄 License](#-license) | </div> --- ## 🌟 Features <div align="center"> <table> <tr> <td width="50%" valign="top"> ### 🎯 Core Capabilities <img src="https://img.shields.io/badge/Automation-Core-blue?style=flat-square" alt="Core"/> ```yaml ✅ 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 ``` </td> <td width="50%" valign="top"> ### 🔧 Advanced Features <img src="https://img.shields.io/badge/Advanced-Pro-green?style=flat-square" alt="Advanced"/> ```yaml ✅ 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 ``` </td> </tr> </table> </div> --- ## 🎬 How It Works <div align="center"> ```mermaid %%{init: {'theme':'dark','themeVariables': {'primaryColor':'#ff6b6b','primaryTextColor':'#fff','primaryBorderColor':'#ff6b6b','lineColor':'#4ecdc4','secondaryColor':'#ffe66d','tertiaryColor':'#a8dadc'}}}%% graph TB Start([🚀 Start Automation]) --> Config[📋 Load Configuration] Config --> Mode{🔀 Choose Mode} Mode -->|Sequential| Seq[📝 main.py<br/>Single Thread] Mode -->|Parallel| Par[⚡ parallel_automation.py<br/>Multi-Thread] Seq --> Git[🔧 Git Operations] Par --> Git Git --> Branch[🌿 Create Branch] Branch --> Commit[💾 Commit Changes] Commit --> Push[📤 Push to Remote] Push --> PR[🎯 Create PR] PR --> AutoMerge{🤖 Auto-merge?} AutoMerge -->|Yes| Merge[✅ Merge PR] AutoMerge -->|No| Next{📊 More PRs?} Merge --> Next Next -->|Yes| Git Next -->|No| Notify[📢 Send Notifications] Notify --> End([🎉 Complete!]) style Start fill:#2ecc71,stroke:#27ae60,stroke-width:3px,color:#fff style End fill:#e74c3c,stroke:#c0392b,stroke-width:3px,color:#fff style PR fill:#3498db,stroke:#2980b9,stroke-width:2px,color:#fff style Merge fill:#f39c12,stroke:#e67e22,stroke-width:2px,color:#fff ``` </div> --- ## 🏗️ Architecture <div align="center"> ### System Design Overview <img src="https://img.shields.io/badge/Architecture-Microservices-blueviolet?style=for-the-badge&logo=architecture" alt="Architecture"/> ``` ┌─────────────────────────────────────────────────────────────────┐ │ 🦈 Pull Shark Automation │ │ Core Orchestration Layer │ └─────────────────────────────────────────────────────────────────┘ │ ┌───────────────┴───────────────┐ │ │ ┌───────▼────────┐ ┌────────▼───────┐ │ 📝 Sequential │ │ ⚡ Parallel │ │ main.py │ │ parallel_*.py │ │ Reliable │ │ Fast & Async │ └───────┬────────┘ └────────┬───────┘ │ │ └──────────────┬───────────────┘ │ ┌──────────────────────┼──────────────────────┐ │ │ │ ┌────▼─────┐ ┌─────▼────┐ ┌──────▼─────┐ │ 🔧 Git │ │ 🐙 GitHub│ │ 🔑 Token │ │ Manager │ │ Tool │ │ Manager │ │ Ops │ │ API Wrap │ │ Rotation │ └────┬─────┘ └─────┬────┘ └──────┬─────┘ │ │ │ └─────────────────────┼──────────────────────┘ │ ┌─────────────────────┼─────────────────────┐ │ │ │ ┌────▼─────┐ ┌────▼─────┐ ┌────▼─────┐ │ 🌐 Proxy │ │ 📢 Notify│ │ 📝 Logger│ │ Rotation │ │ Webhooks │ │ System │ └──────────┘ └──────────┘ └──────────┘ ``` </div> ### 🔑 Component Matrix <div align="center"> | 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 | </div> --- ## 📦 Installation <div align="center"> ### 🚀 Quick Start Guide <img src="https://img.shields.io/badge/Setup_Time-5_Minutes-brightgreen?style=for-the-badge" alt="Setup Time"/> </div> ### Prerequisites Checklist ```bash ✅ Python 3.8 or higher ✅ Git 2.0 or higher ✅ GitHub CLI (gh) ✅ Active GitHub account ✅ Write access to target repository ``` --- ### Step 1️⃣: Clone Repository <details open> <summary><b>📥 Download the Code</b></summary> ```bash # Clone via HTTPS git clone https://github.com/itxashancode/Pull-Shark-Automation.git # Or clone via SSH git clone [email protected]:itxashancode/Pull-Shark-Automation.git # Navigate to directory cd Pull-Shark-Automation ``` </details> --- ### Step 2️⃣: Install Dependencies <details open> <summary><b>🐍 Python Packages</b></summary> ```bash # Install all required packages pip install -r requirements.txt # Or use pip3 on some systems pip3 install -r requirements.txt ``` **📦 What Gets Installed:** | Package | Purpose | Version | |---------|---------|---------| | `requests` | HTTP/API calls | ≥2.28.0 | | `aiohttp` | Async HTTP client | ≥3.8.5 | | `aiofiles` | Async file operations | ≥23.1.0 | | `gitpython` | Git automation | ≥3.1.31 | | `beautifulsoup4` | HTML parsing | ≥4.12.0 | | `colorama` | Terminal colors | ≥0.4.6 | | `schedule` | Task scheduling | ≥1.2.0 | </details> --- ### Step 3️⃣: Install GitHub CLI <details> <summary><b>🍎 macOS Installation</b></summary> ```bash # Using Homebrew brew install gh # Verify installation gh --version ``` </details> <details> <summary><b>🐧 Linux Installation</b></summary> ```bash # Debian/Ubuntu curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | \ sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | \ sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null sudo apt update sudo apt install gh -y # Fedora/RHEL/CentOS sudo dnf install gh -y # Arch Linux sudo pacman -S github-cli # Verify installation gh --version ``` </details> <details> <summary><b>🪟 Windows Installation</b></summary> ```powershell # Using winget winget install --id GitHub.cli # Or using Chocolatey choco install gh # Or using Scoop scoop install gh # Verify installation gh --version ``` </details> --- ### Step 4️⃣: Authenticate GitHub <details open> <summary><b>🔐 Login to GitHub</b></summary> ```bash # Start authentication gh auth login # Follow the interactive prompts: # 1. Choose: GitHub.com # 2. Protocol: HTTPS # 3. Authenticate Git: Yes # 4. Method: Login with a web browser # Verify authentication gh auth status ``` **Expected Output:** ``` ✓ Logged in to github.com as YourUsername ✓ Git operations for github.com configured to use https protocol. ✓ Token: ******************* ``` </details> --- <div align="center"> ### ✅ Installation Complete! <img src="https://user-images.githubusercontent.com/74038190/212284100-561aa473-3905-4a80-b561-0d28506553ee.gif" width="600"/> **Ready to configure? Proceed to [⚙️ Configuration](#️-configuration)** </div> --- ## ⚙️ Configuration <div align="center"> ### 🎛️ Setup Your Automation <img src="https://img.shields.io/badge/Configuration-3_Files-orange?style=for-the-badge" alt="Config"/> </div> --- ### 📋 File 1: Main Config (`config.json`) ```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" } ``` <details> <summary><b>📖 Configuration Reference</b></summary> | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `repo_path` | string | `"."` | Path to your Git repository | | `base_branch` | string | `"main"` | Target branch for PRs | | `readme_file` | string | `"README.md"` | File to modify in each commit | | `pr_count` | integer | `2000` | Total PRs to create | | `delay_seconds` | integer | `30` | Wait time between PRs (sequential) | | `auto_merge` | boolean | `true` | Automatically merge created PRs | | `dry_run` | boolean | `false` | Test mode (no actual changes) | | `max_retries` | integer | `3` | Retry attempts on failure | | `use_free_proxies` | boolean | `true` | Enable proxy rotation | | `max_concurrent` | integer | `10` | Parallel workers (parallel mode) | | `discord_webhook` | string | `""` | Discord notification URL | | `slack_webhook` | string | `""` | Slack notification URL | </details> --- ### 🔑 File 2: GitHub Tokens (`github_tokens.json`) ```json { "tokens": [ { "name": "Primary Token", "token": "github_pat_11XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" }, { "name": "Secondary Token", "token": "github_pat_11XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" }, { "name": "Backup Token", "token": "github_pat_11XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" } ] } ``` <details> <summary><b>🔐 How to Generate GitHub Tokens</b></summary> **Step-by-Step Guide:** 1. **Navigate to GitHub Settings** - Click your profile → Settings - Developer settings → Personal access tokens → Tokens (classic) 2. **Generate New Token** - Click "Generate new token (classic)" - Name: `Pull Shark Automation` - Expiration: `90 days` (recommended) 3. **Select Required Scopes** ✅ - ☑️ `repo` - Full control of private repositories - ☑️ `workflow` - Update GitHub Action workflows - ☑️ `write:packages` - Upload packages 4. **Generate & Copy Token** - Click "Generate token" - ⚠️ Copy immediately (shown only once!) - 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 </details> --- ### 🌐 File 3: Proxies (`proxies.txt`) ```text # Free HTTPS proxies (ip:port format) 8.219.97.248:9090 47.91.34.69:3128 161.35.70.249:8080 165.227.196.37:3128 64.225.4.5:9999 # Authenticated proxies (protocol://user:pass@ip:port) http://username:[email protected]:8080 socks5://admin:[email protected]:1080 ``` <details> <summary><b>🔍 Finding & Testing Proxies</b></summary> **🌐 Free Proxy Sources:** - [free-proxy-list.net](https://free-proxy-list.net/) - Updated hourly - [proxyscrape.com](https://proxyscrape.com/) - API available - [spys.one](https://spys.one/en/) - Global proxies **🧪 Test Proxies:** ```bash # Test single proxy curl -x http://8.219.97.248:9090 https://api.github.com/ # Test with timeout curl -x http://proxy:port --max-time 5 https://api.github.com/ ``` **⚠️ Proxy Reliability:** | 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:** 1. **Bright Data** - Enterprise grade 2. **Smartproxy** - Good balance 3. **Oxylabs** - Large pool 4. **Proxy-Cheap** - Budget friendly </details> --- ### 🔔 Optional: Webhook Setup <details> <summary><b>💬 Discord Webhook</b></summary> **Setup Steps:** 1. Open Discord server 2. Server Settings → Integrations → Webhooks 3. Click "New Webhook" 4. Set name: `GitHub Bot` or similar 5. Choose target channel 6. Click "Copy Webhook URL" 7. Paste into `config.json` **Webhook Format:** ``` https://discord.com/api/webhooks/1234567890/ABCDEFGHIJKLMNOPQRSTUVWXYZ ``` **Test Webhook:** ```bash curl -X POST "YOUR_WEBHOOK_URL" \ -H "Content-Type: application/json" \ -d '{"content": "Test message from Pull Shark!"}' ``` </details> <details> <summary><b>💼 Slack Webhook</b></summary> **Setup Steps:** 1. Go to [api.slack.com/apps](https://api.slack.com/apps) 2. Create New App → From scratch 3. App Name: `GitHub Automation` 4. Select workspace 5. Incoming Webhooks → Activate 6. Add New Webhook to Workspace 7. Select channel 8. Copy webhook URL 9. Paste into `config.json` **Webhook Format:** ``` https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXX ``` **Test Webhook:** ```bash curl -X POST "YOUR_WEBHOOK_URL" \ -H "Content-Type: application/json" \ -d '{"text": "Test from Pull Shark!"}' ``` </details> --- <div align="center"> ### ✅ Configuration Complete! <img src="https://img.shields.io/badge/Status-Ready_to_Run-success?style=for-the-badge" alt="Ready"/> **Next: [🚀 Usage Guide](#-usage)** </div> --- ## 🚀 Usage <div align="center"> ### 🎮 Command Center <img src="https://user-images.githubusercontent.com/74038190/212284136-03988914-d899-44b4-b1d9-4eeccf656e44.gif" width="500"/> </div> --- ### 🏁 Quick Start Commands ```bash # 1️⃣ Basic sequential run python main.py # 2️⃣ Fast parallel mode (recommended) python parallel_automation.py --count 100 --concurrent 10 # 3️⃣ Test without creating PRs python main.py --dry-run # 4️⃣ Custom PR count python main.py --count 500 # 5️⃣ Resume after interruption python main.py # Auto-resumes from state.json ``` --- ### 📘 Sequential Mode (`main.py`) <div align="center"> ```bash python main.py [OPTIONS] ``` <img src="https://img.shields.io/badge/Mode-Sequential-blue?style=for-the-badge" alt="Sequential"/> **⭐ Best For:** Reliability, debugging, small batches (<500 PRs) </div> | Option | Description | Example | |--------|-------------|---------| | `--count N` | Override PR count | `python main.py --count 200` | | `--delay N` | Seconds between PRs | `python main.py --delay 60` | | `--dry-run` | Test mode (no commits) | `python main.py --dry-run` | | `--no-merge` | Disable auto-merge | `python main.py --no-merge` | | `--reset` | Start from PR #1 | `python main.py --reset` | | `--use-proxies` | Enable proxy rotation | `python main.py --use-proxies` | **📊 Example Output:** ``` 🚀 Starting from PR #1 ⏱️ Delay: 30 seconds 🔹 Processing PR #1 ├─ 🌿 Created branch: automation-1-a1b2c3d4 ├─ 💾 Committed changes ├─ 📤 Pushed to remote └─ ✅ PR #12345 created successfully ✅ PR #12345 merged successfully ⏱️ Waiting 30 seconds... 🔹 Processing PR #2 ... ``` --- ### ⚡ Parallel Mode (`parallel_automation.py`) <div align="center"> ```bash python parallel_automation.py [OPTIONS] ``` <img src="https://img.shields.io/badge/Mode-Parallel-red?style=for-the-badge" alt="Parallel"/> **⭐ Best For:** Speed, large batches (500-10,000 PRs) </div> | Option | Description | Example | |--------|-------------|---------| | `--count N` | Number of PRs | `--count 1000` | | `--concurrent N` | Parallel workers | `--concurrent 20` | | `--start N` | Starting PR number | `--start 100` | | `--no-proxy` | Disable proxies | `--no-proxy` | | `--dry-run` | Test mode | `--dry-run` | **📊 Example Output:** ``` 🚀 Initializing parallel automation... 📋 Loaded 3 GitHub tokens 🔍 Fetching proxies... 📦 Total unique proxies collected: 342 ✅ Working proxies: 87 🚀 Starting parallel automation 📈 Progress: 134/200 PRs ✓ Success: 130 ✗ Failed: 4 ⚡ Speed: 45.2 PRs/min 🎉 Automation Complete! ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Total: 200 PRs ✅ Success: 196 (98%) ❌ Failed: 4 (2%) ⚡ Speed: 43.8 PRs/min ⏱️ Time: 4 minutes 34 seconds ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` --- ### 📚 Usage Examples <details> <summary><b>Example 1: First-Time Setup (Bronze Badge)</b></summary> **Goal:** Earn Bronze Pull Shark Badge (16 PRs) ```bash # Test with dry run first python main.py --count 20 --dry-run # Run actual automation python main.py --count 20 --delay 15 # Expected time: ~5 minutes ``` **Output:** ``` 🚀 Starting from PR #1 ⏱️ Delay: 15 seconds ✅ PR #1-20 created successfully 🎉 Bronze Pull Shark Badge unlocked! ``` </details> <details> <summary><b>Example 2: Silver Badge (Parallel Mode)</b></summary> **Goal:** Earn Silver Pull Shark Badge (128 PRs) ```bash # High-speed parallel mode python parallel_automation.py --count 150 --concurrent 15 # Expected time: ~3-5 minutes ``` **Output:** ``` 🚀 Starting parallel automation 📈 150/150 ✓ 147 ✗ 3 ⚡ 42.5 PRs/min 🎉 Silver Pull Shark Badge unlocked! ⏱️ Completed in 3 minutes 32 seconds ``` </details> <details> <summary><b>Example 3: Gold Badge (Maximum Speed)</b></summary> **Goal:** Earn Gold Pull Shark Badge (1024 PRs) ```bash # Ultra-fast mode with 20 workers python parallel_automation.py \ --count 1024 \ --concurrent 20 # Expected time: ~16-20 minutes with 3 tokens ``` **Output:** ``` 🚀 Initializing parallel automation... 📋 Loaded 3 tokens 🌐 Working proxies: 87 📈 1024/1024 ✓ 982 ✗ 42 ⚡ 62.5 PRs/min 🎉🎉🎉 GOLD PULL SHARK UNLOCKED! 🎉🎉🎉 ⏱️ Completed in 16 minutes 23 seconds ``` </details> <details> <summary><b>Example 4: Resume After Interruption</b></summary> **Scenario:** Process interrupted at PR #350 ```bash # Check current state cat state.json # Output: {"last_completed_pr": 350} # Resume from PR #351 python main.py --count 500 # Automatically continues from #351 ``` **Output:** ``` 🔄 Resuming from PR #351 (found state.json) ⏱️ Remaining: 150 PRs 🔹 Processing PR #351 ... ``` </details> <details> <summary><b>Example 5: Dry Run Testing</b></summary> **Goal:** Test configuration without creating PRs ```bash python main.py --count 5 --dry-run ``` **Output:** ``` 🔍 DRY RUN MODE - No actual commits 🔹 PR #1 Simulation 📝 Would create branch: automation-1-abc123 📝 Would modify: README.md 📝 Would commit: "Automated update #1" 📝 Would push to: origin/automation-1-abc123 📝 Would create PR with title: "Automated PR #1" ✅ Simulation successful 🔹 PR #2 Simulation ... ✅ All 5 PRs simulated successfully ``` </details> --- <div align="center"> ### 💡 Pro Tips <table> <tr> <td>🎯 <b>Tip 1</b></td> <td>Start with <code>--dry-run</code> to test your configuration</td> </tr> <tr> <td>⚡ <b>Tip 2</b></td> <td>Use parallel mode with multiple tokens for maximum speed</td> </tr> <tr> <td>🔄 <b>Tip 3</b></td> <td>State files allow resuming - don't worry about interruptions</td> </tr> <tr> <td>📊 <b>Tip 4</b></td> <td>Monitor rate limits: <code>gh api rate_limit</code></td> </tr> <tr> <td>🌐 <b>Tip 5</b></td> <td>Enable proxies for extra speed and reliability</td> </tr> </table> </div> --- ## 🔧 Components Deep Dive <div align="center"> ### 🏗️ System Architecture Breakdown <img src="https://capsule-render.vercel.app/api?type=rect&color=gradient&customColorList=12&height=2" width="100%"/> </div> --- ### 1️⃣ GitManager (`git_manager.py`) <div align="center"> <img src="https://img.shields.io/badge/Git-Automation-F05032?style=for-the-badge&logo=git&logoColor=white" /> </div> **🎯 Purpose:** Handle all Git operations with retry logic and internet connectivity checks **🔑 Key Methods:** ```python 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:** <table> <tr> <td>⏱️ <b>Exponential Backoff</b></td> <td>Retry delays: 5s → 10s → 20s</td> </tr> <tr> <td>🌐 <b>Internet Check</b></td> <td>Validates connection before operations</td> </tr> <tr> <td>🔁 <b>Auto-Retry</b></td> <td>Configurable attempts (default: 3)</td> </tr> <tr> <td>⏲️ <b>Timeout Protection</b></td> <td>30-second command timeout</td> </tr> </table> --- ### 2️⃣ GitHubTool (`github_tool.py`) <div align="center"> <img src="https://img.shields.io/badge/GitHub-API_Wrapper-181717?style=for-the-badge&logo=github&logoColor=white" /> </div> **🎯 Purpose:** Wrap GitHub CLI with rate limit management and PR operations **🔑 Key Methods:** ```python 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:** ```mermaid %%{init: {'theme':'dark'}}%% graph LR A[Check Rate Limit] --> 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 ``` --- ### 3️⃣ TokenManager (`token_manager.py`) <div align="center"> <img src="https://img.shields.io/badge/Token-Management-4CAF50?style=for-the-badge&logo=key&logoColor=white" /> </div> **🎯 Purpose:** Manage multiple GitHub tokens with automatic rotation **🔄 Rotation Algorithm:** ```python 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 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Token 1 (Primary): 4,850 / 5,000 ⚡ Token 2 (Secondary): 5,000 / 5,000 ✅ Token 3 (Backup): 4,920 / 5,000 ⚡ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Total Available: 14,770 requests Next Reset: 42 minutes ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` --- ### 4️⃣ ProxyManager (`proxy_manager.py`) <div align="center"> <img src="https://img.shields.io/badge/Proxy-Rotation-FF6B6B?style=for-the-badge&logo=shield&logoColor=white" /> </div> **🎯 Purpose:** Rotate proxies to distribute requests **🔄 Rotation Strategy:** ```python # 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:** ```python # Simple proxies "8.219.97.248:9090" "http://47.91.34.69:3128" # Authenticated proxies "http://user:[email protected]:8080" "socks5://admin:[email protected]:1080" ``` --- ### 5️⃣ Notifier (`notifier.py`) <div align="center"> <img src="https://img.shields.io/badge/Notifications-Discord_+_Slack-7289DA?style=for-the-badge&logo=discord&logoColor=white" /> </div> **🎯 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:** ```python # 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`) <div align="center"> <img src="https://img.shields.io/badge/Logging-File_+_Console-FFA500?style=for-the-badge&logo=files&logoColor=white" /> </div> **🎯 Purpose:** Dual-output logging system **📝 Log Levels:** ```python 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 2026-02-15 10:22:15 - INFO - Created branch automation-1-abc123 2026-02-15 10:22:18 - INFO - Committed changes to README.md 2026-02-15 10:22:22 - INFO - Pushed branch automation-1-abc123 2026-02-15 10:22:25 - INFO - Created PR #12345 2026-02-15 10:22:28 - INFO - Merged PR #12345 2026-02-15 10:22:28 - WARNING - Rate limit: 4850 remaining ``` --- ## ⚡ High-Performance Modules <div align="center"> <img src="https://img.shields.io/badge/Async-Powered-00D9FF?style=for-the-badge&logo=python&logoColor=white" /> <img src="https://img.shields.io/badge/Windows-Compatible-0078D6?style=for-the-badge&logo=windows&logoColor=white" /> <img src="https://img.shields.io/badge/Speed-10x_Faster-FF6B6B?style=for-the-badge&logo=lightning&logoColor=white" /> ### 🚀 Turbocharged Async Implementation </div> 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/ ├── __init__.py # 📦 Package exports ├── git_manager.py # 🔧 Async Git operations ├── github_tool.py # 🐙 Async GitHub API ├── token_manager.py # 🔑 Async token rotation ├── proxy_manager.py # 🌐 Async proxy scraping └── proxy_refresher.py # 🔄 Background maintenance ``` --- ### 🚀 Performance Comparison <div align="center"> <table> <thead> <tr> <th>Metric</th> <th>Standard</th> <th>High-Performance</th> <th>Improvement</th> </tr> </thead> <tbody> <tr> <td><b>PR Speed</b></td> <td>1-2 PRs/min</td> <td>30-50 PRs/min</td> <td><span style="color:#2ecc71">⬆️ 25x faster</span></td> </tr> <tr> <td><b>Concurrency</b></td> <td>Single-thread</td> <td>10-50 workers</td> <td><span style="color:#2ecc71">⬆️ 50x</span></td> </tr> <tr> <td><b>Token Rotation</b></td> <td>Manual</td> <td>Automatic</td> <td><span style="color:#2ecc71">✨ Smart</span></td> </tr> <tr> <td><b>Proxy Support</b></td> <td>Static list</td> <td>Auto-fetch + test</td> <td><span style="color:#2ecc71">✨ Dynamic</span></td> </tr> <tr> <td><b>Rate Limit</b></td> <td>Cached</td> <td>Live API checks</td> <td><span style="color:#2ecc71">✨ Real-time</span></td> </tr> <tr> <td><b>Memory Usage</b></td> <td>~50 MB</td> <td>~300-500 MB</td> <td><span style="color:#f39c12">⬆️ 6-10x</span></td> </tr> </tbody> </table> </div> --- ### 📊 Real-World Performance **Test: 1000 PRs with High-Performance Modules** <div align="center"> ```bash python parallel_automation.py --count 1000 --concurrent 20 ``` </div> **Results:** <div align="center"> ``` ⏱️ Time: 16 minutes (vs 8+ hours sequential) ✅ Success Rate: 94% 📈 Speed: 62.5 PRs/min 🔄 Token Rotation: 3 tokens cycled automatically 🌐 Proxies Used: 87 working proxies 💾 Memory: ~720 MB peak ``` <img src="https://img.shields.io/badge/Performance-Exceptional-brightgreen?style=for-the-badge" alt="Performance"/> </div> --- ### ⚡1️⃣ HighPerformanceGitManager **🎯 Key Features:** ```python # 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:** ```python # 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 calls - **Smart Token Selection:** Auto-switch on rate limits - **Proxy Integration:** Built-in proxy support ```python # 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 minutes - **Fair Distribution:** Shuffle tokens for balanced usage - **Auto-Refresh:** Update stale token status ```python # 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:** ```python 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:** ```python # 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:** ```python # Sort by speed (fastest first) working_proxies.sort(key=lambda x: x.get("latency", 999)) ``` --- ### ⚡5️⃣ ProxyRefresher **🎯 Background Service** ```bash # Run in separate terminal python -m high_performance.proxy_refresher ``` **Output:** ``` 🔄 Proxy Refresher Started ⏰ Will refresh proxies every 30 minutes [10:00:00] Refreshing proxies... 🔎 Fetching from free-proxy-list... 🔎 Fetching from proxyscrape... 📦 Collected: 342 unique proxies 📦 Testing: 342 proxies... ✅ Working: 87 proxies [10:30:00] Refreshing proxies... ... ``` --- ## 🔐 Security & Best Practices <div align="center"> ### 🛡️ Keep Your Tokens Safe <img src="https://img.shields.io/badge/Security-Critical-red?style=for-the-badge&logo=shield&logoColor=white" /> </div> --- ### 🔒 Token Security Checklist <table> <tr> <td>✅</td> <td><b>Never commit tokens to Git</b></td> <td>Add to <code>.gitignore</code></td> </tr> <tr> <td>✅</td> <td><b>Use environment variables</b></td> <td><code>export GITHUB_TOKEN="ghp_xxx"</code></td> </tr> <tr> <td>✅</td> <td><b>Rotate tokens regularly</b></td> <td>Every 30-90 days</td> </tr> <tr> <td>✅</td> <td><b>Use fine-grained tokens</b></td> <td>Limit scope to specific repos</td> </tr> <tr> <td>✅</td> <td><b>Enable 2FA</b></td> <td>Extra security layer</td> </tr> <tr> <td>✅</td> <td><b>Monitor token usage</b></td> <td><code>gh api rate_limit</code></td> </tr> </table> --- ### 🛡️ API Rate Limits **GitHub Limits:** <div align="center"> | Authentication | Requests/Hour | Notes | |----------------|---------------|-------| | Unauthenticated | 60 | Very limited | | OAuth Token | 5,000 | Per token | | GitHub App | 15,000 | Enterprise | | Multiple Tokens | 15,000+ | Rotation | </div> **📊 Rate Limit Strategies:** ```python # 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 <details> <summary><b>🆓 Free vs 💰 Paid Proxies</b></summary> | Feature | Free | Paid | |---------|------|------| | **Reliability** | ⭐⭐ (20-30%) | ⭐⭐⭐⭐⭐ (99%+) | | **Speed** | Slow | Fast | | **Security** | ⚠️ Questionable | ✅ Verified | | **Support** | None | 24/7 | | **Cost** | $0 | $10-200/mo | | **Best For** | Testing | Production | **💰 Recommended Paid Services:** 1. **Bright Data** - Enterprise ($500+/mo) 2. **Smartproxy** - Balanced ($75/mo) 3. **Oxylabs** - Premium ($300/mo) 4. **Proxy-Cheap** - Budget ($10/mo) </details> --- ## 🐛 Troubleshooting <div align="center"> ### 🔧 Common Issues & Solutions <img src="https://img.shields.io/badge/Support-Community-blue?style=for-the-badge&logo=github" /> </div> --- ### ❌ Issue 1: "gh: command not found" <details> <summary><b>📋 Problem Description</b></summary> GitHub CLI is not installed or not in PATH. </details> <details> <summary><b>✅ Solution</b></summary> ```bash # macOS brew install gh # Linux (Debian/Ubuntu) sudo apt update && sudo apt install gh -y # Windows winget install --id GitHub.cli # Verify gh --version ``` </details> --- ### ❌ Issue 2: "Authentication failed" <details> <summary><b>📋 Problem Description</b></summary> GitHub CLI not authenticated or token expired. </details> <details> <summary><b>✅ Solution</b></summary> ```bash # Re-authenticate gh auth login # Or use token directly echo "YOUR_TOKEN" | gh auth login --with-token # Verify authentication gh auth status ``` </details> --- ### ❌ Issue 3: "API rate limit exceeded" <details> <summary><b>📋 Problem Description</b></summary> Too many API requests in short time. </details> <details> <summary><b>✅ Solutions</b></summary> **Option 1: Add More Tokens** ```json { "tokens": [ {"name": "Token 1", "token": "ghp_xxx1"}, {"name": "Token 2", "token": "ghp_xxx2"}, {"name": "Token 3", "token": "ghp_xxx3"} ] } ``` **Option 2: Check Rate Limit** ```bash gh api rate_limit # Output shows: # - Remaining requests # - Reset time ``` **Option 3: Increase Delay** ```json { "delay_seconds": 60 } ``` </details> --- ### ❌ Issue 4: "Failed to push branch" <details> <summary><b>📋 Problem Description</b></summary> Git push fails due to network or permissions. </details> <details> <summary><b>✅ Solutions</b></summary> **Check 1: Internet Connection** ```bash ping github.com ``` **Check 2: Repository Permissions** ```bash gh repo view --web # Verify you have write access ``` **Check 3: Branch Protection** ```bash gh api repos/OWNER/REPO/branches/main/protection ``` **Check 4: Re-authenticate** ```bash gh auth refresh ``` </details> --- ### ❌ Issue 5: "No changes to commit" <details> <summary><b>📋 Problem Description</b></summary> File already contains identical content. </details> <details> <summary><b>✅ Solutions</b></summary> **Solution 1: Reset State** ```bash python main.py --reset ``` **Solution 2: Change Target File** ```json { "readme_file": "CONTRIBUTING.md" } ``` **Solution 3: Force Content Change** Add timestamps or unique IDs to each commit. </details> --- ### 🔍 Enable Debug Mode ```bash # Set environment variable export LOG_LEVEL=DEBUG # Run with debug logging python main.py # Or edit logger.py logger.setLevel(logging.DEBUG) ``` **Debug Output Example:** ``` DEBUG - Token selected: primary (4850 remaining) DEBUG - Proxy selected: http://8.219.97.248:9090 DEBUG - Executing: git push origin automation-1-abc123 DEBUG - Command output: [SUCCESS] DEBUG - API response: {"pr_number": 12345} ``` --- ## 📈 Performance Tips <div align="center"> ### ⚡ Maximize Your Speed <img src="https://img.shields.io/badge/Optimization-Guide-orange?style=for-the-badge&logo=speedtest" /> </div> --- ### 🚀 Speed Optimization Matrix <table> <thead> <tr> <th>Strategy</th> <th>Impact</th> <th>Difficulty</th> <th>Implementation</th> </tr> </thead> <tbody> <tr> <td><b>Use Parallel Mode</b></td> <td>⭐⭐⭐⭐⭐</td> <td>🟢 Easy</td> <td><code>python parallel_automation.py --concurrent 20</code></td> </tr> <tr> <td><b>Multiple Tokens</b></td> <td>⭐⭐⭐⭐⭐</td> <td>🟢 Easy</td> <td>Add 2-3 tokens to <code>github_tokens.json</code></td> </tr> <tr> <td><b>Enable Proxies</b></td> <td>⭐⭐⭐⭐</td> <td>🟡 Medium</td> <td>Set <code>"use_free_proxies": true</code></td> </tr> <tr> <td><b>Reduce Delay</b></td> <td>⭐⭐⭐</td> <td>🟢 Easy</td> <td><code>--delay 10</code> (sequential mode)</td> </tr> <tr> <td><b>Skip Auto-Merge</b></td> <td>⭐⭐</td> <td>🟢 Easy</td> <td><code>--no-merge</code></td> </tr> <tr> <td><b>Use SSD Storage</b></td> <td>⭐⭐</td> <td>🔴 Hard</td> <td>Run on SSD drive</td> </tr> </tbody> </table> --- ### 💾 Resource Optimization **Optimal Settings by Hardware:** <div align="center"> | 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 | </div> **📊 Monitor Resources:** ```bash # CPU & Memory Usage top -p $(pgrep -f parallel_automation) # Disk I/O iotop -p $(pgrep -f parallel_automation) # Network Stats nethogs ``` --- ### 📊 Benchmarks <details> <summary><b>Test 1: Sequential Mode (100 PRs)</b></summary> **Configuration:** ```json { "pr_count": 100, "delay_seconds": 30, "auto_merge": true } ``` **Results:** ``` ⏱️ Time: 52 minutes ✅ Success: 98 PRs (98%) ❌ Failed: 2 PRs (2%) 🔁 Retries: 3 operations 💾 Memory: ~50 MB 📈 Speed: 1.9 PRs/min ``` </details> <details> <summary><b>Test 2: Parallel Mode (1000 PRs, 10 workers)</b></summary> **Configuration:** ```bash python parallel_automation.py --count 1000 --concurrent 10 ``` **Results:** ``` ⏱️ Time: 28 minutes ✅ Success: 960 PRs (96%) ❌ Failed: 40 PRs (4%) 🔁 Retries: 42 operations 💾 Memory: ~380 MB 📈 Speed: 35.7 PRs/min ``` </details> <details> <summary><b>Test 3: Maximum Speed (1000 PRs, 20 workers, 3 tokens)</b></summary> **Configuration:** ```bash python parallel_automation.py --count 1000 --concurrent 20 ``` **Results:** ``` ⏱️ Time: 16 minutes ✅ Success: 940 PRs (94%) ❌ Failed: 60 PRs (6%) 🔁 Retries: 68 operations 💾 Memory: ~720 MB 📈 Speed: 62.5 PRs/min 🔄 Tokens: 3 rotated 🌐 Proxies: 87 used ``` </details> --- ## 🤝 Contributing <div align="center"> ### 💪 Join the Community <img src="https://img.shields.io/badge/Contributors-Welcome-brightgreen?style=for-the-badge&logo=github" /> <img src="https://user-images.githubusercontent.com/74038190/212284136-03988914-d899-44b4-b1d9-4eeccf656e44.gif" width="500"/> </div> --- ### 🚀 How to Contribute ```bash # 1️⃣ Fork the repository gh repo fork itxashancode/Pull-Shark-Automation # 2️⃣ Clone your fork git clone https://github.com/YOUR_USERNAME/Pull-Shark-Automation.git cd Pull-Shark-Automation # 3️⃣ Create feature branch git checkout -b feature/amazing-feature # 4️⃣ Make your changes # ... edit files ... # 5️⃣ Commit with conventional commits git commit -m "feat: add amazing feature" # 6️⃣ Push to your fork git push origin feature/amazing-feature # 7️⃣ Create Pull Request gh pr create --title "Add amazing feature" --body "Description..." ``` --- ### 📝 Code Style Guide ```python # ✅ 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:** ```bash # Auto-format with black black *.py # Check style with flake8 flake8 *.py # Type checking with mypy mypy *.py ``` --- ### 🐛 Reporting Bugs Found a bug? Help us fix it! **Steps:** 1. Check existing issues 2. Create new issue with template 3. 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:** 1. Check existing discussions 2. Open feature request 3. Describe: - Use case - Proposed solution - Alternatives considered --- ## 📄 License <div align="center"> ### MIT License <img src="https://img.shields.io/badge/License-MIT-green?style=for-the-badge" alt="MIT License"/> ``` MIT License Copyright (c) 2026 Pull Shark Automation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ``` </div> --- ## 🙏 Acknowledgments <div align="center"> ### 🌟 Built With Amazing Tools <p> <img src="https://img.shields.io/badge/Python-3776AB?style=for-the-badge&logo=python&logoColor=white" alt="Python"/> <img src="https://img.shields.io/badge/GitHub_CLI-181717?style=for-the-badge&logo=github&logoColor=white" alt="GitHub CLI"/> <img src="https://img.shields.io/badge/Git-F05032?style=for-the-badge&logo=git&logoColor=white" alt="Git"/> </p> <p> <img src="https://img.shields.io/badge/Discord-7289DA?style=for-the-badge&logo=discord&logoColor=white" alt="Discord"/> <img src="https://img.shields.io/badge/Slack-4A154B?style=for-the-badge&logo=slack&logoColor=white" alt="Slack"/> <img src="https://img.shields.io/badge/AsyncIO-00599C?style=for-the-badge&logo=python&logoColor=white" alt="AsyncIO"/> </p> --- ### 💖 Special Thanks - **GitHub** - For excellent CLI and API - **Python Community** - For amazing async libraries - **Contributors** - Everyone who improved this project - **You** - For using Pull Shark Automation! --- ## 📞 Support & Community <table align="center"> <tr> <td align="center"> <a href="https://github.com/itxashancode/Pull-Shark-Automation/wiki"> <img src="https://img.shields.io/badge/📚_Documentation-Read-blue?style=for-the-badge" alt="Docs"/> </a> </td> <td align="center"> <a href="https://github.com/itxashancode/Pull-Shark-Automation/issues"> <img src="https://img.shields.io/badge/🐛_Issues-Report-red?style=for-the-badge" alt="Issues"/> </a> </td> </tr> <tr> <td align="center"> <a href="https://github.com/itxashancode/Pull-Shark-Automation/discussions"> <img src="https://img.shields.io/badge/💬_Discussions-Join-green?style=for-the-badge" alt="Discussions"/> </a> </td> <td align="center"> <a href="https://github.com/itxashancode"> <img src="https://img.shields.io/badge/👤_Profile-Visit-orange?style=for-the-badge" alt="Profile"/> </a> </td> </tr> </table> --- ## ⭐ Star History <div align="center"> [](https://star-history.com/#itxashancode/Pull-Shark-Automation&Date) </div> --- ## 🎉 Final Words <div align="center"> <img src="https://capsule-render.vercel.app/api?type=waving&color=gradient&customColorList=6,11,20&height=150§ion=footer&text=Happy%20Automating!&fontSize=40&fontColor=fff&animation=twinkling" width="100%"/> ### 🦈 Unleash the Pull Shark! 🦈 <img src="https://user-images.githubusercontent.com/74038190/212284100-561aa473-3905-4a80-b561-0d28506553ee.gif" width="600"/> **If this tool helped you earn your Pull Shark badge, please ⭐ star the repository!** <p> <i>Made with ❤️ by developers, for developers</i> </p> <p> <a href="#-github-pull-shark-automation">⬆️ Back to Top</a> </p> <p> <img src="https://komarev.com/ghpvc/?username=itxashancode&label=Repository%20Views&color=0e75b6&style=flat" alt="Repository Views"/> </p> --- **⚠️ Remember:** This tool is for educational purposes. Use responsibly and follow GitHub's Terms of Service. </div>