botgumi

Guides

GitHub App setup (`botgumi[bot]`)

The bots act as a GitHub App, not as you. Its actions show as botgumi[bot], its tokens are short-lived, and it reaches only the repos you install it on. botgumi does not create the App for you; follow these steps.

1. Create the App

GitHub → Settings → Developer settings → GitHub Apps → New GitHub App.

  • Name: botgumi (shown as botgumi[bot]). If the name is taken, pick another and use it everywhere below.
  • Homepage URL: your botgumi repo.
  • Logo: docs/assets/mark.png (512 × 512).
  • Webhook: active. URL: your deployed relay, https://botgumi-relay.<subdomain>.workers.dev/github. Secret: a long random string; you will store it as the relay's GITHUB_WEBHOOK_SECRET.
  • Where can this App be installed: only on this account.

2. Permissions

Repository permissions:

Permission Access Used for
Issues Read and write Create, label, comment on and close task issues
Pull requests Read and write Open PRs, post reviews, merge under the merge policy, open reverts
Contents Read and write Push branches; merging needs it
Commit statuses Read and write ios-ci and botgumi/review (android-ci comes from the Android workflow itself)
Metadata Read-only Required by GitHub

Account permissions:

Permission Access Used for
Projects Read and write Keep the Project board current

Subscribe to events: Issues, Issue comment, Pull request, Pull request review, Status, Check run.

3. Keys and install

  1. Generate a private key. Store it in your secrets source (1Password or similar), never in a repo. Note the App ID.
  2. Install the App on the app repos you choose, not on all repos. Note the installation ID.
  3. Add the App ID, installation ID and private key to the app's secrets inventory (docs/checklists/secrets-inventory.md).

4. Deploy the relay

From packages/ts/relay:

pnpm wrangler deploy

Then set its secrets, using the webhook secret from step 1 and a new random runner token:

pnpm wrangler secret put GITHUB_WEBHOOK_SECRET
pnpm wrangler secret put RUNNER_TOKEN

5. Branch protection

On each app repo's main, require status checks: the TS CI job, botgumi/review, and each chosen platform's CI (ios-ci, android-ci). The merge policy only merges when all required checks are green.

6. Labels

Create the labels the orchestrator uses: botgumi, gate, track:{backend,ios,android,landing,dashboard,design,docs}, tier:{high,mid,low}, runtime:{claude,codex}.