One GitHub App for the site, the editor and builds

The exact settings of a GitHub App that signs readers and authors in, lets the web editor commit and open pull requests, and sends push webhooks for builds.

Let the admin console create it

Connect GitHub in the admin console registers an app with exactly these settings through GitHub's app manifest flow, and stores its credentials encrypted, so none of the variables below are needed: see Connect GitHub from the admin console. Create the app by hand only when you prefer to keep its credentials in environment variables.

App settings

Setting	Value
GitHub App name	Any name not yet taken on GitHub, such as `Acme docs`
Homepage URL	`$PUBLIC_URL`
Callback URLs	`$PUBLIC_URL/auth/github/callback` (reader sign-in) and `$EDITOR_PUBLIC_URL/auth/github/callback` (author sign-in)
Request user authorization (OAuth) during installation	Off
Setup URL	Empty (an app made by Connect GitHub uses `$PUBLIC_URL/admin/github/installed`, which stores the installation)
Webhook	Active; URL `$PUBLIC_URL/webhooks/github`; secret: the value of `GITHUB_WEBHOOK_SECRET`
Repository permissions	Contents: Read and write. Pull requests: Read and write. Administration: Read-only. Commit statuses: Read and write (the editor only reads them; builds report to them). Checks: Read-only. Metadata: Read-only.
Account permissions	Email addresses: Read-only
Subscribe to events	Push
Where can this GitHub App be installed?	Only on this account

After creating it, generate a client secret and a private key, install the App on the docs repository, and note the installation id from the installation's URL. Register the repository with that installationId.

A pre-filled registration link

GitHub opens the registration form pre-filled from query parameters. The repository's script prints the link for your two hosts; open it while signed in to GitHub, set the webhook secret (the one value GitHub does not take from a link), and create the App.

node scripts/github-app-url.mjs https://docs.example.com https://edit.docs.example.com
# for an organization's App:
node scripts/github-app-url.mjs https://docs.example.com https://edit.docs.example.com "Acme docs" --org acme

Which service gets which variable

Variable	Docs site (web)	Worker	Editor
`GITHUB_APP_ID`, `GITHUB_APP_PRIVATE_KEY`	Yes	Yes	Yes
`GITHUB_OAUTH_CLIENT_ID`, `GITHUB_OAUTH_CLIENT_SECRET`	Yes, for reader sign-in	No	Yes, for author sign-in
`GITHUB_WEBHOOK_SECRET`	Yes	No	No
`EDITOR_PUBLIC_URL`	Optional: Edit this page links	No	Required
`PUBLIC_URL`	Required	Same as web	Recommended: refuses to share the docs host

See Let readers sign in with GitHub, Run the web editor and Connect GitHub: webhooks and the GitHub App.