Pull-Shark-Automation

KO | EN

gitlite — search

#javascript #hacktoberfest #typescript #llm #golang #machine-learning #rust #deep-learning #linux #macos #windows #cli #vue #open-source

Pull-Shark-Automation

(★ 60)

Automate GitHub PR creation at scale with intelligent token rotation, proxy support, and real-time notifications. Create thousands of PRs effortlessly using sequential or high-speed parallel modes (62 PRs/min). Features: multi-token management, auto-merge, state persistence, Discord/Slack webhooks, async operations, and Windows compatibility.

Pull-Shark-Automation 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 🦈 GitHub Pull Shark Automation

---

## ⚠️ Educational Purpose Only

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>

---

## 🎯 What Is Pull Shark Automation?

</div>

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 |

</div>

---

## 📑 Table of Contents

</div>

---

## 🌟 Features

### 🎯 Core Capabilities

```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

```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

```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

### System Design Overview

```
┌─────────────────────────────────────────────────────────────────┐
│                    🦈 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>

---

## 📦 Installation

### 🚀 Quick Start Guide

</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 git@github.com: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>

---

### ✅ Installation Complete!

**Ready to configure? Proceed to [⚙️ Configuration](#️-configuration)**

</div>

---

## ⚙️ Configuration

### 🎛️ Setup Your Automation

</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:password@proxy.example.com:8080
socks5://admin:secret@10.0.0.1: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>

---

### ✅ Configuration Complete!

**Next: [🚀 Usage Guide](#-usage)**

</div>

---

## 🚀 Usage

### 🎮 Command Center

</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`)

```bash
python main.py [OPTIONS]
```

**⭐ 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`)

```bash
python parallel_automation.py [OPTIONS]
```

**⭐ 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>

---

### 💡 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

### 🏗️ System Architecture Breakdown

</div>

---

### 1️⃣ GitManager (`git_manager.py`)

**🎯 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`)

**🎯 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`)

**🎯 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`)

**🎯 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: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:**

```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`)

**🎯 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

### 🚀 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

<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**

```bash
python parallel_automation.py --count 1000 --concurrent 20
```

</div>

**Results:**

```
⏱️  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
```

</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

### 🛡️ Keep Your Tokens Safe

</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:**

| 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

### 🔧 Common Issues & Solutions

</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

### ⚡ Maximize Your Speed

</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:**

| 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

### 💪 Join the Community

</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

### MIT License

```
MIT License

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

### 🌟 Built With Amazing Tools

---

### 💖 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

---

## ⭐ Star History

[![Star History Chart](https://api.star-history.com/svg?repos=itxashancode/Pull-Shark-Automation&type=Date)](https://star-history.com/#itxashancode/Pull-Shark-Automation&Date)

</div>

---

## 🎉 Final Words

### 🦈 Unleash the Pull Shark! 🦈

**If this tool helped you earn your Pull Shark badge, please ⭐ star the repository!**

<p>
  <i>Made with ❤️ by developers, for developers</i>
</p>

---

**⚠️ Remember:** This tool is for educational purposes. Use responsibly and follow GitHub's Terms of Service.

</div>

Pull-Shark-Automation

Pull-Shark-Automation 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Pull-Shark-Automation

Pull-Shark-Automation 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README