Skip to content

GitHub

This guide walks you through creating a GitHub App and configuring webhooks so prbot can fetch PR status and receive real-time updates.

Step 1: Create a GitHub App

  1. Go to Settings > Developer settings > GitHub Apps in your GitHub account (or organisation)
  2. Click New GitHub App
  3. Fill in the details:
Field Value
App name prbot (or any name you like)
Homepage URL Your repository or docs URL
Webhook URL https://your-domain.com/github/webhooks
Webhook secret A strong random string (save it for later)

Generating a webhook secret

openssl rand -hex 32

Step 2: Set permissions

Under Permissions & events, configure:

Repository permissions

Permission Access Purpose
Pull requests Read-only Fetch PR status & reviews
Metadata Read-only Required by GitHub

Event subscriptions

Subscribe to these events:

Event Purpose
Pull request Notified when PRs are opened, closed, merged
Pull request review Notified when reviews are submitted

Step 3: Generate a private key

  1. After creating the app, scroll to Private keys
  2. Click Generate a private key
  3. A .pem file will download — keep this safe

Step 4: Note the App ID

On the app's General page, copy the App ID (a numeric value).

Step 5: Install the app

  1. Go to Install App in the sidebar
  2. Click Install on your account or organisation
  3. Choose which repositories the app can access:
    • All repositories — prbot can track PRs in any repo
    • Only select repositories — pick specific repos

Step 6: Configure prbot

Add the following to your .env file:

PR_BOT_GITHUB_APP_ID=123456
PR_BOT_GITHUB_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----"
PR_BOT_GITHUB_WEBHOOK_SECRET=your-webhook-secret

Private key formatting

When setting the private key as an environment variable, you can either:

  • Use the entire PEM content with \n for newlines (as shown above)
  • Set it as a multi-line value in your .env file using quotes

In production (e.g. Fly.io), set the secret via the platform's secrets management.

How authentication works

prbot uses the GitHub App installation token flow:

sequenceDiagram
    participant prbot
    participant GitHub

    prbot->>prbot: Generate JWT (signed with private key)
    prbot->>GitHub: GET /orgs/{owner}/installation
    GitHub-->>prbot: Installation ID
    prbot->>GitHub: POST /app/installations/{id}/access_tokens
    GitHub-->>prbot: Installation token (1hr TTL)
    prbot->>GitHub: GET /repos/{owner}/{repo}/pulls/{number}
    Note over prbot: Tokens are cached until expiry

This means:

  • No personal access tokens needed
  • Tokens are scoped to the installed repositories
  • Tokens auto-expire after 1 hour and are refreshed automatically