DEV Community

Ashan_Dev
Ashan_Dev

Posted on

🤝 Automate GitHub's Pair Extraordinaire Badge with Python

#python #automation #github #opensource

A deep dive into Pair Extraordinaire Automation — a Python framework that streamlines co-authored PRs at scale, with dual execution modes, token rotation, webhook notifications, and smart state resumption.

GitHub logo itxashancode / Pair-Extraordinaire-Automation

Automate GitHub co-authored Pull Requests with Python. Earn the Pair Extraordinaire badge using sequential or parallel modes, multi-token rotation, Discord/Slack webhooks, and smart rate-limit handling. Supports dry-run, auto-merge & state resumption.

🤝 Pair Extraordinaire Automation

Header

Typing Animation

Features Install Usage Contribute

Python GitHub CLI License Platform

⚠️ Educational Purpose Only

Educational

This tool is designed for educational purposes to understand GitHub automation, co-authoring workflows, and API integration. Use responsibly and in accordance with GitHub's Terms of Service.

🏆 Earn Your Pair Extraordinaire Badge

Pair Extraordinaire Badge
Default 1 PR Bronze 10 PRs Silver 24 PRs Gold 48 PRs

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:

🎯 Use Case 📊 Benefit
Co-authored Commits Automatic Co-authored-by trailers on every commit
Badge Hunting Earn GitHub Pair Extraordinaire badge efficiently
Batch Documentation Update files across multiple branches with a collaborator
CI/CD Testing Stress-test co-authoring automation pipelines
Learning & Research Study GitHub automation patterns and workflows

📑 Table of Contents

🌟 Features 🏗️ Architecture 📦 Installation ⚙️ Configuration
🚀 Usage 🔧
…
View on GitHub

Ever wondered how some developers rack up GitHub achievement badges at scale? Or wanted to deeply understand how GitHub co-authoring workflows actually function under the hood? That's exactly what Pair Extraordinaire Automation is built for.

This open-source Python framework automates co-authored Pull Request workflows — giving you a hands-on way to explore GitHub API integration, token management, webhook notifications, and stateful automation design, all in one project.

⚠️ Heads up: This tool is built for educational purposes — to study GitHub automation and co-authoring patterns. Always use it responsibly and in line with GitHub's Terms of Service.

🏆 What Is the Pair Extraordinaire Badge?

GitHub awards the Pair Extraordinaire achievement when you co-author and merge Pull Requests with a collaborator. The badge has four tiers:

Tier Required PRs
Default 1 PR
🥉 Bronze 10 PRs
🥈 Silver 24 PRs
🥇 Gold 48 PRs

The magic happens through Git's Co-authored-by commit trailer — a simple but powerful convention that GitHub recognises to credit multiple authors on a single commit.

🎯 What Does This Project Do?

Pair Extraordinaire Automation is a configurable Python framework that:

  • Creates branches, makes co-authored commits, opens Pull Requests, and merges them — all automatically
  • Supports sequential and parallel execution modes
  • Handles rate limits with exponential backoff and smart retry logic
  • Rotates across multiple GitHub tokens for higher throughput
  • Sends real-time progress updates to Discord or Slack via webhooks
  • Persists state so you can resume after any interruption
  • Includes a dry-run mode for testing without touching your repository

🏗️ Architecture Overview

The project is cleanly structured into four layers:

Pair Extraordinaire Automation
│
├── run.py              ← Entry point & orchestrator
├── src/                ← Core bot logic (git ops, GitHub API, token mgr)
├── config/             ← JSON settings + .env variables
└── templates/          ← Commit message & PR body templates
Enter fullscreen mode Exit fullscreen mode

The orchestration flow looks like this:

Start → Load Config → Choose Mode (Sequential / Parallel)
      → Create Branch → Co-authored Commit → Push → Open PR
      → Auto-Merge → Save State → Notify → Repeat
Enter fullscreen mode Exit fullscreen mode

What I like about this design is its clear separation of concerns. The src/ layer handles all Git and GitHub API interactions, while config/ and templates/ let you customise behaviour without touching any core logic.

⚙️ Getting Started

Prerequisites

You'll need Python 3.8+, Git 2.0+, and the GitHub CLI installed. You also need two GitHub accounts — your own and a collaborator's.

Installation 

# Clone the repo
git clone https://github.com/itxashancode/Pair-Extraordinaire-Automation.git
cd Pair-Extraordinaire-Automation

# Install dependencies
pip install -r requirements.txt

# Authenticate GitHub CLI
gh auth login
Enter fullscreen mode Exit fullscreen mode

Configuration

Copy .env.example to .env and fill in your details:

GITHUB_TOKEN=your_personal_access_token
REPO_OWNER=your_github_username
REPO_NAME=your_repository_name

CO_AUTHOR_NAME=Collaborator Name
CO_AUTHOR_EMAIL=collaborator@email.com
CO_AUTHOR_TOKEN=collaborator_token_optional

# Optional webhooks
DISCORD_WEBHOOK=https://discord.com/api/webhooks/...
SLACK_WEBHOOK=https://hooks.slack.com/services/...
Enter fullscreen mode Exit fullscreen mode

Then set your run parameters in config/:

{
  "pr_count": 50,
  "delay_seconds": 15,
  "auto_merge": true,
  "dry_run": false,
  "max_retries": 3
}
Enter fullscreen mode Exit fullscreen mode

🚀 Usage

Always test first with dry-run 

python run.py --dry-run --count 5
Enter fullscreen mode Exit fullscreen mode

This simulates the full workflow — branch creation, commits, PRs — without making any real changes. It's a great way to catch config mistakes before they matter.

Run for real 

# Basic run (uses config defaults)
python run.py

# Custom count with specific delay
python run.py --count 50 --delay 10

# Resume after an interruption — state is automatically tracked
python run.py
Enter fullscreen mode Exit fullscreen mode

Sample output 

🚀 Starting Pair Extraordinaire Automation from PR #1

🔹 Processing PR #1
  ├─ 🌿 Created branch: pair-auto-1-a1b2c3d4
  ├─ 💾 Committed with Co-authored-by trailer
  ├─ 📤 Pushed to remote
  └─ ✅ PR #101 created and merged

⏱️  Waiting 15 seconds...

🔹 Processing PR #2
...
Enter fullscreen mode Exit fullscreen mode

🔑 The Co-authored-by Mechanic

The key to how this project works is a Git commit trailer that GitHub specifically recognises:

feat: automated update #1

This is an automated co-authored commit.

Co-authored-by: Collaborator Name <collaborator@email.com>
Enter fullscreen mode Exit fullscreen mode

When a PR containing this trailer is merged, GitHub awards the Pair Extraordinaire badge to both the author and the co-author. The email in the trailer must match an email associated with the collaborator's GitHub account — that's a common gotcha.

🛡️ Security Considerations

A few things to keep in mind when running this:

  • Never commit your .env file — it's already in .gitignore, keep it that way
  • Use fine-grained personal access tokens scoped to specific repos only
  • Rotate tokens every 30–90 days as a good hygiene practice
  • Monitor your rate limit with gh api rate_limit — you get 5,000 requests/hour per token, and multi-token rotation lets you stack that

🐛 Common Issues

gh: command not found → Install GitHub CLI for your platform and verify with gh --version

Authentication failed → Run gh auth login and follow the prompts, or use echo "TOKEN" | gh auth login --with-token

Co-authored-by not recognized → Double-check that CO_AUTHOR_EMAIL exactly matches an email registered on the collaborator's GitHub account

API rate limit exceeded → Increase delay_seconds in config, or add a second token for rotation

📈 Real-World Benchmarks

Badge Goal PRs Approx. Time
Default 2 ~30 seconds
Bronze 10 ~3 minutes
Silver 24 ~5 minutes
Gold 48 ~10 minutes

💡 What I Learned Building This

This project is a great reference for several Python and GitHub automation patterns:

  • Stateful automation — persisting progress to a JSON file so a long-running task can be safely interrupted and resumed
  • Exponential backoff — retry logic that doubles the wait time on each failure (5s → 10s → 20s) to avoid hammering a rate-limited API
  • Token rotation — cycling through multiple API tokens to multiply your effective request quota
  • Template-based commit messages — separating message content from code so customisation doesn't require touching logic
  • Webhook integration — pushing structured notifications to Discord/Slack with colour-coded severity levels

Even if you never use this for badge automation specifically, these patterns come up constantly in real-world automation and DevOps work.

🤝 Contributing

The project is MIT licensed and welcomes contributions. If you want to jump in:

gh repo fork itxashancode/Pair-Extraordinaire-Automation
git checkout -b feature/your-improvement
# Make changes, commit with conventional commits
git commit -m "feat: add your amazing feature"
gh pr create
Enter fullscreen mode Exit fullscreen mode

The codebase follows type hints and clear docstrings — black for formatting, flake8 for style, mypy for type checking.

🔗 Links

If you found this interesting, drop a ⭐ on the repo and let me know in the comments — what GitHub automation patterns have you built or wanted to build?

Top comments (0)