GitHub App

Register the app

Go to your organization's settings on GitHub: Settings → Developer settings → GitHub Apps → New GitHub App (or open https://github.com/organizations/<your-org>/settings/apps/new). Create a standard GitHub App, not GitHub's newer "Agentic App" type. Fill in:

• GitHub App name: anything recognizable, for example Proliferate (Company). GitHub derives the app's URL slug from this name; you will need the slug later.
• Homepage URL: https://<site>
• Callback URL: https://<site>/auth/github-app/user-authorization/callback
• Expire user authorization tokens: enabled
• Request user authorization (OAuth) during installation: leave disabled
• Setup URL (under Post installation): https://<site>/auth/github-app/installation/callback
• Webhook: Active, with Webhook URL https://<site>/v1/cloud/webhooks/github-app
• Webhook secret: generate a random value (for example openssl rand -hex 32) and save it; the server needs it as GITHUB_APP_WEBHOOK_SECRET.

Grant permissions

Under Repository permissions, grant:

GitHub may warn that Contents "Read and write" can't be used for Agentic Apps. That warning applies only to GitHub's Agentic App type; this is a standard GitHub App, so ignore it.

No event subscriptions are needed. GitHub always delivers the installation events the server consumes to the app's webhook.

Under Where can this GitHub App be installed?, choose Only on this account. Then click Create GitHub App.

Collect the app's identity

The app's settings page now shows most of the values the server needs:

• App ID (a number, in the About section)
• Client ID
• The app's slug: the last path segment of its public link, https://github.com/apps/<slug>
• Click Generate a new client secret and copy it; GitHub shows it only once.

Generate a private key

Scroll to Private keys, click Generate a private key, and download the .pem file. This key is what lets the server mint installation tokens, so treat it like a root credential.

Place it on the deploy host, in the directory the Docker stack bind-mounts read-only into the API container for exactly this purpose (default /opt/proliferate/secrets/github-app, created by the installer; override with GITHUB_APP_PRIVATE_KEY_HOST_PATH if you use a different install root):

sudo install -m 600 downloaded-key.pem /opt/proliferate/secrets/github-app/github-app.pem

Install the app

From the app's settings page, choose Install App and install it on your organization. Select all repositories or only the ones your team works in; you can change this later, and the server picks up changes automatically through the webhook.

Configure the Proliferate server

Add the GITHUB_APP_* variables to your env file (.env.static in the deploy directory):

One variant, in case you'd rather not manage a file on the host:

• GITHUB_APP_PRIVATE_KEY holds the key inline instead of GITHUB_APP_PRIVATE_KEY_PATH; escape newlines as \n.
• GITHUB_APP_CALLBACK_BASE_URL overrides the base used to build callback URLs. It defaults to your server's API base URL, which is correct for the standard stack, so most installs leave it unset.

Apply by running the update script from the deploy directory (it regenerates the runtime env and restarts the stack):

./update.sh

Verify

Create a cloud workspace from the desktop app and confirm the sandbox clones a repository the app is installed on. On the GitHub App settings page, Advanced → Recent Deliveries should show your webhook deliveries answered with 2xx responses. If deliveries fail, re-check the webhook URL and that GITHUB_APP_WEBHOOK_SECRET matches the secret configured on GitHub. Webhook delivery is not on the critical path for authorization or installation — a missed delivery only briefly staleifies the server's cached repository-selection scope, which a later Setup URL callback refreshes.

If you click through the install/authorization flow directly (outside the desktop app) and your deployment has no separate web frontend (FRONTEND_BASE_URL unset — the default for a self-hosted install), the callbacks land on a server-rendered /auth/github-app/connected page instead of a 404. No configuration is needed for that page to work.