Tags, Releases, Release Notes, Assets, Changelogs, and Release Governance: Configuration, Design Choices, and Tradeoffs

1. Annotated, signed, and lightweight tags communicate different intent

A lightweight tag is only a ref name pointing to an object. An annotated tag creates a tag object with message and tagger metadata. A signed annotated tag adds a cryptographic signature that GitHub can display as verified when the signing identity is recognized.

Signing answers “who signed this tag with a verifiable key?” It does not prove that uploaded assets were built reproducibly or passed tests. Keep signer identity, build provenance, and artifact integrity as separate evidence.

# Example only after configuring an approved signing key
git tag -s v2.0.0 -m "Release v2.0.0" COMMIT_SHA
git tag -v v2.0.0

2. Manual versus generated notes is a governance choice, not a tooling preference

Manual notes are strongest for migration steps, operational risk, rollback instructions, deprecation policy, and curated narrative. Generated notes scale well for enumerating merged pull requests and contributors. A hybrid model often works best: generated change inventory plus manually authored operational sections.

# Example generated-note release after the remote tag already exists
gh release create v2.1.0 --verify-tag --generate-notes --title "v2.1.0"

# Optional comparison start when generation should not infer the previous tag
gh release create v2.2.0 --verify-tag --generate-notes --notes-start-tag v2.1.0

If the generated output is wrong, fix the metadata model or edit the draft/notes before publication rather than assuming generation is authoritative.

3. .github/release.yml turns label taxonomy into changelog categories

Generated release notes can use labels to group changes. This creates a contract between triage/review metadata from Chapters 05–08 and release communication. Keep categories small enough that contributors can classify PRs consistently.

# .github/release.yml
changelog:
  exclude:
    labels:
      - skip-changelog
  categories:
    - title: Breaking changes
      labels:
        - breaking-change
    - title: Features
      labels:
        - enhancement
    - title: Fixes
      labels:
        - bug
    - title: Other changes
      labels:
        - "*"

The catch-all prevents unlabeled work from disappearing completely; reviewers can then improve taxonomy rather than silently omitting the change.

4. Draft, prerelease, and latest should have written entry/exit criteria

The REST API does not allow drafts or prereleases to be marked latest. The “latest” designation should not replace your own SemVer/support policy; it is a hosted convenience that downstream automation may read.

5. Corrections: mutate metadata carefully; do not silently redefine a consumed artifact

Correcting a typo in notes is different from replacing a binary under the same version. For a consumed production version, artifact replacement or tag movement breaks the meaning of caches, checksums, SBOMs, deployment records, and incident evidence. Prefer publishing a new patch version such as v1.4.1.

Immutable releases enforce the strongest form of this policy for tag/assets. Even without the feature, adopt the operating rule: published tag target and artifact bytes do not change. Metadata corrections should be documented and bounded.

6. Multiple support lines require explicit release targeting

Suppose main is v3 development while release/2.x receives security fixes. A v2.7.4 release must tag the validated commit on the support branch, not whatever happens to be on the default branch. Tag first and verify the SHA; the branch is only the moving line from which that commit was selected.

7. Worked decision table: choose a policy, not a button sequence

The “critical” column costs more operational discipline, not necessarily more GitHub subscription. The important cost is governance: key management, provenance generation, reviewers, and long-term evidence retention.

8. Latest designation and automation consumers

Automations that download /releases/latest trade convenience for indirection: their input can change when a new stable release is designated. Production automation should usually pin a version/tag or digest and perform explicit promotion rather than silently following latest.

9. Lesson summary

Release policy is a set of explicit decisions: tag identity, note generation, state transitions, artifact provenance, support lines, and correction strategy. Annotated/signed tags strengthen release intent; generated notes accelerate inventory but require taxonomy; immutable releases can enforce the no-redefinition rule for published tags/assets.

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