This guide walks through the full setup: create a GitHub App, configure Supabase, apply migrations, and get the dev server running.

Prerequisites

• Node.js 20+
• pnpm (npm install -g pnpm)
• A GitHub Account with admin access to at least one organization
• A Supabase Project (free tier works fine)
• Supabase CLI (npm install -g supabase) for running db push

Step 1: Create a GitHub App

This project requires a GitHub App (not a GitHub OAuth App). The distinction matters — GitHub Apps support installation-level permissions and webhooks.

1. Go to GitHub Settings → Developer settings → GitHub Apps → New GitHub App
2. App Name: something unique like my-org-tools-dev
3. Homepage URL: http://localhost:3000
4. Callback URL: http://localhost:3000/api/auth
5. Webhook URL: http://localhost:3000/api/install/webhook (or your ngrok URL)
6. Webhook secret: generate a random string — save it for GITHUB_WEBHOOK_SECRET
7. Permissions:
   • Organization: members (read), teams (read)
   • Repository: metadata (read), contents (read), pull_requests (read), issues (read)
   • Account: email (read)
8. Subscribe to events: installation, installation_repositories
9. Save, then generate a Private Key — download the .pem file
10. Install the app on your target organization

For the webhook URL, GitHub requires HTTPS. If you’re developing locally, use ngrok  to create a tunnel — more on that in the troubleshooting section below.

Step 2: Configure environment variables

cp example.env .env.local

Required variables

Security variables (strongly recommended)

If you skip AUTH_SESSION_SECRET or TOKEN_ENCRYPTION_KEY, the app falls back to derived values from GITHUB_CLIENT_SECRET and GITHUB_APP_ID. Fine for local development, but not recommended for production.

Step 3: Apply Supabase migrations

The app uses 13 migration files in supabase/migrations/.

Link your Supabase project (first time)

npx supabase login
npx supabase link --project-ref <your-project-ref>

Your project ref is the random string in your Supabase URL: https://<project-ref>.supabase.co

Push migrations

npx supabase db push

This applies all 11 migrations in order:

1. 001_enums_and_utilities.sql — custom ENUMs, helper functions and trigger utilities
2. 002_users_and_organizations.sql — normalized users, organizations, and membership tables
3. 003_repositories_and_teams.sql — repository and team scaffolding used by the ingest pipeline
4. 004_relationships.sql — relationship tables and FK constraints between repos, teams and orgs
5. 005_github_installations.sql — cache for GitHub App installation metadata
6. 006_auth_sessions.sql — encrypted session storage and session management helpers
7. 007_scoring_presets.sql — scoring preset definitions and metadata
8. 008_signals.sql — contributor action signals table (the raw events/signals used by scoring)
9. 009_sync_state.sql — ingest/sync tracking and state tables (ingest cooldowns)
10. 010_leaderboard_materializations.sql — leaderboard snapshot / materialization tables and indexes
11. 011_computed_scores.sql — pre-computed score storage for presets and time windows

Verify

npx supabase migration list

All local and remote versions should match 001 through 011.

Manual application (no CLI)

If you’d rather not use the Supabase CLI:

1. Open the Supabase SQL Editor in the dashboard
2. Run each migration file in numeric order — 001 first, then 002, etc.

Step 4: Install dependencies and run

pnpm install
pnpm dev

The app will be available at http://localhost:3000.

Available commands

Step 5: Verify the setup

1. Open http://localhost:3000
2. Click Sign in with GitHub
3. Authorize your GitHub App
4. You should be redirected back with a session cookie (gh_session)
5. Check the Account page — your organizations should appear
6. Install the GitHub App on an organization if it’s not already installed

Troubleshooting

redirect_uri mismatch

The GitHub App callback URL must match exactly — http://localhost:3000/api/auth (no trailing slash, no typos).

session not found after sign-in

• Check that SUPABASE_SERVICE_ROLE_KEY is correct
• Verify migrations were applied: npx supabase migration list
• Check browser cookies: gh_session should be present

Database errors on first run

If you see table-not-found errors, migrations weren’t applied. Run npx supabase db push again.

Webhook events not received locally

GitHub requires HTTPS for webhook URLs. Use ngrok to create a tunnel:

ngrok http 3000

Then update the Webhook URL in your GitHub App settings to https://your-ngrok-url.ngrok.io/api/install/webhook.

Related

• Supabase Configuration — migration strategy and schema design
• Database Schema — complete table reference
• Authentication — how auth flows work