colophon publish¶

Description¶

Tag the commit that landed and create its release

Usage¶

colophon publish [flags]

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

Flags¶

Flag	Description	Default
`--author-email`	Email on the release tag	`[email protected]`
`--author-name`	Name on the release tag	`colophon`
`--announce-failure-exit`	Exit with this code when the release stood and an announcement failed. `0` keeps exit 0; `1`, `2` and anything above `125` are refused. See making a failed announcement show	`0`
`--branch`	Release branch whose merge request to publish	derived: `colophon/release/<target>`
`--remote`	Git remote to read and push to	`origin`
`--forge`	Forge the remote is on when its host does not say: `gitlab`, `github` or `gitea`. Same as `forge` in `.colophon.yaml`; both must agree when given.	empty
`--no-announce`	Create the release without announcing it; the adapters `.colophon.yaml` names stay quiet	`false`
`-C`, `--repo`	Path to the git repository	`.`
`--tag-only`	Push the tag and stop, leaving the release to a later run on the tag pipeline	`false`
`--target`	Branch the release landed on	`main`

A release with assets¶

A build tool that takes its version from the tag can only run after the tag exists, so a release created on the default branch is created before its binaries do. --tag-only cuts the tag and stops; release creates the release on the tag pipeline once the build has uploaded, carrying links to what it uploaded. publish itself never attaches assets.

See Publishing a release complete for why this is shaped the way it is.

The release it created is announced¶

When .colophon.yaml names announce adapters, a release this run created is announced once the object exists, and the report gains a section per release in the words announce uses:

announce v1.2.3
  announced  discord
  unchanged  file

Only what this run created: a release found already there is reported and announced to nobody, and --tag-only announces nothing because the release is release's to create. A failed announcement is reported and does not fail the run, unless --announce-failure-exit asks for a code to show it. --no-announce withholds it and says so.

Needs a forge token in <FORGE>_TOKEN. See the configuration reference.

Components¶

At the merged commit, publish reads the manifest and each own component's <dir>/CHANGELOG.md, and takes the tag its top section names. A tag that does not exist is this release's: it is cut at the commit, root first, and its release object is created from that section. A tag already at this commit is a re-run finding its own work. A tag that exists at another commit is an earlier release: the component did not release this time, and the report says so and leaves it alone. The same reading applies to the root in a repository with components, so a component-only release leaves the root untouched, and a repository whose root has never released may have no root changelog at all.

The report prints one tag line per tag and one release line per release object. A tag_also directory's tag carries none, nor does a component's whose release is off, which a shared component's is by default; those have no release line. Under --tag-only every tag is cut and no release is created; each tag's own pipeline creates its release with release --tag.

Global flags¶

Flag	Description	Default
`--ci`	Indicates the tool is running in a CI environment	`false`
`--config`	Config files to use (repeatable)	`/etc/colophon/config.yaml`, `~/.colophon/config.yaml`
`--debug`	Force debug log output	`false`
`--output`	Output format: `text` or `json`	`text`

Run colophon <command> --help for the authoritative, always-current flag set.