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. The Docker stack mounts /opt/proliferate/bin into the API container read-only at the same path, so that directory is a convenient home:

sudo install -m 600 downloaded-key.pem /opt/proliferate/bin/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 six GITHUB_APP_* variables to your env file (.env.static in the deploy bundle):

Two variants, in case you need them:

• 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.