Manual app creation#

Use this path to fill in GitHub’s app registration form yourself, generate a client secret and private key, and put the resulting values into the site. This walkthrough uses http://localhost:5000 and does not use the manifest submission or conversion steps. For the recommended submission form and the manifest CLI flow, return to Set up the GitHub App.

1. Prepare the site and choose an app owner#

From the checkout:

make dev
test -f .env || cp .env.development.example .env
mkdir -p data

Set SITE_URL=http://localhost:5000 in .env. Choose a distinct app name of at most 34 characters and use it for SITE_NAME as well. Use a separate app for development and for production.

For a deployed site, use its public HTTPS address everywhere below instead of http://localhost:5000. The OAuth callback and installation setup must point to that same site, and the webhook URL is always the site address plus /github/webhook/. GitHub cannot deliver webhooks to localhost; see Test the GitHub App locally with Tailscale for a public address of the local site with Tailscale Funnel.

Open one of these registration pages while signed in to GitHub:

  • Personal account: settings/apps

  • Organization: https://github.com/organizations/ORGANIZATION/settings/apps/new; replace ORGANIZATION with the organization login. Your account must have permission to register apps there.

2. Fill in the registration form#

Use these values for local development:

Registration fields#

Field

Value

GitHub App name

Your distinct app name; use the same name in SITE_NAME.

Homepage URL

http://localhost:5000

Callback URL

http://localhost:5000/accounts/github/login/callback/

Expire user authorization tokens

Either; the site uses no tokens of people.

Request user authorization (OAuth) during installation

Leave unchecked for this walkthrough. Sign in on the site before installing the app; the separate setup URL then remains available.

Enable Device Flow

Leave unchecked.

Setup URL

http://localhost:5000/setup/installed/

Redirect on update

Selected.

Webhook Active

Selected.

Webhook URL

Your public delivery URL; for a deployed site, https://<your site>/github/webhook/.

Webhook secret

A new random secret; save the same value as GITHUB_WEBHOOK_SECRET.

SSL verification

Enabled for the public HTTPS webhook delivery URL.

Where can this GitHub App be installed?

Any account, so other projects can install the site’s app.

Generate a webhook secret locally, for example:

uv run python -c 'import secrets; print(secrets.token_urlsafe(32))'

The webhook secret is not a client secret. You generate the client secret in step 4. GitHub hides the separate setup URL when OAuth during installation is enabled; leaving that option off here lets GitHub return to /setup/installed/. The site’s Sign in with GitHub button still uses the OAuth callback above.

3. Set permissions and events, then create the app#

Under Repository permissions, set:

  • Metadata: Read-only (GitHub includes it automatically).

  • Contents: Read-only.

  • Pull requests: Read and write.

  • Commit statuses: Read and write.

Under Subscribe to events, select Pull request and Push. Leave other permissions and events at their defaults. The reasons for these permissions are in Permissions of the GitHub App.

Press Create GitHub App. You now have an app registration; it still needs credentials on the site and installation on the repositories.

4. Collect credentials and configure the site#

On the app’s settings page:

  1. Copy the numeric App ID to GITHUB_APP_ID.

  2. Copy the app’s slug from its address, for example the last component of https://github.com/apps/your-app-slug, to GITHUB_APP_SLUG.

  3. Copy Client ID to GITHUB_CLIENT_ID. It differs from the numeric App ID.

  4. Press Generate a new client secret and copy it to GITHUB_SECRET.

  5. Under Private keys, press Generate a private key. Save the downloaded PEM file as data/github-app.pem in the checkout. Use a new filename if that path already holds another app’s key.

Complete these settings in .env, replacing the example values:

SITE_NAME=your-unique-development-app-name
SITE_URL=http://localhost:5000
GITHUB_APP_ID=123456
GITHUB_APP_SLUG=your-app-slug
GITHUB_CLIENT_ID=Iv23...
GITHUB_SECRET=the-client-secret-from-github
GITHUB_WEBHOOK_SECRET=the-webhook-secret-you-chose-in-step-2
GITHUB_APP_PRIVATE_KEY_FILE=data/github-app.pem

Restrict access to the downloaded key:

chmod 600 data/github-app.pem

For Docker, put the PEM file in the host’s data directory, mount it at /app/data/github-app.pem and set GITHUB_APP_PRIVATE_KEY_FILE to that container path. See Run the site with Docker. Keep the key and .env out of version control. All environment settings are described in Settings.

5. Start the site, sign in and install the app#

Run make run or restart it if it is already running. It reads .env and supplies other missing local defaults. For Docker, restart the service with its updated environment. There should be no ai_pycal.W001 warning about missing GitHub App settings.

Open http://localhost:5000/accounts/login/ and select Sign in with GitHub. Then open Setup, press Install the GitHub App and select the repositories. GitHub returns to the site’s installation setup page.

Continue with Set up a repository to add the configuration file and activate a repository. Open a test PR and check the app’s recent webhook deliveries on GitHub if no agreement checks appear.

These steps follow GitHub’s manual app registration guide.