Automate co-authored PR creation and merging to unlock all achievement tiers!

🎯 What Is Pair Extraordinaire Automation?

A powerful Python automation framework that streamlines GitHub co-authored Pull Request workflows at scale. Perfect for developers who want to:

📑 Table of Contents

🌟 Features

🎬 How It Works

graph TB
    Start([🚀 Start Automation]) --> Config[📋 Load Config & .env]
    Config --> Mode{🔀 Choose Mode}
    Mode -->|Sequential| Seq[📝 run.py]
    Mode -->|Parallel| Par[⚡ Parallel Workers]
    Seq --> Git[🔧 Git Operations]
    Par --> Git
    Git --> Branch[🌿 Create Branch]
    Branch --> Commit[💾 Co-authored Commit]
    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!])

🏗️ Architecture

System Design Overview

┌─────────────────────────────────────────────────────────────────┐
│               🤝 Pair Extraordinaire Automation                  │
│                     Core Orchestration Layer                     │
└─────────────────────────────────────────────────────────────────┘
                                │
                ┌───────────────┴───────────────┐
                │                               │
        ┌───────▼────────┐            ┌────────▼───────┐
        │  📝 Sequential │            │  ⚡ Parallel   │
        │    run.py      │            │   src/async    │
        │   Reliable     │            │   Fast Mode    │
        └───────┬────────┘            └────────┬───────┘
                │                              │
                └──────────────┬───────────────┘
                               │
        ┌──────────────────────┼──────────────────────┐
        │                      │                      │
   ┌────▼─────┐         ┌─────▼────┐         ┌──────▼──────┐
   │ 🔧 src/  │         │ ⚙️ config│         │ 📄 templates│
   │ Core Bot │         │ Settings │         │  Commit Msg │
   └────┬─────┘         └─────┬────┘         └──────┬──────┘
        │                     │                      │
        └─────────────────────┼──────────────────────┘
                              │
              ┌───────────────┼───────────────┐
              │               │               │
        ┌─────▼─────┐  ┌─────▼─────┐  ┌─────▼─────┐
        │ 🔑 Token  │  │ 📢 Notify │  │ 📝 Logger │
        │ Manager   │  │ Webhooks  │  │  System   │
        └───────────┘  └───────────┘  └───────────┘

🔑 Component Matrix

📦 Installation

🚀 Quick Start Guide

Prerequisites Checklist

✅ Python 3.8 or higher
✅ Git 2.0 or higher
✅ GitHub CLI (gh)
✅ Active GitHub account
✅ A collaborator account (for co-authoring)
✅ Write access to target repository

Step 1️⃣: Clone Repository

📥 Download the Code

# Clone via HTTPS
git clone https://github.com/itxashancode/Pair-Extraordinaire.git

# Or clone via SSH
git clone git@github.com:itxashancode/Pair-Extraordinaire.git

# Navigate to directory
cd Pair-Extraordinaire

Step 2️⃣: Install Dependencies

🐍 Python Packages

# Install all required packages
pip install -r requirements.txt

# Or use pip3 on some systems
pip3 install -r requirements.txt

📦 What Gets Installed:

Step 3️⃣: Install GitHub CLI

🍎 macOS

brew install gh && gh --version

🐧 Linux (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
gh --version

🪟 Windows

winget install --id GitHub.cli
# Or: choco install gh
gh --version

Step 4️⃣: Authenticate GitHub

🔐 Login to GitHub

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

✅ Installation Complete!

Ready to configure? Proceed to ⚙️ Configuration

⚙️ Configuration

🎛️ Setup Your Automation

📋 File 1: Environment Variables (.env)

cp .env.example .env

# GitHub credentials
GITHUB_TOKEN=your_personal_access_token_here

# Repository details
REPO_OWNER=your_github_username
REPO_NAME=your_repository_name

# Co-author details (required for Pair Extraordinaire)
CO_AUTHOR_NAME=Collaborator Name
CO_AUTHOR_EMAIL=collaborator@email.com
CO_AUTHOR_TOKEN=collaborator_github_token

# Notification webhooks (optional)
DISCORD_WEBHOOK=https://discord.com/api/webhooks/YOUR_WEBHOOK_HERE
SLACK_WEBHOOK=https://hooks.slack.com/services/YOUR_WEBHOOK_HERE

📖 Configuration Reference:

📋 File 2: Main Config (config/)

{
  "repo_path": ".",
  "base_branch": "main",
  "target_file": "README.md",
  "pr_count": 50,
  "delay_seconds": 15,
  "auto_merge": true,
  "dry_run": false,
  "max_retries": 3
}

📖 Configuration Reference:

📋 File 3: Commit Templates (templates/)

The templates/ directory contains message templates for comm