Skip to main content
Use a GitHub App to connect private repos and enable GitHub‑based automation triggers.

​
What This Enables

  • Private repo cloning in sandboxes
  • Org‑wide repo access via installation tokens
  • GitHub webhook triggers (when webhooks are reachable)

​
What You’ll Get

  • GITHUB_APP_ID
  • GITHUB_APP_PRIVATE_KEY
  • GITHUB_APP_WEBHOOK_SECRET
  • NEXT_PUBLIC_GITHUB_APP_SLUG

​
GitHub App Setup (Self‑Host, Full Checklist)

1

Create the GitHub App

Go to Settings → Developer settings → GitHub Apps → New GitHub App.If you are creating it for an org, use Org Settings instead of personal settings.
2

Required app info

GitHub App name
  • Any name, e.g. proliferate-self-host
Homepage URL
  • Your app URL (example: https://proliferate.example.com)
Callback URL
  • Must be exactly: https://YOUR_APP_URL/api/integrations/github/callback
Webhook URL
  • Must be exactly: https://YOUR_APP_URL/api/webhooks/github-app
Webhook secret
  • Generate a new secret and use it for GITHUB_APP_WEBHOOK_SECRET
3

Permissions

Minimum permissions for cloning and repo access:
  • Repository permissions
  • Contents: Read-only
  • Metadata: Read-only
If you want GitHub webhook triggers for PRs/issues/checks, also enable:
  • Pull requests: Read-only
  • Issues: Read-only
  • Commit statuses: Read-only
  • Checks: Read-only
Organization permissions (optional):
  • Members: Read-only (only if you need org user data)
4

Webhook events

Enable these events for triggers:
  • push
  • pull_request
  • issues
  • check_suite
  • check_run
  • workflow_run
If your app URL is not publicly reachable, webhook delivery will not work. Cloning still works without webhooks.
5

Generate the private key

In your GitHub App settings:
  • Click Generate a private key
  • Download the .pem file
  • This content becomes GITHUB_APP_PRIVATE_KEY
6

Install the app

Go to the app page and click Install App.Choose:
  • All repositories (recommended), or
  • Only selected repositories (more restrictive)
The installation ID is used internally; you don’t have to set it manually.
7

Set environment variables

Add these to .env or .env.local:
GITHUB_APP_ID=123456
GITHUB_APP_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
GITHUB_APP_WEBHOOK_SECRET=your_webhook_secret
NEXT_PUBLIC_GITHUB_APP_SLUG=your-app-slug
Notes:
  • GITHUB_APP_PRIVATE_KEY must preserve newlines (\n)
  • NEXT_PUBLIC_GITHUB_APP_SLUG is the app slug from: https://github.com/apps/<slug>
8

Restart services

docker compose down
docker compose up -d
9

Verify

  • In the Proliferate UI, go to Settings → Connections
  • You should see GitHub as connected after install
  • Try a repo clone flow to confirm

​
Optional: GitHub App Manifest

Use this if you want to create the app from a manifest instead of the GitHub UI. Replace YOUR_APP_URL.
The manifest flow redirects to redirect_url with a temporary code. If you don’t have a handler for that code, use the manual setup above.
{
  "name": "proliferate-self-host",
  "url": "https://YOUR_APP_URL",
  "hook_attributes": {
    "url": "https://YOUR_APP_URL/api/webhooks/github-app",
    "active": true
  },
  "redirect_url": "https://YOUR_APP_URL",
  "callback_urls": [
    "https://YOUR_APP_URL/api/integrations/github/callback"
  ],
  "public": false,
  "default_permissions": {
    "metadata": "read",
    "contents": "read",
    "issues": "read",
    "pull_requests": "read",
    "checks": "read",
    "statuses": "read"
  },
  "default_events": [
    "push",
    "pull_request",
    "issues",
    "check_suite",
    "check_run",
    "workflow_run"
  ],
  "request_oauth_on_install": false
}
If you don’t need GitHub triggers, remove default_events entries and the extra permissions.
After creating the app from a manifest, set the webhook secret in GitHub to match GITHUB_APP_WEBHOOK_SECRET.

​
Troubleshooting

  • YOUR_APP_URL must be publicly reachable for GitHub webhooks
  • For local testing, use a tunnel and update NEXT_PUBLIC_APP_URL
  • Make sure GITHUB_APP_PRIVATE_KEY includes the full PEM block
  • Ensure GITHUB_APP_ID is correct (numeric)
  • Check installation scope (all repos vs selected)
  • Verify permissions include Contents: Read-only