Prerequisites

• Node.js 24
• pnpm 10.33.1 (npm install -g pnpm@10.33.1)
• A GitHub account with ability to create a GitHub App
• A Supabase project (free tier works)
• Optional: an Upstash Redis instance

Step 1 — Clone and Install

git clone https://github.com/CodeChefVIT/gh-org-tool.git
cd gh-org-tool
pnpm install

Step 2 — Create a GitHub App

You need a GitHub App to handle OAuth and API calls. See /docs/setup/local-development for the full GitHub App creation walkthrough.

Key settings for local development:

• Homepage URL: http://localhost:3000
• Callback URL: http://localhost:3000/api/auth (exact match required)
• Setup URL (post-install): http://localhost:3000/api/install/callback
• Webhook URL: use a tunnel (e.g. ngrok) pointing to http://localhost:3000/api/webhooks/github
• Required permissions: organization members read, repository contents read, pull requests read, issues read, teams read

Step 3 — Create a Supabase Project

1. Create a new project at supabase.com 
2. Run all migrations in order from supabase/migrations/ (001 through 011):

npx supabase db push

Or apply them manually via the Supabase SQL Editor.

Step 4 — Configure Environment Variables

cp example.env .env.local

Fill in all required values in .env.local. Required fields:

GITHUB_APP_ID=
GITHUB_APP_NAME=
GITHUB_PRIVATE_KEY=
GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=
GITHUB_WEBHOOK_SECRET=
AUTH_SESSION_SECRET=            # min 32 chars
TOKEN_ENCRYPTION_KEY=           # min 64 hex chars
NEXT_PUBLIC_APP_URL=http://localhost:3000
NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_DEFAULT_KEY=
SUPABASE_SERVICE_ROLE_KEY=

Redis vars are optional — leave them blank to use DB/memory cache:

UPSTASH_REDIS_REST_URL=
UPSTASH_REDIS_REST_TOKEN=

Step 5 — Start the Dev Server

pnpm dev

The app runs on http://localhost:3000. Turbopack is enabled in dev for faster rebuilds.

Step 6 — Sign In and Install

1. Go to http://localhost:3000
2. Click Sign in with GitHub — this triggers the OAuth flow
3. After sign-in, you are prompted to install the GitHub App on an organization
4. Complete the installation
5. The leaderboard for that organization is now available

Running Tests

# Interactive watch mode
pnpm test
 
# With v8 coverage (same as CI)
pnpm test:ci

Test files live next to the code they test:

• lib/scoring/normalize.test.ts
• lib/scoring/engine.test.ts
• lib/scoring/rules.test.ts
• lib/leaderboard/pipeline.test.ts
• lib/github/ingest-profile.test.ts

Test utilities are in lib/test/ — setup.ts, supabase-mock.ts, octokit-mock.ts.

Linting and Formatting

pnpm lint          # ESLint
pnpm format        # Prettier (if script exists) or: pnpm exec prettier --write .

Pre-commit hooks run Prettier automatically on staged files via husky + lint-staged. You do not need to run Prettier manually before committing.