Skip to content

README.md

Latest commit

 

History

History
193 lines (138 loc) · 7.86 KB

README.md

File metadata and controls

193 lines (138 loc) · 7.86 KB

Copilot Collections Dashboard

Take control of your GitHub Copilot spending. Copilot Collections Dashboard gives engineering leaders full visibility into how their organization uses GitHub Copilot — across seats, teams, and departments — so they can optimize adoption and manage premium request costs before they spiral.

Built with Copilot Collections by The Software House.

🤔 The Problem

GitHub Copilot is a powerful tool, but organizations adopting it at scale face real challenges:

  • 💸 No spending visibility — GitHub provides limited insight into per-user and per-team premium request costs. You see the bill, not the breakdown.
  • 🪑 Inactive seats burn money — Seats assigned to users who rarely (or never) use Copilot keep costing the same as active ones. Identifying them manually is tedious.
  • 👥 No team-level accountability — Engineering managers can't see how their team's usage compares to others, making it impossible to justify costs or encourage adoption.
  • 🚨 Premium request overruns — Each seat includes an allowance of premium requests. When users exceed it, the organization pays extra — often without realizing it until the invoice arrives.
  • 📉 Historical tracking is missing — Team compositions change month-over-month, but there's no built-in way to track usage trends over time as people move between teams.

✨ Key Features

📊 Dashboard & Analytics

  • Monthly usage overview with total seats, active seats, spending, and premium request metrics at a glance
  • Per-user breakdown — see exactly how many premium requests each person used and what it cost
  • Allowance tracking — see included vs. used vs. paid premium requests with visual progress indicators
  • Model-level cost breakdown — understand spending per AI model (Claude Sonnet, GPT-4o, etc.)
  • Most & least active users — instantly spot top contributors and inactive seats
  • Spending breakdown — separate seat license costs from paid premium request overage
  • Monthly snapshots — team compositions are tracked per month so historical comparisons remain accurate even when people move between teams

⚙️ Automated Data Collection

  • Background jobs run on a configurable schedule (default: daily at midnight UTC)
  • Seat sync pulls the latest seat list from GitHub
  • Usage collection fetches premium request data for each active seat

💺 Organisation Management

  • Teams — group seats into teams, track usage per team, and compare across teams
  • Departments — organize seats into departments for higher-level reporting
  • Editable metadata — assign first name, last name, and department to each seat

🔐 Security & Authentication

  • Two authentication modes: built-in credentials or Azure Entra ID (Azure AD) via OAuth 2.0 PKCE
  • GitHub App integration — no long-lived tokens. Credentials are stored encrypted in the database using AES-256
  • Setup wizard — guided first-run flow creates the GitHub App, installs it on your organization, and configures everything through the UI

🔧 Configuration

Environment Variables

Required

Variable Description
DATABASE_URL PostgreSQL connection string (e.g. postgres://user:pass@host:5432/dbname)
ENCRYPTION_KEY 64-char hex string for encrypting GitHub App credentials. Generate with openssl rand -hex 32
APP_BASE_URL Public URL of the application (e.g. https://copilot-dashboard.yourcompany.com)
DEFAULT_ADMIN_USERNAME Username for the initial admin account
DEFAULT_ADMIN_PASSWORD Password for the initial admin account

Authentication

Variable Description Default
AUTH_METHOD credentials (built-in login) or azure (Azure Entra ID SSO) credentials
SESSION_TIMEOUT_HOURS Session expiry in hours 24

When using Azure Entra ID (AUTH_METHOD=azure):

Variable Description
AZURE_TENANT_ID Azure AD tenant ID
AZURE_CLIENT_ID Azure AD application (client) ID
AZURE_REDIRECT_URI OAuth callback URL (e.g. https://copilot-dashboard.yourcompany.com/api/auth/azure/callback)

Data Sync

Variable Description Default
SYNC_CRON_SCHEDULE Cron expression for background sync jobs 0 0 * * * (daily at midnight)
SEAT_SYNC_ENABLED Enable automatic seat synchronization true
USAGE_COLLECTION_ENABLED Enable automatic usage data collection true
SEAT_SYNC_RUN_ON_STARTUP Trigger seat sync immediately on app start false
USAGE_COLLECTION_RUN_ON_STARTUP Trigger usage collection immediately on app start false

Note: No GitHub token environment variable is required — GitHub App credentials are stored encrypted in the database and configured through the setup wizard.

🐙 GitHub App Setup

The dashboard connects to GitHub through a GitHub App (not a personal access token). On first launch, the setup wizard walks you through:

  1. Create the GitHub App — the app generates a manifest and redirects you to GitHub to create it
  2. Install on your organization — select which organization (or enterprise) to monitor
  3. Automatic configuration — the app detects your setup (org vs. enterprise) and starts syncing

No manual token management needed. The private key is encrypted at rest in the database.

🚀 Installation

🐳 Docker (Recommended)

The fastest way to get running. The Docker image includes automatic database migrations on startup.

1. Create a .env file:

DATABASE_URL=postgresql://postgres:postgres@postgres:5432/copilot_dashboard
ENCRYPTION_KEY=          # Generate with: openssl rand -hex 32
APP_BASE_URL=http://localhost:3000
DEFAULT_ADMIN_USERNAME=admin
DEFAULT_ADMIN_PASSWORD=changeme

2. Start the application:

docker compose up

This starts PostgreSQL, runs migrations automatically, and launches the dashboard on http://localhost:3000.

3. Complete the setup wizard — open the app in your browser, log in with your admin credentials, and follow the guided GitHub App setup.

☸️ Kubernetes (Helm)

A Helm chart is included for Kubernetes deployments:

helm install copilot-dashboard ./helm/copilot-dashboard \
  --set env.DATABASE_URL="postgresql://..." \
  --set env.ENCRYPTION_KEY="..." \
  --set env.APP_BASE_URL="https://copilot-dashboard.yourcompany.com" \
  --set env.DEFAULT_ADMIN_USERNAME="admin" \
  --set env.DEFAULT_ADMIN_PASSWORD="changeme"

🛠️ Development Setup

# Install dependencies
npm install

# Start PostgreSQL
docker compose up postgres -d

# Run database migrations
npx ts-node -P tsconfig.typeorm.json scripts/run-migrations.ts

# Start development server
npm run dev

Available Scripts

Command Description
npm run dev Start Next.js dev server
npm run build Production build
npm run lint ESLint
npx tsc --noEmit Type checking
npx vitest run Unit/integration tests
npx playwright test E2E tests (credentials mode)
npx playwright test --config playwright.azure.config.ts E2E tests (Azure mode)

🧱 Tech Stack

  • Next.js 16 (App Router, React 19, standalone output)
  • PostgreSQL 16 with TypeORM
  • Tailwind CSS 4
  • Recharts for data visualization
  • Arctic for Azure Entra ID OAuth
  • node-cron for background job scheduling

📄 License

MIT