prwatcher

CLI tool that watches GitHub PRs and sends Slack notifications when CI passes, fails, or the PR is ready to merge. Optionally auto-merges when all checks pass.

Zero setup for developers — just run one command. No Slack app creation, no servers, no ngrok.

Roadmap

Phase 1 — CLI Watcher (Done)

Run from your terminal. Watches PRs and sends Slack notifications while your laptop is on.

Phase 2 — Cloud Watcher (Done)

Run without a laptop via GitHub Actions. Trigger from CLI, GitHub UI, mobile, or curl.

Phase 3 — Multi-Channel Notifications (Coming Soon)

Telegram, Discord, Microsoft Teams support.

Phase 1: CLI Watcher

Install

npm install -g prwatcher

Or use directly with npx:

npx prwatcher https://github.com/owner/repo/pull/123

GitHub Token Setup

On first run you'll be prompted for a GitHub personal access token. The type of token you need depends on how you use the tool:

Notifications only (watching PRs)

A fine-grained token with minimal permissions is enough:

• Metadata → Read-only (required)
• Pull requests → Read-only

Create one at github.com/settings/tokens → Fine-grained tokens → Generate new token.

Full access (--auto-merge, --auto-rebase)

Use a classic token with repo scope — this is the simplest way to get full access:

Create one at github.com/settings/tokens → Tokens (classic) → Generate new token → check repo.

Or if you prefer a fine-grained token:

• Metadata → Read-only (required)
• Pull requests → Read and write
• Contents → Read and write

| Feature | Fine-grained (minimal) | Classic (repo scope) | |---------|----------------------|----------------------| | Watch + Slack notifications | ✅ | ✅ | | Smart CI detection | ✅ | ✅ | | --auto-merge | ❌ | ✅ | | --auto-rebase | ❌ | ✅ |

Your token is saved to ~/.watch-pr on your machine with owner-only permissions (0600). It is never sent anywhere except the GitHub API.

Usage

prwatcher https://github.com/owner/repo/pull/123

On first run, you'll also be prompted for:

• Slack webhook URL — your team's Incoming Webhook

Both are saved to ~/.watch-pr so you only enter them once.

Options

prwatcher <pr-url> [options]

Options:
  --interval <minutes>   Polling interval in minutes (default: 1)
  --auto-merge           Automatically merge PR once all required checks pass
  --auto-rebase          Automatically rebase PR branch when behind (no conflicts only)
  --reset-config         Re-enter GitHub token and Slack webhook URL
  -V, --version          Output version number
  -h, --help             Display help

Examples

# Watch a PR with default 1-minute polling
prwatcher https://github.com/org/repo/pull/42

# Watch and auto-merge when ready
prwatcher https://github.com/org/repo/pull/42 --auto-merge

# Auto-rebase when behind base branch (no conflicts only)
prwatcher https://github.com/org/repo/pull/42 --auto-rebase

# Auto-rebase + auto-merge (full automation)
prwatcher https://github.com/org/repo/pull/42 --auto-rebase --auto-merge

# Poll every 30 seconds
prwatcher https://github.com/org/repo/pull/42 --interval 0.5

# Poll every 5 minutes
prwatcher https://github.com/org/repo/pull/42 --interval 5

# Re-enter credentials
prwatcher https://github.com/org/repo/pull/42 --reset-config

Notifications

You'll get Slack messages when:

| Event | Message | |-------|---------| | Required CI checks fail | ⚠️ CI checks failed (lists which ones) | | PR needs rebase | 🔄 PR needs rebase | | PR is ready to merge | ✅ PR is ready to merge! | | PR is auto-merged | 🎉 PR was auto-merged! | | PR is merged | 🎉 PR was merged! | | PR is closed | ❌ PR was closed without merging | | Waiting for review approval | 👀 PR waiting for review (CI passed) | | Auto-merge failed | ⚠️ Auto-merge failed (with reason) | | PR auto-rebased | 🔄 PR branch auto-rebased from base branch |

Notifications only fire on state changes — no spam.

Smart CI Detection

The tool distinguishes between required and optional CI checks using GitHub's branch protection rules:

• If a required check fails → you get notified
• If an optional check fails → ignored, PR can still merge
• If branch protection can't be read (no admin access) → falls back to treating all checks as required

One-Time Team Setup (Slack Webhook)

One team member creates the webhook, shares the URL with everyone:

1. Go to Slack API → Apps
2. Create an app (or use existing) → Incoming Webhooks → Enable
3. Add New Webhook to Workspace → pick your #pr-notifications channel
4. Copy the webhook URL and share with your team

Each developer pastes this URL on their first prwatcher run.

How It Works

prwatcher <url>
     ↓
Poll GitHub API every N seconds
     ↓
Detect state change (CI failed, ready, merged, etc.)
     ↓
POST to Slack webhook
     ↓
--auto-merge? → merge via GitHub API → exit
PR merged/closed? → exit

Phase 2: Cloud Watcher (Done)

Watch PRs without keeping your laptop open.

A GitHub Actions workflow runs in the cloud on your behalf. It polls the PR, sends Slack notifications, auto-merges/rebases, and stops when the PR is done.

• Free — 2,000 min/month for private repos, unlimited for public repos
• No server — runs inside GitHub Actions
• Trigger from anywhere — CLI, GitHub UI, mobile, or curl

Cloud Setup (one-time, by team lead)

1. Create a private repo for the watcher:

gh repo create your-org/pr-watcher --private

2. Add the workflow file:

git clone https://github.com/your-org/pr-watcher.git
cd pr-watcher
mkdir -p .github/workflows
# Copy the workflow file (bundled with prwatcher)
cp $(npm root -g)/prwatcher/workflow/watch.yml .github/workflows/watch.yml
git add . && git commit -m "Add PR watcher workflow" && git push

Or run the interactive setup:

prwatcher setup-cloud

3. Add the secret key to the repo:

gh secret set CLOUD_KEY -R your-org/pr-watcher
# paste your secret key

4. Add team members as collaborators:

gh api repos/your-org/pr-watcher/collaborators/USERNAME -X PUT -f permission=write

Team Member Setup (one-time)

Each developer runs:

prwatcher config set cloud-repo your-org/pr-watcher
prwatcher config set cloud-key the-secret-key

They also need their own GitHub token and Slack webhook configured (done on first prwatcher run).

Usage

# Watch from the cloud — close your laptop
prwatcher https://github.com/org/repo/pull/42 --cloud

# Cloud + auto-merge + auto-rebase
prwatcher https://github.com/org/repo/pull/42 --cloud --auto-merge --auto-rebase

Trigger from GitHub UI / Mobile

1. Go to your watcher repo → Actions → Watch PR
2. Click Run workflow
3. Fill in: PR URL, cloud key, your GitHub token, Slack webhook
4. Done — notifications will come to Slack

Trigger via curl (from anywhere)

curl -X POST \
  https://api.github.com/repos/your-org/pr-watcher/actions/workflows/watch.yml/dispatches \
  -H "Authorization: token YOUR_GITHUB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ref": "main",
    "inputs": {
      "pr_url": "https://github.com/org/repo/pull/42",
      "cloud_key": "your-secret-key",
      "github_token": "ghp_your_token",
      "slack_webhook": "https://hooks.slack.com/services/xxx",
      "auto_merge": "true",
      "auto_rebase": "true"
    }
  }'

Config Commands

prwatcher config show                          # Show current config (secrets masked)
prwatcher config set cloud-repo org/repo       # Set watcher repo
prwatcher config set cloud-key my-secret       # Set cloud key
prwatcher config set github-token ghp_xxx      # Set GitHub token
prwatcher config set slack-webhook https://...  # Set Slack webhook

Phase 3 (Coming Soon)

Multi-Channel Notifications

Not just Slack — get notified wherever your team lives.

| Channel | Status | |---------|--------| | Slack | Done | | Telegram | Coming soon | | Discord | Coming soon | | Microsoft Teams | Coming soon |

License

MIT