Git and GitHub / Advanced: trust, scale, and recovery / Lesson 17

Tags, releases, and maintenance collaboration

Identify source milestones and connect them to verified release artifacts without treating a tag name as an immutable guarantee.

About 4 min readContent reviewed 2026-10-25

On this page

Lesson goals

Distinguish lightweight tags, annotated tags, and GitHub releases.
Preserve release identity and maintenance traceability.

A tag names a historical point under policy

A lightweight tag is a reference, while an annotated tag adds a tag object with metadata and message and can carry a signature. Both can identify a release point, but the name alone does not guarantee it will never be moved or deleted. Repository policy and hosted controls determine permitted updates. Treat published release names as stable agreements and prefer a new version for a correction rather than silently changing what an existing name means. Verify the dereferenced commit and any signature under the release policy instead of relying only on a familiar version label.

Create a source milestone only in the lab

The fragment creates an unsigned annotated tag at the current clean lab commit with synthetic identity. cat-file reports tag because the name points to a tag object; dereferencing with the commit peeling syntax resolves the underlying commit. The command does not create a GitHub release or upload anything. Signing a tag is a separate configured cryptographic operation with its own trust and key lifecycle. Do not treat this unsigned teaching tag as verified provenance. All writes occur in the temporary repository and no actual project tag is created.

bash Inspect an annotated temporary tag and its target

git -c user.name="Lab Author" -c user.email="lab@example.invalid" tag -a lab-v1.0 -m "Lab notebook milestone"
git cat-file -t lab-v1.0
git rev-parse 'lab-v1.0^{commit}'

The type output is tag; the final generated id is the tagged commit and is not fixed here. The lab assumes the tag name does not already exist. No force option, publication, or real repository metadata change is used.

Separate hosted release metadata from Git objects

A GitHub release is a hosted publication associated with a tag and can include notes and downloadable assets. Its publication date and asset creation times need not equal commit or tag dates. Source archives and separately built binaries are different artifacts; a tag does not prove a binary was built from that source or passed tests. Connect the release to exact artifact digests, build provenance, and validation evidence under the project’s process. Platform features for release protection and immutability can vary, so inspect current documentation and repository settings rather than assuming every release has identical guarantees.

Record source and artifact identity explicitly

The synthetic manifest below illustrates the fields a release process might connect. It is not a standard GitHub format and contains no real digest or approval. A production record must use verified immutable identifiers and trusted evidence sources. Keep the tag name for human navigation while using the resolved commit for precise source identity. If a tag moves, the manifest should reveal the mismatch instead of silently following the new target. Do not include credentials in release notes or attach private diagnostic archives as public assets. Review access and retention before publication.

json An application-defined synthetic release record

{
  "tag": "lab-v1.0",
  "sourceCommit": "synthetic-lab-commit",
  "artifact": "synthetic-lab-package",
  "validationRecord": "lab-test-record",
  "publicationState": "example-only-not-published"
}

The labels intentionally are not fabricated cryptographic hashes. This example describes traceability and makes its unpublished state explicit. It does not create a release, upload an asset, or invoke a GitHub API.

Coordinate fixes across supported release lines

A maintenance policy should identify supported branches, backport criteria, review requirements, and how fixes return to the main development line. Cherry-picking a fix may create a different commit identity on each line, so preserve provenance and test each target context. Release notes should explain user-visible behavior and migration implications rather than merely listing hashes. Avoid moving published tags to conceal a problem; issue a reviewed correction with a clear relationship to the previous release. Before any actual publication, verify authorization, source identity, artifact evidence, and recovery plans through the project’s established process. No publication is performed in this course.

Common errors and fixes

A tag is assumed to prove binary provenance

Why it happens: Source naming is confused with build evidence.
How to fix it: Verify artifact identity, provenance, and tests separately.
Prevent it next time: Link source and artifact records explicitly.

A published tag is moved to hide a fix

Why it happens: A version name is treated as a disposable local label.
How to fix it: Coordinate a clear corrective release under policy.
Prevent it next time: Protect and review published reference changes.

A backport is released without target testing

Why it happens: Original validation is assumed to cover another maintenance context.
How to fix it: Run relevant validation on the actual release candidate.
Prevent it next time: Maintain per-line evidence and provenance.

Check your understanding

1. An annotated tag exists locally. Has a GitHub release been published?

Show worked solution

No. The local tag is a Git object and reference. Hosted publication and assets are separate operations requiring access and policy. Even sharing the tag would not automatically prove binaries or release notes were published.

2. A release binary is rebuilt later from the same tag. What must be verified?