Skip to content

github-app-setup.mdx

Latest commit

 

History

History
51 lines (34 loc) · 2.57 KB

github-app-setup.mdx

File metadata and controls

51 lines (34 loc) · 2.57 KB
Raw
title GitHub App Setup
description One-time setup of the GitHub App that powers sign-in, webhooks, and automation.

This is a one-time, manual setup step that needs org-owner access on trickfirerobotics. Everything else in the app assumes this App already exists.

1. Create the App

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

  • GitHub App name: TrickFire Tasks (or similar - must be globally unique across GitHub)
  • Homepage URL: https://tasks.trickfirerobotics.com
  • Redirect URL: https://tasks.trickfirerobotics.com/api/auth/callback/github (add http://localhost:3006/api/auth/callback/github too, for local dev)
  • Request user authorization (OAuth) during installation: checked - this is what lets the same App handle sign-in, not just automation
  • Webhook URL: https://tasks.trickfirerobotics.com/api/webhooks/github
  • Webhook secret: generate one (openssl rand -hex 32) and save it for GITHUB_WEBHOOK_SECRET

2. Permissions

Repository permissions:

  • Issues: Read and write
  • Pull requests: Read and write
  • Metadata: Read-only (mandatory default)

Organization permissions:

  • Members: Read-only (used to gate sign-in to org members)

3. Subscribe to events

  • Issues
  • Issue comment
  • Pull request
  • Installation
  • Installation repositories

4. Generate credentials

  • App ID: shown on the App's settings page → GITHUB_APP_ID
  • Client ID / Client secret: under "OAuth Credentials" on the same page → GITHUB_APP_CLIENT_ID / GITHUB_APP_CLIENT_SECRET
  • Private key: "Generate a private key" → downloads a .pem file. Paste its contents into GITHUB_APP_PRIVATE_KEY, replacing real newlines with literal \n so it fits on one env var line (the app un-escapes it at startup - see src/lib/github/app.ts).

5. Install it on the org

From the App's settings page, Install App, choose trickfirerobotics, and select every repo any project might ever link to (or "All repositories" - simplest if the whole org is fair game). The installation's row gets recorded in the github_installation table automatically the first time it's used, or via the installation.created webhook.

Result

Set GITHUB_APP_ID, GITHUB_APP_CLIENT_ID, GITHUB_APP_CLIENT_SECRET, GITHUB_APP_PRIVATE_KEY, GITHUB_WEBHOOK_SECRET, and GITHUB_ORG=trickfirerobotics in the environment (.env.local for dev, .env.production on the server). Sign-in, webhooks, and the reconciliation job all come alive together once these are set - there's no separate "enable" step.