---
title: "GitHub App setup"
source: "docs/github-app-setup.md"
---

> Part of [botgumi docs](https://www.botgumi.com/docs/llms.txt). Every page: [llms.txt](https://www.botgumi.com/llms.txt).

# 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`:

```bash
pnpm wrangler deploy
```

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

```bash
pnpm wrangler secret put GITHUB_WEBHOOK_SECRET
```

```bash
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}`.