gitgud

A GitHub-based training program platform. Users create training programs from the GitHub orgs they own, becoming the program's first instructor; instructors import rosters from CSV and publish assignments with deadlines and GitHub Actions autograding. Students claim roster entries, join groups, and accept assignments via invitation links — everything lives in real GitHub repos, and scores flow back to the instructor dashboard via workflow webhooks and polling. Students participate as outside collaborators; org membership is managed on GitHub and is out of GitGud's scope.

Stack

• SvelteKit 2 + Svelte 5 (runes), TypeScript
• Tailwind CSS 4
• Drizzle ORM + PostgreSQL 17
• pnpm (≥11, see packageManager in package.json)
• OpenTelemetry (optional OTLP/HTTP export)

Features

• Auth — GitHub sign-in via a GitHub App; instructors are assigned per program, and students are outside collaborators resolved from a claimed roster entry.
• Instructor — create programs from GitHub orgs they own, load students from CSV with an invite/claim flow, create assignments with deadlines and autograding, lock pushes after deadlines, flag late submissions, manage/archive programs and assignments, view score dashboards and export to CSV.
• Student — claim a roster entry, create or join a group, accept assignments via invitation link (per-repo collaborator access for an individual or every group member).
• Autograding — powered by a GitHub Actions workflow already included in the template repo; scores are captured on workflow completion via webhook with polling fallback, and failures/missing workflows are surfaced in the dashboard.

Getting started

Prerequisites: Node ≥24, pnpm 11+, Docker.

pnpm install             # install dependencies
cp .env.example .env     # configure environment (defaults match the dev stack)
pnpm docker:dev          # start PostgreSQL 17 on localhost:5432 and OpenObserve on localhost:5080
pnpm db:migrate          # apply Drizzle migrations
pnpm dev                 # start the dev server

Environment variables (see .env.example):

• DATABASE_URL (required) — PostgreSQL connection string.
• GITHUB_APP_CLIENT_ID, GITHUB_APP_CLIENT_SECRET (required) — GitHub App OAuth credentials; the client ID also serves as the JWT iss when minting installation tokens.
• GITHUB_APP_PRIVATE_KEY (required) — the app's private key (.pem download) as a single line with newlines escaped as \n; used to mint installation access tokens for assignment repo provisioning.
• SESSION_SECRET (required) — any random high-entropy string; it derives the session secret hashing key and the AES-256-GCM key for stored GitHub tokens.
• FAKE_GITHUB_PORT (optional) — for testing; set this to point the tests to a fake GitHub server at http://localhost:${FAKE_GITHUB_PORT}.
• OTEL_EXPORTER_OTLP_ENDPOINT / OTEL_EXPORTER_OTLP_HEADERS (optional) — OTLP/HTTP telemetry export to the local OpenObserve dev service (see docs/OPENOBSERVE.md); the untracked .env.local holds them, matching the credentials in compose.dev.yml. Leave unset to disable: in development (NODE_ENV !== 'production'), logger output then goes to the console instead of being discarded.

See docs/SETTINGS.md for the list of settings for the GitHub App.

Scripts

Command	What it does
pnpm dev	Start the dev server
pnpm build	Production build (adapter-node)
pnpm preview	Preview the production build
pnpm lint	ESLint + svelte-check
pnpm fix	Prettier + ESLint autofix
pnpm test:unit	Vitest unit/integration tests
pnpm test:e2e	Playwright end-to-end tests (requires pnpm build)
pnpm test	Unit tests, then end-to-end tests
pnpm db:generate	Generate Drizzle migrations
pnpm db:migrate	Apply Drizzle migrations
pnpm db:studio	Open Drizzle Studio
pnpm docker:dev	Start the dev PostgreSQL + OpenObserve stack
pnpm docker:dev:down	Stop the dev PostgreSQL + OpenObserve stack

Testing

Unit/integration tests are colocated with source files as src/**/*.test.{js,ts}; end-to-end tests live in tests/. Run pnpm test:secrets once to generate local fake GitHub App secrets, and pnpm test:e2e:setup once to install the Playwright chromium browser. Tests never hit the real GitHub API — see TESTING.md for details.

Documentation

• AGENTS.md — agent guide and working conventions
• TESTING.md — testing commands and layout
• REVIEW.md — code review expectations
• docs/CONVENTIONS.md — topic-routed convention documents
• docs/OPENOBSERVE.md — OpenObserve dev stack for telemetry collection
• docs/SETTINGS.md - list of GitHub App settings