GitHub connector setup

This page is the setup half — creating the OAuth app GitHub needs in its own developer settings and getting its client id and secret into this deployment. Authorising a connection afterwards is the Authenticate control on the plugin sheet, which is what actually sends you to GitHub.

1. Create the OAuth app in GitHub's developer settings

1. Open GitHub's OAuth Apps settings and register a new OAuth application — this is your own app, not Botseon's.

2. Under Authorization callback URL, paste the redirect URL from docs/connectors/README.md — with the quickstart's default BOTSEON_PUBLIC_URL, that is:

   http://127.0.0.1:3000/api/oauth/github/callback
   

3. Register the application. GitHub shows you a Client ID and lets you generate a Client secret — copy both now.

2. Scopes

Request the narrowest set that covers the tools this connector exposes (F-PLUG-1: minimum scopes per capability, read and write requested separately):

• public_repo — read and write access limited to public repositories.
• read:org — read an organisation's membership and teams; no writes.
• read:user — read the connected account's own profile.
• repo — full read and write access to public and private repositories.

GitHub has no private-read-only scope: the repo grant is what reads a private repository, and the consent screen says so at authorisation.

3. Enter the app

One command, with the client secret on standard input — there is no flag that takes it and no environment variable that holds it (see docs/connectors/README.md):

printf %s "$CLIENT_SECRET" | botseon oauth-app set \
  --org <organisation id> --slug github \
  --client-id <the client ID from step 1> \
  --auth-url https://github.com/login/oauth/authorize \
  --token-url https://github.com/login/oauth/access_token \
  --configured-by <your user id>

Both URLs are read from GitHub's own current documentation (Authorizing OAuth apps), not invented here.

It stores the secret encrypted and prints the redirect URL from step 1 back, so you can check the two match. botseon oauth-app show --org <organisation id> --slug github says whether an app is configured and under which client id; nothing prints the secret back.

Never put either value in a bot's description, a memory, or anywhere else a model reads as ordinary text.