An organization in Bellows is one installation of the GitHub App. Installation access is membership: whoever can see an installation can sign in to that organization.
You need the public URL of your dashboard first. This page writes it as
https://bellows.example.com. It becomes auth.publicUrl in Helm, or PUBLIC_URL in the environment.
1. Register the GitHub App
In GitHub, go to Settings, Developer settings, GitHub Apps, New GitHub App (for an organization, use the organization’s settings).1
Basics
Pick a name and set Homepage URL to your dashboard URL.
2
Setup URL
Set Setup URL to:GitHub sends people here after they install the App. Bellows then restarts sign-in with the new installation selected. If someone returns without installing, sign-in reports that the install was cancelled.
3
Webhook
Optional but recommended. Set Webhook URL to
https://bellows.example.com/api/github/webhook and Secret to a random string of at least 32 characters (openssl rand -hex 32). Bellows refuses to boot with a shorter secret. Keep the webhook active. See Webhook events.Without a webhook secret the route does not exist. Everything still works, but a person removed from the GitHub organization keeps access until their next sign-in.4
Permissions
Grant the repository permissions in the next table.
5
Install target
Choose where the App can be installed, then create it. Note the App ID.
6
Private key
On the App page, under Private keys, click Generate a private key. GitHub downloads a
.pem file.Permissions
For each run, Bellows asks GitHub for a short-lived token limited to the one repository and to Contents (write), Pull requests (write), Issues (write), Checks (read) and Actions (read). If the installation holds less than that, GitHub refuses with a 422 and the error names the missing permission. Add the permission in the App settings, then accept the update on the installation.
Webhook events
Subscribe to these events.
Deliveries are verified with an HMAC signature. Any other event is acknowledged and ignored.
Webhooks only speed things up. A lost delivery is repaired by a periodic read of GitHub.
2. Register the OAuth App
In GitHub, go to Settings, Developer settings, OAuth Apps, New OAuth App.- Homepage URL: your dashboard URL.
- Authorization callback URL:
https://bellows.example.com/api/auth/github/callback. It is<PUBLIC_URL>/api/auth/github/callbackand must match what Bellows sends.
read:org scope, so it can list the installations a person can see. It reads no repository data at sign-in.
3. Give the values to Bellows
The App id and the key are required. Without them the server does not start. A key that is not a PEM is refused with a message that tells you what to paste. One line of base64 survives a
.env file where a multi-line PEM does not.
Do not set
GITHUB_TOKEN, GITHUB_APP_INSTALLATION_ID or ORG_REPOS. Bellows refuses to boot with them. Installations are discovered at sign-in.4. Install it on an organization
1
Install
Open the App’s public page on GitHub and click Install, or open the Bellows sign-in page and click Sign in with GitHub. Choose the organization or account, and the repositories the App may see.
2
Sign in
After installing, GitHub sends you to the Setup URL and Bellows signs you in. On a first sign-in you see Choose organizations and repositories. Pick what Bellows tracks.
3
Check
The organization appears in Bellows, and you are its first member, which makes you an admin. Open Settings → Repositories to see the tracked list.
- More repositories. Update the installation on GitHub, then open Settings → Repositories.
- More people. Anyone who can see the installation can sign in. There are no invites. See Connections for what members connect.
- Changed permissions. GitHub asks an installation owner to accept the update. Runs fail with the 422 above until they do.
Every member sees every repository the organization tracks. GitHub repository permissions are not projected into Bellows. Treat membership as write access to those repositories.