Releases, Tags, Release CLI, Evidence, Changelogs, and Deployment Traceability: Concepts, Architecture, and Mental Model

1. The practical problem: a release name is not enough

Chapters 22 and 23 gave packages and OCI images durable coordinates and digests. A production release must now connect those objects back to the exact source and delivery event. “Version 2.4.0 shipped” is weak evidence unless an operator can answer: which commit did v2.4.0 name, which pipeline built the deliverables, which immutable package or image digest was distributed, what Release metadata described it, and which deployment consumed that identity?

Git provides commit and tag objects. GitLab adds a hosted Release object, release notes, assets/links, evidence snapshots, API/CLI automation, and relationships to milestones and deployment activity. Do not collapse these layers into one abstraction.

2. Git tag versus GitLab Release object

A Release is not a second Git commit and it is not the binary itself. It is metadata anchored to a tag. Deleting a Release leaves the tag; deleting the tag associated with a Release removes the Release too.

3. Mental model: release as a chain of independently verifiable identities

flowchart TD
  C[Commit SHA] --> T[Git tag vX.Y.Z]
  T --> R[GitLab Release]
  P[Pipeline / job] --> A[Package hash or OCI digest]
  A --> R
  R --> V[Release evidence JSON]
  A --> D[Deployment / environment]
  C --> P
  D --> O[Operational rollback record]

4. Read-only inspection before release mutation

Before creating or editing a release, prove current state from at least two surfaces:

git fetch --tags --prune
git status --short
git rev-parse HEAD
git tag --list "v*" --sort=-version:refname | head -n 10

glab release list -F json --per-page 20
# Inspect a known release without editing it:
glab release view v1.2.3 -F json

For machine-readable API evidence, use GET /projects/:id/releases and GET /projects/:id/releases/:tag_name. Record project, tag, Release creation/release timestamps, returned commit SHA, asset links, and evidence file path. Never infer a binary digest merely because it is linked from a release.

5. Current automation interfaces: glab, release keyword, REST API

For new automation, prefer glab, the CI release keyword, or the Releases API. release-cli is deprecated since GitLab 18.0 and scheduled for removal in 20.0.

release_job:
  stage: release
  image: registry.gitlab.com/gitlab-org/cli:latest
  rules:
    - if: $CI_COMMIT_TAG
  variables:
    GLAB_ENABLE_CI_AUTOLOGIN: "true"
  script:
    - echo "Release metadata will be created after this job script succeeds."
  release:
    tag_name: $CI_COMMIT_TAG
    name: "Release $CI_COMMIT_TAG"
    description: "CHANGELOG.md"

Authentication nuance: for CI job-token auto-login, set GLAB_ENABLE_CI_AUTOLOGIN=true. Do not set GITLAB_TOKEN=$CI_JOB_TOKEN; glab sends GITLAB_TOKEN as a private-token header, which the Releases API does not accept as a job token and can result in 404 Not Found.

6. Assets are references; durability depends on the target

A Release includes automatically generated source archives plus optional asset links. An asset link has a display name and URL; it can point to a Generic Package, container/package download, documentation, runbook, or other durable service. The Release does not magically copy the referenced bytes unless your chosen workflow explicitly uploads them somewhere durable.

7. Release evidence: audit snapshot, not cryptographic trust

When a release is created, GitLab creates release-evidence JSON automatically on Free/Premium/Ultimate across all offerings. The snapshot can include release metadata and related records; matching packages may be included when package versions match the release tag convention. Current tier-specific extensions matter:

• Automatic snapshot: Free-compatible.
• Collect another evidence snapshot on demand: Premium/Ultimate, Self-Managed/Dedicated.
• Preserve report artifacts as release evidence: Ultimate.

The evidence SHA identifies the evidence snapshot. It does not assert that a package/image is vulnerability-free, signed by a trusted key, reproducibly built, or safe to deploy. Those are separate controls/evidence sources.

8. Changelog generation: structured commit data, not automatic editorial judgment

GitLab changelog generation selects commits using a configured Git trailer, by default Changelog, and emits Markdown. The default values such as added, fixed, changed, deprecated, removed, security, performance, and other give maintainers a useful taxonomy.

git commit -m "Harden release verification

Changelog: security"

glab changelog generate --version 1.2.0 --from <old_sha> --to <new_sha> > release-notes.md

Generated notes are evidence of selected commit metadata, not a substitute for human explanation of breaking changes, migration steps, compatibility, or known limitations.

9. Tags are release governance, not decoration

Because release metadata is anchored to tags, tag creation/deletion policy is part of release governance. Protected tags are Free across all offerings and can restrict who may create matching release tags. Maintainers/Owners configure the rules; deleting a protected tag requires GitLab UI/API and appropriate permission.

A particularly dangerous failure is deleting and recreating a release tag after consumers have cached or deployed the earlier ref. The same tag text can then name a different commit. Preserve the original incident evidence, restore by a new version/tag when possible, and use protected-tag policy to reduce this class of mutation.

10. Traceability invariant

A production release record is strong when the following invariant is independently checkable:

tag_commit_sha == release.commit.id == build_source_sha
release_asset_hash_or_digest == deployed_artifact_hash_or_digest
deployment.commit_sha == intended_release_commit_sha

Not every GitLab object stores every equality directly, so operators collect the chain from Git, Release API, package/container metadata, pipeline/job evidence, and environment/deployment records.

11. DevOps connection

Release governance reduces two forms of pressure: ambiguity (“which binary is this?”) and ceremony (“we have a release page, so we must be compliant”). The goal is a small, automatable chain of durable identities and explicit permissions. That chain supports rollback, incident response, audit, customer distribution, and later security policy without making the Release page the single source of truth for everything.

Knowledge check

Summary

Git commits and tags provide source identity; GitLab Releases provide hosted metadata; package hashes/OCI digests provide deliverable identity; deployment records provide operational state; release evidence and changelogs add audit/context. A trustworthy release ties these layers together without pretending any one layer proves all the others.

Official references

Primary sources used for the current GitLab 19.3 behavior taught in this lesson:

• GitLab Docs — Releases
• GitLab Docs — Project releases API
• GitLab Docs — Release links API
• GitLab Docs — Release evidence
• GitLab Docs — Release fields and assets
• GitLab Docs — release-cli (deprecated)
• GitLab CI/CD YAML — release keyword
• GitLab CLI — release
• GitLab CLI — release create
• GitLab CLI — release view
• GitLab CLI — release list
• GitLab Docs — Changelogs
• GitLab CLI — changelog generate
• GitLab Docs — Repositories API changelog endpoints
• GitLab Docs — Protected tags