Tags, Releases, Release CLI, Changelogs, Evidence, Asset Links, and Release-Orchestration Pipelines: Configuration, Design Choices, and Tradeoffs

1. Design frame: release automation is a public API for your build evidence

A release pipeline is not merely a convenient last stage. It publishes a durable identity that downstream humans, systems, and later deployments may trust. Design it like an API: define required inputs (exact SHA, version, artifact digest), allowable side effects (tag/release/links), authorization, idempotency behavior, and how a caller can verify or supersede the result.

2. Current platform assumptions verified for this chapter

3. YAML release versus glab versus Releases API

Do not combine all three mechanisms in one job simply because they exist. More mechanisms means more token paths, more update semantics, and more ways to accidentally treat a partial success as complete publication.

4. Pre-created annotated tag versus release-time tag creation

A pre-created tag separates source authorization from release metadata creation. It is easier to inspect the ref before publishing. Release-time creation reduces steps, but it makes explicit ref selection essential. Protected tags can further restrict who may create release refs.

5. Generated notes versus curated notes

Generated notes scale well and reduce omissions when commits use consistent trailers. Curated notes communicate impact better. A robust model uses generated data as a reproducible base, then treats human edits as release metadata whose author/time are preserved—not as a rewrite of the release’s source or artifact identity.

glab changelog generate \
  --from "$PREVIOUS_RELEASE_SHA" \
  --to "$TARGET_SHA" \
  --version "$VERSION" \
  > generated-notes.md

# Curator may add context, but these immutable fields stay machine-produced:
printf '\nSource SHA: `%s`\nArtifact SHA-256: `%s`\n' \
  "$TARGET_SHA" "$ARTIFACT_SHA256" >> generated-notes.md

6. Immutable assets versus external mutable URLs

Asset links are references; they do not copy the target into a magical immutable store. A URL like https://downloads.example/app/latest.zip is operationally convenient and evidentially weak. A versioned package coordinate, container digest, commit-SHA raw path, or content-addressed object plus digest is auditable.

7. Protected tags and publication authorization

Release write permission and tag-creation permission are related but not identical. GitLab documents that a user creating/updating/deleting a release associated with a protected tag must also be permitted to create that protected tag. This makes a protected tag namespace a useful release authorization boundary.

A broad PAT with api can often do much more than the release needs. Prefer CI_JOB_TOKEN where the endpoint supports it; otherwise use a narrowly scoped project/group token and isolate it to the release job/ref. Never print it for debugging.

8. Idempotency and retries: “try again” is a state transition, not a button

Before retrying a failed release job, inspect whether the tag exists, whether the release exists, whether asset links were already added, and whether evidence was collected. The YAML release keyword fails if the release already exists; glab release create can update an existing release. Those different semantics must be part of the retry design.

LAB_TAG="v0.0.0-ch22-lab.${CI_PIPELINE_ID}"

# Inspect first.
git ls-remote --tags origin "refs/tags/$LAB_TAG"
GLAB_ENABLE_CI_AUTOLOGIN=true glab release view "$LAB_TAG" --repo "$CI_PROJECT_PATH" || true

# Decide whether the correct action is create, update, repair an asset link,
# or do nothing. Do not blindly rerun a non-idempotent release mutation.

9. Worked decision table

10. Keep state boundaries explicit

A release does not authorize deployment, and a deployment approval does not validate the release artifact. Similarly, a green release job does not prove a downstream registry or external link is healthy. Keep build evidence, publication authorization, release metadata, deployment authorization, and external state independently observable.

11. Design checklist

• Exact VERSION, tag, and SHA are inputs, never inferred from “latest”.
• Artifact digest comes from the tested artifact, not a release-time rebuild.
• Choose one primary publication mechanism and document its retry/update semantics.
• Use protected tag namespaces to reduce accidental publication.
• Prefer job token over broader credentials where supported.
• Keep changelog range/configuration reproducible.
• Link to immutable/versioned assets and verify consumer-side digest.

Knowledge check

Official references and version notes

Documentation verification date: 2026-09-12. Releases, changelogs, the Releases API, release links, base release evidence, and role-based protected tags are documented across Free/Premium/Ultimate unless a narrower tier is explicitly called out. The current YAML release flow uses glab; current docs require glab 1.58.0 or later. release-cli was deprecated in GitLab 18.0 and is planned for removal in 20.0. The lesson treats additional evidence recollection and some evidence/report enrichment as optional where current docs specify narrower tier/offerings.

• Releases — official reference.
• CI/CD YAML release keyword — official reference.
• GitLab Release CLI migration — official reference.
• glab release create — official reference.
• Changelogs — official reference.
• Release evidence — official reference.
• Project Releases API — official reference.
• Release links API — official reference.
• Protected tags — official reference.
• CI job token — official reference.

Current assumptions used in this chapter: Version-sensitive YAML, Runner/executor behavior, APIs, security features, policy controls, tiers, and deprecations must be verified against the exact GitLab, GitLab Runner, tool, and external-system versions used in production. Preserve the exact project/ref/SHA, compiled configuration, pipeline/job IDs, runner/tool versions, and external target evidence used for reproducible work.