Git Catcher

A Python CLI tool that receives GitHub push webhooks in real time via the Smee.io SSE proxy and automatically runs git pull and a custom deploy command for allowed branches.

Works behind firewalls/NAT, and supports automatic reconnection with exponential backoff on disconnection.

Installation

pip install -r git_catcher/requirements.txt

Dependencies

Quick Start

1. Interactive Setup (recommended)

python -m git_catcher.main init

Or using the shortcut:

python run.py init

Answer the interactive prompts to automatically generate a .env file and docker-compose.yml.

• Auto-generate Smee.io URL (opens browser)
• Randomly generate Webhook Secret
• Select repository path and allowed branches
• Configure Slack notifications

2. Manual Setup

Copy .env.example to create a .env file and fill in the values.

cp git_catcher/.env.example git_catcher/.env

2. Create a Smee.io Channel

1. Go to https://smee.io/new.
2. A unique channel URL is automatically generated (e.g. https://smee.io/AbCdEfGhIjKlMn).
3. Copy this URL. Use the same value for the GitHub Webhook Payload URL and SMEE_URL in your .env.

Note: The git-catcher init command automatically opens Smee.io in your browser.

3. Add a GitHub Repository Webhook

1. In your GitHub repository, go to Settings → Webhooks → Add webhook.
2. Configure as follows:

3. Click Add webhook to save.

Note: Leaving the Secret blank also skips signature verification in Git Catcher. Setting a Secret is recommended for security.

3-1. Receive Webhooks for All Repositories via GitHub App (optional)

If you only need a single repository, use 3. Add a GitHub Repository Webhook above. To receive push webhooks from all repositories in your personal account (including future ones), create a GitHub App.

1) Create a GitHub App

Create an app at GitHub Settings → Developer settings → GitHub Apps → New GitHub App.

2) Permissions and Event Subscriptions

At the bottom of the creation form, configure:

• Repository Permissions → Contents: Set to Read-only or higher (required to detect code changes)
• Subscribe to events → Check Push (webhook fires only on code pushes)

3) Install the App on Your Account

This is the most important step. Creating the app alone is not enough — you must install it on your account.

1. On the created app page, click Install App.
2. Select your account and choose All repositories.
3. Click Install.

Selecting All repositories automatically applies the webhook to all existing repositories and any created in the future.

4) Security and Verification

4. .env Example

SMEE_URL must match the channel URL from Smee.io, and WEBHOOK_SECRET must match the Secret entered in GitHub Webhook settings.

SMEE_URL=https://smee.io/AbCdEfGhIjKlMn
WEBHOOK_SECRET=your-webhook-secret-here
REPO_PATH=/path/to/your/repo
ALLOWED_BRANCHES=main,master
POST_PULL_COMMAND=
ALLOWED_REPOS=
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/T.../B.../xxx
NOTIFY_ON_START=true
POLL_INTERVAL=0
LOG_LEVEL=INFO
LOG_FILE=
SHOW_ALL_EVENTS=false

See the environment variables table for details on each variable.

Running

Basic Usage

# Option 1: run as module
python -m git_catcher.main

# Option 2: shortcut (recommended)
python run.py

On startup, git-catcher connects to the Smee.io SSE stream and waits for GitHub push events. When a push is detected on an allowed branch, it automatically runs git fetch → git checkout → git pull → post-pull command in sequence.

Startup Notification

When NOTIFY_ON_START=true, git-catcher sends a Slack notification on startup containing:

• Repository name
• Allowed branch list
• Hostname
• External IP address
• Start time (UTC)

CLI Commands

CLI Options (run command)

# Basic run
python run.py

# git_catcher module DEBUG + write to log file
python run.py -v --log-file deploy.log

# Show all push events + full DEBUG
python run.py -vv --show-all-events

# Interactive setup
python run.py init

Key Features

• Interactive setup: Answer prompts with git-catcher init to auto-generate .env and docker-compose.yml
• Quick start: Run with python run.py
• Startup notification: Sends a Slack notification on start when NOTIFY_ON_START=true (includes repo, branches, host, IP)
• Auto repo detection: Extracts owner/repo from REPO_PATH git remote origin URL when ALLOWED_REPOS is not set
• Slack deploy notifications: Notifies a Slack channel on deploy success/failure when SLACK_WEBHOOK_URL is set
• SSE reconnect recovery: Resumes from the last received event using Last-Event-ID on disconnection
• Rich console logging: Readable colored output with timestamp (HH:MM:SS.ms) format

Verifying It Works

1. Run Git Catcher:

   python run.py
   

2. When you see the SSE stream connected log, the connection is established.

3. If NOTIFY_ON_START=true, a startup notification is sent to Slack.

4. Push a commit to an allowed branch:

   git add .
   git commit -m "test webhook"
   git push origin main
   

5. Verify the following logs appear in order in the Git Catcher terminal:

   • Push detected: [main] test webhook
   • git fetch → git checkout → git pull complete
   • POST_PULL_COMMAND executed (if configured)
   • Slack notification sent (if configured)

If something is wrong, check the Recent Deliveries tab on the GitHub Webhook page to inspect delivery status.

Tests

pytest tests/ -v