Lesson 07 · GitHub platform · releases
A release wraps a single commit, a tag, and a changelog into a fixed point other people can pin to. Knowing when to cut one — and when a plain merge to main is enough — is the actual skill.
Every lesson so far — Issues, Actions, Projects, Pages, Security, Insights — covered day-to-day repo mechanics. A release is different: it's the moment you say "this exact state of the code is a thing other people can depend on," out loud, in public.
Under the hood a release is thin: it's a git tag — a pointer to one specific commit — dressed up with a title, notes, and optional files. "Releases are deployable software iterations you can package and make available for a wider audience to download and use." — GitHub Docs
v0.1.0. Pins the release to one exact commit forever. GitHub creates this for you when you publish a release from the web UI — you don't need git tag on the command line first.The tag itself is one thing you already half-know from git: a named pointer to a commit, like a branch that never moves. "A tag date may be different than a release date since they can be created at different times" — the tag marks the code moment, the release wraps it with documentation later, possibly much later.
| Web UI | gh CLI |
|---|---|
| Repo → Releases → Draft a new release | gh release create v0.1.0 --draft --generate-notes |
Choose or type a tag, e.g. v0.1.0 | same tag, as the first argument |
| Click Generate release notes | --generate-notes flag |
| Check Set as a pre-release | --prerelease flag |
CLI reference: gh release create. You already have gh available — same tool used to check this repo's visibility in an earlier lesson.
GitHub's docs describe what a release is but stay quiet on when to cut one — that judgment call is yours. A working rule of thumb:
| Cut a release when… | Just merge to main when… |
|---|---|
| Someone outside your own deploy pipeline needs to pin a specific version — a library consumer, a Docker tag, a downloadable tool | You're continuously deploying and the only "version" that matters is whatever's on main right now |
| You want a fixed rollback point with a changelog attached | Rollback already means "revert the commit" or "redeploy the previous deploy," no tag needed |
| You're shipping a milestone worth announcing (v1.0, a breaking change) | The change is routine, internal, and not something anyone would reference by version number |
This workspace's own repo is a practice ground, not a shipped library — nobody depends on a pinned version of it. So a release here is purely for practicing the mechanic, not because the repo needs one.
v0.1.0 is fine — targeting main.Primary source — read this one: GitHub Docs — About releases. Covers tags, notes, assets, and pre-release/latest flags in full.