Welcome
gh-org-tool is a self-hosted dashboard for GitHub organizations. Connect it to your org through a GitHub App, and you get contributor leaderboards, analytics, bulk member management, and configurable scoring — all running on your own Vercel account.
Think of it as the ops dashboard GitHub doesn’t give you.
I want to…
| I want to… | Go here |
|---|---|
| Set this up on my machine | Local Development |
| Understand what every env var does | Environment Variables |
| Run or write tests | Testing |
| See how the system is designed | Architecture Overview |
| Understand how requests flow through auth | Request Lifecycle |
| See every API route | API Reference |
| Understand how scoring works | Scoring Overview |
| Tweak or create scoring presets | Presets & Configuration |
| Invite members or manage teams | Organization Management |
| Understand the analytics pages | Analytics Guide |
| Find a component or hook | Frontend Overview |
| Look up a database table | Database Schema |
| Deploy to production | Deployment |
| Debug a problem | Common Issues |
| Contribute code | Onboarding |
| See what’s broken or unfinished | Known Issues |
What’s in the box
| Feature | Status |
|---|---|
| GitHub App sign-in (encrypted sessions, httpOnly cookies) | ✅ |
| Contributor leaderboards with configurable scoring | ✅ |
| Team leaderboards | ✅ |
| Repository leaderboards | ✅ |
| Scoring presets — create, edit, delete, import, export | ✅ |
| Analytics dashboards, heatmaps, and timelines | ✅ |
| Bulk member invitations (username list, JSON, CSV, XLSX) | ✅ |
| Bulk team membership management | ✅ |
| Bulk role changes (member/admin) | ✅ |
| GraphQL proxy with 8-operation allowlist | ✅ |
| Full-text docs search | ✅ |
How the docs are organized
Getting Started — install, configure, and run locally.
Architecture — system design, request lifecycle, data flow, and the six caching layers.
Frontend — pages, components, data-fetching hooks, Zustand stores, and auth gating.
Backend — all 37 API routes, auth, authorization, GraphQL proxy, webhooks, and background jobs.
Scoring — the three-phase ingest → score → serve pipeline, the scoring engine, and preset management.
Database — the 26-table schema, migration management, and the repository pattern.
Infrastructure — Vercel deployment, CI/CD, security posture, and docs search.
Guides — walkthroughs for organization management, leaderboards, and analytics.
Contributing — onboarding, code conventions, project structure, and known issues.
Troubleshooting — common errors and how to fix them.