FixControl opens a Pull Request automatically when an agent produces a patch (the Run-fix → PR flow). FixControl needs a GitHub credential to do that write. You have two options — pick one.
Two options
| GitHub App | Personal Access Token | |
|---|---|---|
| Recommended for | Production, multi-tenant | Single-repo setups |
| Token lifetime | 1 hour, rotated automatically | Static until you revoke it |
| PR attribution | <app-slug>[bot] | Your own account |
| Per-tenant scoping | Yes (per installation) | No — one token, one repo |
| Webhook events | Yes | No |
The App route is the recommended path for production.
Option 1: GitHub App (recommended)
Step 1 — Register the App
Go to github.com/settings/apps/new (or your organization settings) and use:
- Callback URL:
https://<your-host>/api/auth/github/callback - Request user authorization (OAuth) during installation: on
- Enable Device Flow: on
- Webhook URL:
https://<your-host>/api/github/webhook - Webhook secret: a random string of 32+ characters — keep it
- Permissions (Repository):
- Contents — Read & write - Pull requests — Read & write - Workflows — Read & write - Metadata — Read
- Permissions (Account): Email addresses — Read
After saving, download the private key (.pem).
Safety: treat the private key as a password. Anyone holding the PEM can mint tokens as your App.
Step 2 — Install per tenant
A signed-in admin clicks Settings → Integrations → Connect GitHub. FixControl redirects to GitHub's "Install on selected repositories" page. After confirming, the installation is bound to the tenant and FixControl mints a fresh installation token per PR (1h TTL).
Step 3 — Validate the webhook
FixControl verifies every delivery with X-Hub-Signature-256. The secret in GitHub's App settings must match the secret FixControl was configured with. Without a match every delivery is rejected — by design: unsigned webhooks are never trusted.
Option 2: Personal Access Token
Use this for a single-repo install.
Mint a fine-grained PAT scoped to that one repo with Contents: read & write and Pull requests: read & write. A classic token works too, but grants more scope than needed.
PRs show up under your account. There's no webhook — events like pull_request.closed won't reach FixControl.
Webhook setup
App-route only:
- In App settings: Webhook URL =
https://<your-host>/api/github/webhook. - Webhook secret = the exact same string FixControl was configured with.
- Subscribe to the events you need —
Pull requestis the minimum set for the Run-fix flow. - Test it from the Recent Deliveries tab in App settings. A 401 there usually means the secrets don't match.
FAQ
Can I configure both at once? Yes. FixControl picks per tenant: App installation first, then a stored user token, then the PAT. So you can run a production App alongside a single-user PAT setup.
Which repos can FixControl touch? For the App: only the repos you select during installation. For the PAT: only the configured default repo.
What if the installation is removed? The next PR call gets a 401. FixControl invalidates the cached token automatically and surfaces the error — re-enable by installing again from Settings → Integrations.
Are private keys or secrets logged? No. Audit events store the installation ID and GitHub username, never tokens or the PEM.