Getting Started
gh-org-tool is a Next.js 16 application that connects to GitHub through a GitHub App installation. It ingests contributor activity across repositories, computes configurable scores, and serves the results through leaderboards and organization management tools.
There is no separate backend service. The Next.js app is the entire system — API routes, frontend, and background jobs in a single Vercel deployment.
What it does
| Capability | Notes |
|---|---|
| GitHub App OAuth sign-in | Browser redirect flow; session stored as encrypted httpOnly cookie |
| GitHub App installation (org-level) | Admin installs the app on a GitHub org; grants repository access |
| Contributor leaderboards | Commits, PRs, issues, reviews — weighted by a scoring preset |
| Team leaderboards | Aggregate scores across team members |
| Repository leaderboards | Per-repo contributor rankings |
| Configurable scoring presets | Admin-defined weights stored in DB; hot-swappable |
| GraphQL proxy | 8-operation allowlist; forwards authenticated queries to GitHub |
| Bulk org member invitations | Invite by username list; respects rate limits |
| Analytics dashboards / heatmaps | Planned — not yet implemented |
| Team management UI | Planned — not yet implemented |
| Role management UI | Planned — not yet implemented |
How sign-in works
- Visit the app. The landing page shows a Sign in with GitHub button.
- GitHub OAuth redirect → callback hits
/api/auth. - A session is created in the
auth_sessionstable. The GitHub token is AES-256-GCM encrypted before storage. - Subsequent requests carry a
gh_sessionhttpOnly cookie; the decrypted token lives only in-memory during request handling. - To see leaderboard data, your organization must have the GitHub App installed. The sign-in flow offers an install link.
Quick links
| I want to… | Go to |
|---|---|
| Run this locally | Local Development |
| Understand all env vars | Environment Variables |
| Understand the system design | Architecture Overview |
| Understand how a request is handled | Request Lifecycle |
| Understand how data moves | Data Flow |
| Understand scoring and presets | Scoring Overview |
| Read the API reference | API Overview |
| Read the database schema | Database Schema |
Related
Last updated on