For whoever runs the workshop. The format is live hands-on: you do every step on screen, explaining as you go, and the students do the same in their own accounts. The lab pages hold every command, so a student who misses something can always catch up from them.
Run sheet¶
The slide numbers are the ones shown at the bottom right of the slides.
| Clock | Slides | Lab | What happens |
|---|---|---|---|
| 0:00 | 1–6 | Setup | Welcome, share the materials link. Why version control, Git vs GitHub. ✅ git --version |
| 0:10 | 7–9 | Commits, the three areas | |
| 0:14 | 10 | 1.1–1.4 | git init, first commit, .gitignore, publish on GitHub. ✅ repository link in the chat |
| 0:26 | 11–14 | 1.5–1.6 | The daily loop, GitHub flow, tour of a pull request, first PR merged |
| 0:38 | 15–17 | 1.7 | Merge conflict, on purpose. ✅ two merged PRs. Recap |
| 0:45 | 18–22 | Issues, labels, milestones, projects, closing keywords | |
| 0:50 | 23 | 2.1–2.4 | 4 issues, a label, milestone v1.0, board, bug fixed by a PR. ✅ milestone 25% |
| 1:10 | 24–27 | CI and CD, Actions vocabulary, anatomy of a workflow | |
| 1:15 | 28 | 3.1–3.2 | First workflow, then the branch ruleset, then merge |
| 1:25 | 29–30 | 3.3 | Test-first: red, then green. ✅ milestone 75% |
| 1:32 | 31–33 | 3.4 | Docker, the Dockerfile, build and run locally |
| 1:38 | 34–36 | 3.5–3.6 | The publish job, merge, tag v1.0.0, release, public package. ✅ final checkpoint |
| 1:50 | 37–41 | Wrap-up | What they built, quiz, challenges, questions |
Before the day¶
One week before
Send students the Before the Workshop page, and ask them to report any line of its checklist that fails. Most lost time in a live workshop is installation and sign-in, and it’s easier to fix them before than during. If you can, hold a 15-minute “setup clinic” the day before.
Students’ repositories must be public. Rulesets (step 3.2) are free on public repositories, but need a paid plan on private ones. Actions minutes and container images are free for public repositories, too.
Rehearse once, end to end, with the account you will present with. Alone, it takes about 70 minutes. Then delete everything, so that the live run starts from zero, exactly like the students:
the
calc-apprepository: Settings → Danger Zone → Delete this repository;the
calc-apppackage, which survives the repository: your profile → Packages →calc-app→ Package settings → Delete this package. A leftover package makes the nextpublishfail with permission denied;the
Calc App roadmapproject: project ⋯ → Settings → Delete this project.
On the day, 30 minutes before
docker pull python:3.12-slim, so the live build does not wait for a download.Terminal: large font (18 pt or more), light theme, a prompt that shows the current branch (Git Bash does by default).
Browser zoom at 125–150%. Close private tabs and silence notifications.
Three windows ready: the slides, the lab page of the current part, and the terminal next to your editor.
Have
calc-app-final.zipextracted somewhere: if something breaks live, copy the files you need from it rather than debugging in front of everyone.If possible, have a co-host who watches the chat and helps stuck students, in a breakout room if needed.
While presenting¶
Narrate what you type and what you expect to see, then show it. When the output differs from the lab page, say why.
Wait at every ✅ checkpoint until most of the room has posted in the chat. People who are stuck can catch up there, from the lab pages.
Keep
git statuson screen often: it is the habit to pass on.Park questions that are out of scope (rebase, Git internals, Kubernetes) in a list, and answer them at the end.
In Part 2, remind students that issue numbers differ from yours if they opened extra pull requests.
Running late? What to cut¶
| Part | Cut first | Then |
|---|---|---|
| 1 | Step 1.5: the branch workflow in 1.6 uses the same commands | Do 1.7 (conflict) yourself only; students do it after the workshop |
| 2 | The Table view and custom fields | Create only the bug and feature issues live, and the two others as you reach them in Part 3 |
| 3 | The local Docker build (3.4): the pipeline builds the image anyway | Make your package public and run your image; students finish 3.6 at home |
| Wrap-up | The quiz: it is on the Wrap-up page |
Ahead of time? What to add¶
The Python-version matrix (challenge 4), live: watch three jobs run in parallel.
Open the repository in a Codespace and run the app there.
On GitHub, show Blame on a file and the history of a single line.
Common problems¶
| Symptom | Cause | Fix |
|---|---|---|
git push asks for a password, then fails | GitHub refuses passwords on the command line | gh auth login (setup, step 4); on Windows, the Git Credential Manager window |
remote: Permission ... denied (403) | Git is signed in as another GitHub account | gh auth login again; on Windows, remove the git:https://github.com entry in the Credential Manager |
fatal: not a git repository | The terminal is in the wrong folder | cd into calc-app; ls -a must show .github, app, tests |
ls -a shows only another calc-app folder | The zip was extracted into a folder of the same name | cd calc-app once more |
error: src refspec main does not match any | Nothing committed yet, or the branch is called master | Commit first; git branch -M main |
! [rejected] ... (fetch first) | GitHub has commits the student doesn’t have | git pull, then git push |
| A strange editor fills the terminal | vim, opened by a commit or merge without -m | Type :wq then Enter; set core.editor (setup, step 3) |
LF will be replaced by CRLF (Windows) | Line-ending conversion | Harmless, ignore it |
| The workflow never starts | The file is not at .github/workflows/*.yml, at the root | git ls-files .github |
test is not offered in the ruleset | The check has never run | Push the branch, wait for the run, add the rule again |
publish fails: permission_denied: write_package | A calc-app package left from an earlier attempt, or no permissions: block | Delete the old package, or grant the repository Write in its settings |
docker: command not found, or “daemon not running” | Docker Desktop not installed, or not started | Start Docker Desktop, or use a Codespace |
port is already allocated | Port 8000 is used by something else | docker run --rm -p 8080:8000 calc-app and open port 8080 |
After the workshop¶
Share the materials link again, and point to the take-home challenges on the Wrap-up page.
Ask one question for feedback: “What will you use next week?”
Delete your demo repository, package and project, as above.
Maintaining these materials¶
Everything lives in
workshops/github/of the site repository: these pages, the slides (deck/), and the sample project, as the starter (calc-app/) and the end state (calc-app-final/). The site build zips both into the downloads.Most code in Parts 2 and 3 is included straight from the files of
calc-app-final/, so editing the sample project updates those snippets too. Two are written out in the page and need updating by hand: the first version of the workflow (step 3.1) andtest_divide_by_zero(step 2.4). The slides and the cheat sheet also quote code.The workflow
.github/workflows/workshop-github.ymlruns the tests of both versions and builds the Docker image whenever the workshop changes. It also fails if the pages or the slides mention a different version of an action thancalc-app-final/.github/workflows/ci-cd.ymldoes.Once a year, bump the major versions of the actions in that workflow file (the check above then lists every page to update), and walk through the GitHub screens: their names move from time to time.