DEV Community

Cover image for Commitea now has challenges verified against your real GitHub
David
David

Posted on

Commitea now has challenges verified against your real GitHub

#github #git #showdev #opensource

A while back I shared Commitea, my project to teach Git and GitHub in Spanish, with a repo of docs and an interactive visualizer. Since then I kept adding things — search, feedback widget, dark mode, a changelog page.

But there was still a gap between "reading how something works" and "actually knowing how to do it." So I built the piece that closes that gap: challenges verified against your real GitHub account.

What changed

Instead of reading how a merge or a Pull Request works and moving on, you now do it — in your own GitHub, with your own Git — and Commitea checks the result against the real API, not a checkbox you tick yourself.

The flow:

  1. You connect your GitHub account (OAuth, repo scope).
  2. You pick a challenge. Commitea generates a private repo in your account from a template (POST /repos/{owner}/{repo}/generate), pre-configured with whatever starting state that challenge needs.
  3. You solve it locally, with your actual Git — clone, branch, commit, push, whatever the challenge asks for.
  4. You hit "Verify." Commitea queries the GitHub API and tells you exactly what's missing, not just pass/fail. Three challenges are live right now, each verified differently:
  • Branches & commits — checks a specific branch exists and has enough commits ahead of the default branch (GET /repos/.../compare/{base}...{branch}, reading ahead_by).
  • Pull Request — checks at least one PR exists with a real description (not empty, not a single character).
  • Resolve a conflict — the template repo ships with two branches that genuinely conflict on the same line. Verification checks for a merge commit (a commit with 2+ parents) and that the file's final content matches the expected resolved value — so you can't just accept one side blindly.

A few technical details

  • Repo-per-challenge, not branch-per-challenge. I considered a single "progress" repo per user with one branch per challenge, but repo generation via GitHub's template API is built exactly for the one-repo-per-instance case, and verification stays unambiguous — no risk of cross-contamination between unrelated challenges living in the same repo.
  • The default branch is never assumed. Early on I hardcoded main as the comparison target and broke verification for anyone whose repo defaulted to master. Every verify call now reads default_branch from GET /repos/{owner}/{repo} first and compares against that.
  • Progress lives in Redis (Vercel KV), one JSON blob per user (progress:{username} → { [challengeId]: { completedAt } }), not a relational table — a single read gets everything needed to render the dashboard, and a single write marks a challenge complete. No migrations to manage for something this shaped.
  • The OAuth connect flow has an explanatory step before redirecting to GitHub. Clicking "connect" used to jump straight to GitHub's authorization screen; now there's a /login page first that explains what gets created (private repos, what gets read, what gets stored) and is explicit that the repo scope is broad because classic OAuth Apps don't offer a narrower option — GitHub Apps would, but that's a heavier model I'm not ready to take on yet.
  • The public challenge catalog (/retos) and the connection status in the header are fully static pages — they don't read cookies server-side, since most of the site is prerendered for performance/SEO. Instead there's a tiny /api/auth/status endpoint each page pings client-side to swap "Connect with GitHub" for "Dashboard" once it knows you're logged in.

Why this matters for the project

Git tutorials that stop at "here's the theory" are everywhere. What's rare is something that tells you, against your actual repository, whether you got it right — and why not, when you didn't. That's the difference between reading about a merge conflict and actually knowing what to do the next time Git throws one at you for real.

How you can help

Still a living project, not a closed course. Issues and PRs are open — especially ideas for new challenges (rebase, cherry-pick, and GitHub Actions checks are next on my list).

🔗 Repo: https://github.com/davidbc01/commitea
🔗 Site: https://commitea-web.vercel.app
🔗 Challenges: https://commitea-web.vercel.app/retos

Top comments (0)