github-app-setup — create your own GitHub App for Heimdall
Read and follow references/github-app-setup/protocol.md (protocol SSOT).
What it achieves
When you choose --post --github-app in /local-pr-review, the review posts as your GitHub App
(<app-name>[bot]), not as github-actions[bot] nor as your user. It is the same
model as CodeRabbit / Greptile, but with your own App and 100% local.
It does not depend on the ChimeraNext App: each founder creates their own.
Step summary (details in the protocol)
Create the App in the ORG settings:
https://github.com/organizations/{organization-id}/settings/apps/new- Permissions:
Pull requests: Read & write+Issues: Write(to comment on the PR thread) +Contents: Read-only+Metadata: Read-only. - Do not check
Expire user authorization tokens,Request user authorization (OAuth), orEnable Device Flow(they are user OAuth; Heimdall uses installation tokens).
- Permissions:
Generate and save the private key:
~/.agents/heimdall-review.pem(mode 0600).Register in
~/.agents/.heimdall.env:HEIMDALL_GITHUB_APP_ID=<app_id> HEIMDALL_GITHUB_APP_KEY=~/.agents/heimdall-review.pemInstall the App in your org and select the repos.
Verify (dry-run first):
heimdall-review pr <n> --github-app heimdall-review pr <n> --post --github-app
Manifest template
references/github-app-setup/github-app-manifest.json — reusable for creating the App.
Verify installation across multiple orgs
If the App will be installed across multiple organizations, use the standalone verification
script (real example in chimeranext/internal-org-gate → scripts/check-heimdall-app-installs.mjs):
GH_TOKEN=... node scripts/check-heimdall-app-installs.mjs
Lists the orgs with the App installed vs. the missing ones. GitHub does not allow one App to install another automatically: this script only tells you where the admin's manual click is missing.
Launch the command
Use /assurance:github-app-setup to run this guide interactively with the founder.