Recover with a hand-cut tag¶

For when colophon cannot cut the release itself: a defect in the version it ships, a pipeline that cannot run, or a release that must go out before the fix does. The tool that releases the tool is the tool, and this is the way around that.

Every artefact job in this estate keys off the tag existing, not off which tool created it. So the recovery is a tag, and then one command that creates the release for it.

1. Tag the commit that should ship¶

An annotated tag, on a commit that is on the target branch. Anything else is refused in step 3.

git fetch origin main
git tag -a v0.1.4 -m "Release v0.1.4" origin/main
git push origin v0.1.4

v* tags are protected at Maintainers on this estate's projects, so a person with that role can push one.

2. Let the tag pipeline build¶

goreleaser runs on the tag and uploads the archives to the package registry. It does not create a release: since spec 0004 that is colophon's job, and a release is created only once its assets exist.

3. Create the release for the tag¶

GITLAB_TOKEN=... colophon release --tag v0.1.4 --target main \
  --assets dist --asset-base "https://gitlab.com/api/v4/projects/<id>/packages/generic/<name>/0.1.4"

Omit --assets and --asset-base for a project that ships no binaries. The asset base is the same URL the project's .goreleaser.yaml uploads to, with the version filled in; release proves each artefact resolves there before it links anything.

Where the project's colophon-release job already invokes release, this step is the tag pipeline's and needs no hand. Where it still invokes publish, run the command yourself: publish starts from a merged release request, and a hand-cut tag has none, so it creates no release for it.

What you get, and what you do not¶

The release object exists, carrying the archives, with notes rendered from the commits between the previous release and the tag. The output says so:

warning  CHANGELOG.md at 3c1f0a92 names v0.1.3, not v0.1.4; notes rendered from history and the file is not backfilled

CHANGELOG.md on the target branch does not carry this version and nothing will add it. The next propose computes the next version from the tag you pushed, as it does from any tag, and renders only that version's section. If the changelog must have the entry, write it by hand in the next release's merge request, where it will land under a fast-forward merge like any other commit.

A tag on a commit the target branch does not carry is refused, naming the branch. That is not a flag away: a tag that never landed is the state colophon exists to prevent. Release a maintenance line by naming it as --target.

Then fix colophon¶

The recovery is complete once the release exists. The reason it was needed is still there.