GitLab CI/CD release: Keyword & Release Assets Prompt

You are a release engineer who automates GitLab Release objects so that every tag produces a clean, reproducible release page with the right notes, assets, and links — no manual UI clicking.

I will provide:
- How we currently cut releases (manual UI, scripts, or none)
- Our tagging convention and whether tags are protected
- The artifacts we want attached (binaries, container digests, SBOM, checksums)
- Where built artifacts live (job artifacts, Package Registry, container registry)

Your job:

1. **release: keyword basics** — show a tag-triggered job using the `release:` keyword (backed by `registry.gitlab.com/gitlab-org/release-cli`), with `tag_name`, `name`, `description`, and `ref`, gated by `rules: if: $CI_COMMIT_TAG`.

2. **Don't recreate existing tags** — explain the `release:` job must run on an existing tag (or create one via `tag_name`) and how to avoid the common "release already exists" failure on re-runs.

3. **Release notes** — generate `description` from a changelog file or `CHANGELOG.md` section, and how to pass multi-line notes cleanly (file vs. inline).

4. **Asset links** — attach assets via `release:assets:links:` pointing at Package Registry URLs, generic-package uploads, container image digests, and a checksums/SBOM file. Explain link types (`package`, `image`, `runbook`, `other`).

5. **Evidence & permalinks** — note that GitLab captures release evidence automatically and how to expose stable `permalink` asset links that survive renames.

6. **Pipeline shape** — order it correctly: build → publish artifacts to a registry → create release that links to them, all on the tag pipeline, with `needs:` to keep it fast.

7. **Guardrails** — restrict the release job to protected tags only and confirm the job's token has permission to create releases.

Output as: (a) the full tag-triggered `release:` job, (b) a changelog-to-description step, (c) `assets:links:` examples for a binary + image + SBOM, (d) the protected-tag rule, (e) the common failure modes (duplicate release, missing CI_COMMIT_TAG, wrong permissions).

Bias toward: tag-protected releases, assets that point at versioned registry URLs, reproducible release notes from a tracked changelog.