Skip to content

setup-github-app.md

Latest commit

 

History

History
98 lines (68 loc) · 5.29 KB

setup-github-app.md

File metadata and controls

98 lines (68 loc) · 5.29 KB
Raw

GitHub App setup

GitHub App Wizard Docs index

Codasaurus reviews PRs as a GitHub App. Prefer the dashboard onboarding wizard (manifest flow). Use this guide for manual registration or troubleshooting.

Permissions

Permission Access Why
Pull requests Read & Write Reviews, comments, labels, requested reviewers
Contents Read & Write (Write for @codasaurus fix) Diffs, file fetch, optional branch writes
Issues Read & Write Linked-issue context, assessment
Checks Read & Write Optional Check Runs
Reactions Read 👎 / confused on finding comments → learn dismiss
Metadata Read Required baseline

Subscribe to events: Pull request · Issue comment · Reaction · Installation · Installation repositories

Webhook URL: https://<your-host>/webhook (trailing slash is also accepted). Generate a secret: openssl rand -hex 32.

App icon / badge

GitHub’s create-from-manifest API does not accept a logo. There is also no REST endpoint to set the App badge after conversion — you upload it in the UI:

  1. Open GitHub → Settings → Developer settings → GitHub Apps → [your app] → Display information.
  2. Upload the logo (PNG/JPG/GIF, < 1 MB). Use our bundled mark: assets/logo.png or download from your deploy at https://<host>/branding/logo.png.

The bot identity in PR threads uses that badge; until you upload one, GitHub shows the default identicon.

Manifest flow (wizard)

  1. In the wizard, click Create GitHub App.
  2. GitHub opens a pre-filled form (POST manifest from /api/setup/github/manifest-page) with permissions, events, webhook URL, description, and callbacks.
  3. Confirm → GitHub redirects to /api/setup/github/callback with a one-time code.
  4. Codasaurus exchanges the code, stores App ID / PEM / webhook secret / slug, and returns you to the wizard.
  5. (Optional) Upload the App icon as above — the wizard surfaces /branding/logo.png.

PUBLIC_URL (or the request Host) must match the URL GitHub can reach for webhooks and callbacks. The manifest sets the callback to /api/setup/github/callback (App creation), not a user OAuth login endpoint.

Manual credentials

Settings → Developer settings → GitHub Apps → New GitHub App, then set:

Field Value
Name codasaurus (or yours)
Homepage your deployment URL
Webhook URL https://<host>/webhook
Webhook secret from openssl rand -hex 32
Callback URL https://<host>/api/setup/github/callback

Generate a private key (.pem). Never commit it.

Environment

export GITHUB_APP_ID="123456"
# PEM with literal newlines, or base64:
export GITHUB_APP_PRIVATE_KEY="$(cat codasaurus.pem)"
# export GITHUB_APP_PRIVATE_KEY_B64="$(base64 < codasaurus.pem)"
export GITHUB_WEBHOOK_SECRET="…"

The setup wizard and Settings → Connections → GitHub App can store the same fields in the DB. Env vars win when both are set (see configuration.md).

Install on repositories

Install App → choose account/org → select repositories.

Install URL (when slug is known): https://github.com/apps/<slug>/installations/new

Also exposed as github_install_url on GET /api/setup/status and GET /api/github/install-url (authenticated).

Verify

curl -s http://localhost:3000/health

Expect "status":"ok" and an egress_profile. Open a PR on an installed repo. Codasaurus should post a review within the webhook delivery window.

In the dashboard, Settings → Connections → GitHub App → Test connection calls GET /app with your App JWT to confirm credentials without opening a PR.

Common failures

Symptom Check
401 on webhook GITHUB_WEBHOOK_SECRET matches the App setting
No reviews App installed on that repo; events include Pull request
Manifest callback error PUBLIC_URL / TLS / reverse-proxy Host headers
@codasaurus fix fails Contents Write permission + allow_auto_fix in settings