GitHub

GitHub requires a public https:// URL for webhooks. Set up HTTPS before you connect.

GitHub integration uses a GitHub App. Proval can create the app via quick setup, or you can register an existing app manually. Per-repository webhooks are not configured by hand. The App handles delivery.

Prerequisites

• Quick Start completed. Proval is running
• A model provider configured in Proval
• A public https:// URL reachable from GitHub (HTTPS; webhooks use port 7901)

---

Public URL and HTTPS

Webhook URL pattern:

https://<public-host>/webhook/github

Include the port if needed: https://<public-host>:7901/webhook/github.

Terminate TLS with nginx, Caddy, Traefik, or Cloudflare Tunnel and forward to port 7901:

https://proval.example.com/webhook/github   →   http://127.0.0.1:7901/webhook/github

The dashboard can share the same hostname (→ 7900) or stay on an internal port. When the dashboard is served over HTTPS, set COOKIE_SECURE=true on the Proval container.

---

Quick setup (recommended)

Step 1: Start GitHub App registration

1. Dashboard → Git Provider → Connect GitHub App
2. Quick setup → Continue
3. Enter your public base URL (e.g. https://proval.example.com), then Next

Step 2: Create the app on GitHub

Review permissions on GitHub and click Create GitHub App. You return to Proval automatically.

Step 3: Connect a GitHub account (installation)

1. Connect GitHub account
2. Select user or organization and repositories
3. Complete the installation flow

Step 4: Add a repository in Proval

1. Repositories → Add repository
2. Select your GitHub installation and repository
3. Configure model provider and review settings. No webhook secret needed
4. Create

---

Existing app (manual)

1. Git Provider → Connect GitHub App → Existing app
2. Fill in App ID, Slug, Private key (PEM), Webhook secret, Public base URL
3. Confirm the webhook URL matches your GitHub App settings
4. Test Connection, Save
5. Connect account and add repositories as in Steps 3 and 4

The app must subscribe to pull_request and issue_comment (quick setup sets these automatically). The pull_request subscription covers open, synchronize (push), reopen, and ready for review so Proval can review on first push or every push per repository settings. Draft pull requests are skipped until they are marked ready.

---

Troubleshooting

Symptom	Likely cause
Redirect fails after app creation	Public HTTPS URL not reachable; check firewall and proxy
No repositories in dropdown	Installation missing repository access
No review on PR	App not installed on the repository, or webhook URL mismatch
401 on webhook	Webhook secret in GitHub App settings does not match Proval