gh-class-sak

Manage a whole course's GitHub repos from the command line — now that GitHub Classroom is gone.

A GitHub org hosts your classrooms, described by one small versioned state repo: classroom-meta — a directory per classroom, a hand-editable tsv file per assignment, a row per team. Everything else is derived from it and the repo names:

$ gh-class-sak classrooms cs101-fall
scanning cs101-fall ...
cs101_fall: hw1
cs101_fall: project

List the teams on an assignment, with their members and real names:

$ gh-class-sak repos list cs101-fall project --members --name
TEAM       MEMBERS
team-1     jdoe(Jane Doe),msmith(Marcus Smith)
nightowls  rpatel(Riya Patel),tk-codes
team-3     lchen(Lin Chen)

Pull every team's repo down for grading — safe by default, so this only previews:

$ gh-class-sak repos clone cs101-fall project --dest grading
⚠️  dry run: no changes will be made. add --no-dryrun to apply
⚠️  would clone cs101-fall/project-team-1 -> grading/team-1
⚠️  would clone cs101-fall/project-nightowls -> grading/nightowls
⚠️  would clone cs101-fall/project-team-3 -> grading/team-3

Add --no-dryrun and it actually clones, fast-forwarding any repo you already have.

What it does

• One versioned state repo per org — classrooms are directories, assignments are tsv files you can hand-edit, diff, and review; an org hosts as many classrooms as you need
• Roster tables built for the shell — teams, members, instructors, real names, and the emails students actually commit with, in columns that cut and awk parse
• Bulk clone for grading — clone or fast-forward every team's repo into one directory, named by team
• Canvas integration — map orgs to Canvas courses: build an assignment's repos straight from the enrollment roster or a Canvas group set (one repo per person or per group), resolve emails to GitHub ids via Canvas profile links, match groups, add per-section instructor columns, and report who has no repo yet
• Message the stragglers — canvas message-missing finds every student stranded on the way to their repo — no GitHub link on their Canvas profile, a broken one, or a repo invitation they never accepted — and sends each a Canvas message saying exactly what to fix; a dry run shows every message before anything goes out
• Managed classrooms — meta apply reconciles the org to the classroom-meta repo: creates private repos (optionally from a template), grants student, TA, and branch-protection state exactly as recorded — removing people is opt-in — and tracks repos by permanent id so renames can't hide them
• Safe by default — every mutating command previews with a ⚠️ until you pass --no-dryrun, and your token never appears in ps output, clone URLs, or .git/config

Installation

pip install gh-class-sak

Or, to keep it out of your project environments:

pipx install gh-class-sak      # or: uv tool install gh-class-sak

Requires Python 3.9+.

Documentation

• Getting started — install, tokens, the Canvas config, and a first walk through a course
• Migrating from GitHub Classroom — where Classroom's bookkeeping lives now, and the one-command import
• Canvas integration — how GitHub ids map to Canvas accounts, assignments built from enrollments or group sets, and messaging the students whose setup is stuck
• The classroom-meta files — the file layouts and formats, and how TA teams manage the TAs
• Commands — the full reference: every command, every flag, and the classroom-meta repo

Every example on those pages — and above — is replayed against an invented demo course by the test suite, so the output you see is the output you get.

Contributing

Questions, war stories, and quick help live on the Discord server — running a course with this, or thinking about it? Come say hi.

See CONTRIBUTING.md. The test suite stubs out GitHub and Canvas, so you can contribute without a course, a token, or a Canvas account:

python -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/pytest

Security policy: SECURITY.md. Please report vulnerabilities privately.