Skip to content

colophon release

Description

Create the release for a tag that already exists

Create the release object for an existing tag, whether publish --tag-only or a person made it. The tag is resolved on the remote and must be contained by the target branch; a tag on a commit that never landed is refused, and there is no flag past that. The notes come from CHANGELOG.md at the tagged commit when it names the version, and are rendered from the commits since the previous release when it does not.

Usage

colophon release --tag <tag> [flags]

Run colophon release --help for the authoritative, always-current flag set.

Flags

Flag Description Default
--tag The existing tag to release, e.g. v1.2.3. Required. none
--target Branch that must contain the tagged commit main
--remote Git remote to read from origin
-C, --repo Path to the git repository .
--assets goreleaser dist directory; its artifacts.json names what the release should carry none
--asset-base URL the artefacts were uploaded under, appended with each asset's name none

Where the notes come from

release reads CHANGELOG.md at the tagged commit. When its newest section names the tag's version, that section is the release's notes, byte for byte what publish would have used. That is every release publish --tag-only made.

When it does not, which is what a hand-cut tag looks like, the notes are rendered from the commits between the previous release and the tag, the way propose would have rendered them, and the output says so:

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

The file is not backfilled. The release object carries those notes and nothing else does; the next propose renders only the version it proposes. See Recover with a hand-cut tag.

The previous release is the highest semver tag reachable from the tagged commit whose version is below the one being released. Two tags below it that tie on precedence and differ only in build metadata are refused rather than chosen between, for the same reason plan refuses them.

What is refused

  • A tag the remote does not carry. release never creates one.
  • A tag whose commit the target branch does not contain. Name the branch that does contain it with --target; there is no flag that skips the check.
  • A tag that is not a semantic version.
  • --assets without --asset-base, or the reverse.

A hold in .colophon.yaml is not consulted. A hold stops publish deciding to release; once a tag exists the decision has been made.

Re-running

Safe. An existing release is reported as already present and the command exits zero. It does not attach assets an existing release is missing; that is colophon#7.

In the pipeline

This is the job the cicd component's colophon-release runs on the tag pipeline, after goreleaser has uploaded, so a release is never visible without its assets. Until the component invokes release directly it runs publish with the same asset flags, which creates the same release for a tag publish made and no release for one it did not.