Tags, Releases, Release Notes, Assets, Changelogs, and Release Governance: Guided Hands-On Workflow and Core Operations

1. Create the disposable release laboratory

gh auth status --active --hostname github.com

# Create a public disposable repository and clone it.
gh repo create github-release-lab --public --clone --add-readme
cd github-release-lab

git status --short --branch
git remote -v
gh repo view --json nameWithOwner,visibility,defaultBranchRef,viewerPermission

The repository is the hosted container. At this point no release has been created. Confirm that before adding any tag:

gh release list --json tagName,name,isDraft,isPrerelease,isLatest,isImmutable
git tag --list

2. Create an annotated tag and prove its target before pushing

An annotated tag creates a tag object in addition to the ref. That gives the version a message and tagger metadata. For this lab, create a small commit, capture its OID, then tag exactly that commit.

printf "release lab v0.1
" > RELEASE-DEMO.txt
git add RELEASE-DEMO.txt
git commit -m "Add v0.1 release demo"
COMMIT_V01=$(git rev-parse HEAD)

git tag -a v0.1.0 "$COMMIT_V01" -m "Disposable v0.1.0 release"

# Read-only proof before publishing the tag.
git show --no-patch --decorate v0.1.0
git rev-list -n 1 v0.1.0

# Only after the target is verified:
git push origin main
git push origin refs/tags/v0.1.0

3. Create the GitHub Release as a draft and refuse implicit tag creation

Use the already-pushed tag. --verify-tag is the guardrail: if the remote tag is absent, the command aborts rather than creating a tag at an implicit target.

cat > release-notes.md <<'EOF'
## v0.1.0

Disposable training release.

- Exact tag target verified before publication.
- Asset hash will be recorded before publish.
EOF

printf "artifact for v0.1.0
" > release-evidence.txt

gh release create v0.1.0 release-evidence.txt \
  --draft \
  --verify-tag \
  --title "v0.1.0 — disposable lab" \
  --notes-file release-notes.md

gh release view v0.1.0 --json tagName,name,isDraft,isPrerelease,isImmutable,targetCommitish,assets,url

The Release object is now a draft. The tag existed beforehand; the asset is a hosted Release asset; neither operation changes the commit graph.

4. Hash the asset, edit the notes, then publish

Compute the local SHA-256 before publication and place it in the release notes. On production releases this digest should be generated by the build/release system, not copied from memory.

# Git Bash/Bash/zsh
sha256sum release-evidence.txt

# Append the observed digest to release-notes.md, then update the draft.
gh release edit v0.1.0 --notes-file release-notes.md

# Publish the already-assembled draft.
gh release edit v0.1.0 --draft=false

gh release view v0.1.0 --json tagName,name,isDraft,isPrerelease,isImmutable,publishedAt,assets,url

5. Download the uploaded asset and compare it with a source archive

mkdir -p downloads/assets downloads/source

# Uploaded Release asset
gh release download v0.1.0 -p 'release-evidence.txt' -D downloads/assets
sha256sum downloads/assets/release-evidence.txt

# GitHub-generated source archive for the same tag
gh release download v0.1.0 --archive=zip -D downloads/source

# Inspect file names/sizes rather than treating them as the same artifact.
ls -lh downloads/assets downloads/source

The uploaded text file is a Release asset you supplied. The source ZIP is generated from repository contents at the tag. GitHub’s immutable-release verification command cannot verify the generated source ZIP/tarball because those archives are created on request; use tag/commit identity for source and attestation/digest evidence for uploaded immutable assets.

6. Generate notes as a preview, then decide what belongs in the human-facing release

Generated notes are useful input, not an approval. You can create a separate disposable tag/Release later with --generate-notes, or use the web “Generate release notes” control. A .github/release.yml file can control categories and exclusions. For this first release, manually authored notes make the mapping between evidence and prose easier to inspect.

# Read-only list gives structured state for audit evidence.
gh release list --json tagName,name,isDraft,isPrerelease,isLatest,isImmutable,publishedAt

# REST inspection of this specific hosted Release
gh api -H "Accept: application/vnd.github+json" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  repos/{owner}/{repo}/releases/tags/v0.1.0 \
  --jq '{id,tag_name,target_commitish,draft,prerelease,immutable,assets:[.assets[]|{name,size,digest}]}' 

{owner} and {repo} are resolved by gh api from the current repository when written in braces.

7. Cleanup proves Release deletion and tag deletion are separate operations

# Delete the GitHub Release object only.
gh release delete v0.1.0 --yes

# Prove the Git tag still exists remotely/local.
git ls-remote --tags origin 'refs/tags/v0.1.0*'
git tag --list v0.1.0

# Now delete the remote tag explicitly, then the local tag.
git push origin :refs/tags/v0.1.0
git tag -d v0.1.0

# Final proof
gh release list
git ls-remote --tags origin
git tag --list

gh release delete --cleanup-tag exists if you intentionally want coupled cleanup, but keeping the two operations separate in this lesson makes the resource boundary observable.

8. Challenge: choose the right control

Your team has already pushed v0.2.0 at a verified commit and wants a Release only if that exact remote tag exists. Which surface/control should you choose?

Use gh release create v0.2.0 --verify-tag .... Do not use --target as a substitute for a pre-existing verified tag, because the goal is to fail closed if release preparation is incomplete.

9. Lesson summary

The workflow was deliberately two-phase: establish an exact Git tag first, then create a GitHub Release object around it. Drafts let you assemble notes/assets before publication. Uploaded assets and generated source archives are different artifact classes. Cleanup demonstrated that Release deletion and tag deletion are independent unless you explicitly couple them.

Knowledge check

Further reading — current official GitHub sources

• GitHub Docs — About releases
• GitHub Docs — Managing releases in a repository
• GitHub Docs — Automatically generated release notes
• GitHub Docs — Immutable releases
• GitHub Docs — Verify release integrity
• GitHub REST API — Releases
• GitHub REST API — Release assets
• GitHub CLI manual — gh release