Tags, Releases, Release CLI, Changelogs, Evidence, Asset Links, and Release-Orchestration Pipelines: Diagnostics, Failure Modes, Security, and Performance

1. Evidence-first diagnostic sequence

1. Preserve pipeline ID, release-job ID, first failing trace, release API response, exact tag, and any consumer mismatch.
2. Confirm CI_PIPELINE_SOURCE, ref, CI_COMMIT_SHA, and compiled release configuration.
3. Resolve the tag target independently with Git/API.
4. Confirm the verified artifact digest and whether release publication reused or rebuilt it.
5. Inspect release/evidence/asset metadata and authorization response.
6. Check asset target bytes and consumer digest.
7. Apply the smallest correction: tag, metadata, link, credential, or cleanup target—never all at once.
8. Retry only the smallest safe scope after proving current partial state.

2. Failure: tag points to the wrong commit

The most dangerous symptom is a plausible release page whose tag target does not match the verified candidate. Preserve both SHAs before correcting anything.

EXPECTED_SHA="$CI_COMMIT_SHA"
ACTUAL_SHA="$(git rev-parse "$LAB_TAG^{}")"
printf 'expected=%s actual=%s tag=%s\n' "$EXPECTED_SHA" "$ACTUAL_SHA" "$LAB_TAG" | tee wrong-tag-evidence.txt

test "$EXPECTED_SHA" = "$ACTUAL_SHA" || {
  echo "STOP: release tag does not identify verified candidate" >&2
  exit 41
}

For a disposable lab tag, the least destructive repair is usually to remove/supersede the erroneous release record and create a new corrected tag/release. Do not force-move a published production tag: consumers may already have cached the old ref, and protected tags are specifically intended to prevent accidental update/deletion.

3. Failure: release job rebuilt the artifact

Tests verified digest A, but the release stage ran the compiler again and published digest B. That is not a “flaky hash”; it is a provenance break. Preserve both build logs and both digests. Repair the pipeline dataflow so release consumes the verified artifact/package rather than reconstructing it.

# Broken: release silently rebuilds.
release_bad:
  stage: release
  script:
    - ./build.sh
    - sha256sum dist/app.tar.gz

# Safer: verified build artifact flows forward.
release_good:
  stage: release
  needs:
    - job: build_verified
      artifacts: true
  script:
    - sha256sum -c SHA256SUMS
    - test "$CI_COMMIT_SHA" = "$(cat SOURCE_SHA)"

4. Failure: mutable asset link silently changed

The release metadata still says v1.4.0, but https://downloads.example/app/latest.zip now serves a different digest. Preserve the release API response, HTTP headers, URL, first known digest, and current digest. Repair the release link to a versioned/content-addressed target and publish a clear superseding note if consumers may have received wrong bytes.

5. Failure: broad token can alter unrelated releases

A PAT with broad API scope can mask missing authorization design. Before rotating or replacing it, record which endpoint actually required authentication and whether CI_JOB_TOKEN is supported. Releases API accepts a job token; glab can auto-login with it in CI.

# Good CI pattern for release endpoints that accept the job token.
export GLAB_ENABLE_CI_AUTOLOGIN=true
glab release view "$LAB_TAG" --repo "$CI_PROJECT_PATH"

# Direct API uses JOB-TOKEN, not PRIVATE-TOKEN.
curl --fail --silent --show-error \
  --header "JOB-TOKEN: $CI_JOB_TOKEN" \
  "$CI_API_V4_URL/projects/$CI_PROJECT_ID/releases/$LAB_TAG" > release.json

Do not echo either token. If a different endpoint requires a stronger token, scope it to the smallest project/job/ref surface and document why the job token was insufficient.

6. Failure: cleanup selects “latest”

A cleanup script calls the latest-release permalink, then deletes whatever tag it finds. This is unsafe because released_at ordering is not the same as “the lab resource I created.” The fix is to persist the exact LAB_TAG at creation time, validate its prefix and target SHA, then address that one release.

# Intentionally broken — do not use:
# TAG=$(curl .../releases/permalink/latest | jq -r .tag_name)
# curl -X DELETE .../releases/$TAG

# Guarded exact cleanup:
case "$LAB_TAG" in v0.0.0-ch22-lab.*) ;; *) exit 2 ;; esac
test "$(git rev-parse "$LAB_TAG^{}")" = "$TARGET_SHA"
printf 'Deleting exact release record %s at %s\n' "$LAB_TAG" "$TARGET_SHA"

7. Partial state: tag exists, release creation failed

This is a normal recoverable state, not a reason to delete everything. Inspect whether the tag target is correct. If yes, fix only the release metadata/auth/tool issue and rerun the release creation path. If the tag target is wrong, create a new correct tag in the disposable lab or follow your organization’s production release incident policy.

8. Performance without weakening evidence

Release jobs should be lightweight. Rebuilding, rerunning full test suites, or downloading giant artifacts merely to discover their digest increases latency and creates inconsistency risk. Compute provenance during build/test, store compact manifests, and let release publication verify those manifests before metadata mutation.

Similarly, changelog generation can be bounded to the exact range. The current changelog configuration parser has a documented two-second parsing limit; keep templates/configuration intentionally small.

9. Intentionally broken lab and repair

Start with this broken command in a disposable local repository or lab project:

# BROKEN: tag missing + no --ref + mutable link + ambiguous cleanup habit.
GLAB_ENABLE_CI_AUTOLOGIN=true glab release create "$LAB_TAG" \
  --notes "Disposable test" \
  --assets-links '[{"name":"asset","url":"https://example.invalid/latest.txt"}]'

Interpretation: if the tag did not exist, the CLI may derive it from the default branch; the link is mutable; and nothing records the verified artifact digest. Repair by (1) recording TARGET_SHA, (2) creating/validating the exact lab tag or adding --ref "$TARGET_SHA", (3) linking an immutable/versioned object, (4) publishing the digest, and (5) recording LAB_TAG for exact cleanup.

10. Security and governance boundaries

• Never paste PATs/job tokens into logs, examples, release notes, or asset URLs.
• Do not disable TLS verification to “fix” a release API error.
• Do not use an unreviewed mutable image for a privileged release job; record/pin tool identity where practical.
• Do not unprotect a production tag namespace just to make a pipeline green.
• Do not let release cleanup delete packages, registry objects, tags, or releases outside the exact disposable namespace.
• Release authorization is not deployment authorization; keep Chapter 21’s environment controls separate.

11. Diagnostic checklist

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. Release deletion and tag deletion are deliberately modeled as separate state changes: the Releases API deletes the release record without deleting the tag.

• 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.