Raxx · internal docs

internal · gated

GitHub App provisioning runbook

Purpose: Provision three GitHub Apps (raxx-dev-bot, raxx-ops-bot, raxx-pm-bot) so dispatched agents author commits/PRs/issues under bot identities instead of Kristerpher's user account.

Audience: Kristerpher (operator). Steps 1-7 must be done manually in the GitHub web UI; only the org owner can create Apps under raxx-app.

Time: ~30 minutes total (~10 min per App).

Tracking: Issue #335.

Before you start

Per-App provisioning steps

Repeat this whole section three times — once for each of raxx-dev-bot, raxx-ops-bot, raxx-pm-bot. Permissions differ; see the matrix below.

Step 1 — Create the App

  1. Open https://github.com/organizations/raxx-app/settings/apps/new
  2. GitHub App name: raxx-dev-bot (or raxx-ops-bot / raxx-pm-bot)
  3. Description: Use the description from the matrix below.
  4. Homepage URL: https://raxx.app
  5. Webhook → Active: Uncheck (we don't need webhooks for v1).
  6. Repository permissions: set per the matrix below.
  7. Where can this GitHub App be installed? → "Only on this account" (raxx-app org).
  8. Click Create GitHub App.

Step 2 — Note the App ID

After creation you land on the App's settings page. At the top:

App ID: 123456

Copy the App ID. You'll store it in Infisical in step 5.

Step 3 — Generate a private key

Scroll to Private keys at the bottom of the App settings page.

  1. Click Generate a private key.
  2. A .pem file downloads automatically (e.g., raxx-dev-bot.2026-04-25.private-key.pem).
  3. Move it to a scratch directory (~/scratch/ or similar). Do not commit.

Step 4 — Install the App on the repo

  1. From the App's left sidebar click Install App.
  2. Click Install next to raxx-app.
  3. Choose Only select repositories → select TradeMasterAPI.
  4. Click Install.
  5. After install, the URL will look like https://github.com/organizations/raxx-app/settings/installations/12345678. The 12345678 at the end is your Installation ID — copy it.

Step 5 — Store secrets in Infisical

In Infisical, under /MooseQuest/<bot-name>/:

Key Value
APP_ID The App ID from step 2 (numeric)
INSTALLATION_ID The Installation ID from step 4 (numeric)
PRIVATE_KEY_PEM Full contents of the .pem file (including BEGIN/END lines)

Key names must be uppercase. The mint script (scripts/agents/mint_github_token.py) fetches APP_ID, INSTALLATION_ID, and PRIVATE_KEY_PEM by exact name. Lowercase or hyphenated names cause exit 4 ("bot secrets missing keys").

Verify with:

infisical run --env=prod --path=/MooseQuest/raxx-dev-bot -- env | grep -E "(APP_ID|INSTALLATION_ID)"

(Should print the IDs without revealing the PEM.)

Step 6 — Delete the local .pem

rm ~/scratch/raxx-dev-bot.*.private-key.pem

The PEM only lives in Infisical from this point.

Step 7 — Verify token minting

Once scripts/agents/mint_github_token.py lands (PR for issue #335), test:

python scripts/agents/mint_github_token.py --bot raxx-dev-bot
# Should print: ghs_AAAAAAAAA... (installation token, valid 1 hour)

If the token mints correctly, the App is provisioned.

Permissions matrix per App

raxx-dev-bot — Engineering activity

Description: Bot identity for code-writing agents (feature-developer, ux-polisher, ux-designer). Pushes commits, opens PRs, comments on issues.

Permission Level
Contents Read & Write
Pull requests Read & Write
Issues Read & Write
Workflows Read & Write
Metadata Read (default)

Webhooks: none.

raxx-ops-bot — Operations & Security activity

Description: Bot identity for ops agents (sre-agent, security-agent, card-groomer). Files security issues, comments on infra PRs, grooms backlog.

Permission Level
Contents Read
Pull requests Read & Write
Issues Read & Write
Security events Read & Write
Metadata Read

Webhooks: none.

raxx-pm-bot — Product & Architecture activity

Description: Bot identity for design + product agents (product-manager, software-architect, marketing-strategist, business-legal-researcher, data-scientist). Files cards, opens design-doc PRs.

Permission Level
Contents Read & Write
Pull requests Read & Write
Issues Read & Write
Metadata Read
Discussions Read & Write

Webhooks: none.

After all three Apps are provisioned

Comment on issue #335 with:

Provisioned. App IDs:
- raxx-dev-bot: <ID>
- raxx-ops-bot: <ID>
- raxx-pm-bot: <ID>

Private keys stored in Infisical at /MooseQuest/<bot-name>/.

That unblocks the implementation half (token-mint helper + agent dispatch wiring).

Rollback / removal

If something goes wrong (key leaked, App misconfigured):

  1. Revoke the App's installation: https://github.com/organizations/raxx-app/settings/installations → Configure → Uninstall.
  2. Delete the App: https://github.com/organizations/raxx-app/settings/apps → click App → Advanced → Delete this GitHub App.
  3. Delete the Infisical entries: clear /MooseQuest/<bot-name>/.
  4. Agents fall back to Kristerpher's PAT (per the fallback path in #335).

References