colophon

module
v0.21.4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 19, 2026 License: MIT

README

colophon

Release orchestration that tags the commit which actually landed: work out the version your commits have earned, open the release as a merge request, then resolve the tag against the target branch itself rather than trusting whatever the forge says merged.

Built on gtb, an opinionated, batteries-included framework for Go CLI tools and services.

What is this?

A colophon is the mark a printer leaves on the last page, once the book is actually finished. This one does the same job for a release: it records what was produced, after it was produced.

The problem it exists for. When a release merge request merges, something has to decide which commit gets the tag, and the usual sources are unreliable. Under a fast-forward merge there is no merge commit; with squash off there is no squash commit; and a forge's record of the request's head is not updated by an automatic rebase, so it can name a commit that is no longer on the target branch. A forge will also report a request merged a moment before its commit is reachable there. Measured across phpboyscout/go on 2026-08-01, 9 of 231 recent tags were not on their default branch at all, and nothing had failed.

colophon publish resolves the commit against the target branch, and takes the version from the changelog at that commit rather than from the merge request's body, which under a fast-forward merge is not in git at all. The tag lands on what merged.

Four commands.

Command What it does
plan Compute the next version and the commits that decided it, and print them. Writes nothing: no branch, no merge request, no tag. Needs no credentials, so it is safe to run against any checkout and is the way to compare colophon against whatever a project releases with today.
propose Re-cut the release branch from its target, write the changelog into it, and open or update the merge request that proposes the release. The branch is cut fresh on every run rather than merged forward, so the request can never be behind.
publish Find the merged release request, resolve the commit that actually landed, tag it, and create the release on that tag. Safe to re-run: an already-tagged commit and an already-published release are not errors.
release Create the release for a tag that already exists, whether publish --tag-only or a person made it. The tag must be on the target branch; the notes come from the changelog at that commit, or from history when the changelog does not carry the version. The recovery when colophon cannot release itself.

What it asks of your project. Conventional Commits, and a CHANGELOG.md it maintains for you. That is the whole contract. Nothing in the version decision or the changelog rendering is specific to a language, so a repository of any kind can release through it; colophon is written in Go because it had to be written in something.

Forges. GitLab, GitHub, Gitea, Codeberg and Bitbucket, through the go/forge adapters. The public hosts are recognised from the remote; a self-hosted GitLab, GitHub Enterprise Server or Gitea instance is named with forge: in .colophon.yaml. GitLab is the one the estate releases with daily. Every verb has also passed against real GitHub, Gitea, Forgejo and Codeberg projects, and GitHub Actions has run the whole release, as have Gitea, Forgejo and Codeberg Actions and Bitbucket Pipelines. Bitbucket Cloud proposes, tags and comments, and has no release object. Forge support links each run. Wherever you start, reach for plan first, since it writes nothing.

Status: pre-1.0 and moving. colophon cuts its own releases, so every tag on this repository is one it resolved and created itself. Below 1.0 the CLI surface may still change between minor versions, so pin the tag in a pipeline rather than tracking @latest.

Full documentation, including the reasoning behind each of these decisions, is at https://colophon.phpboyscout.uk.

Prerequisites

  • Go 1.27.0 or newer — required to build and install.

The following tools are only needed for development (they are not required to install or run the binary). Each is invoked by a just recipe:

Install

Install the latest release with go install:

go install gitlab.com/phpboyscout/colophon/cmd/colophon@latest

The main package lives at cmd/colophon/, so the install path ends in /cmd/colophon — installing the module root would fail because it has no main package.

Build & run

This repository ships a justfile with the common tasks. Build the binary with the default recipe:

just            # tidy + generate + build → bin/colophon
just build      # the same, explicitly

Then run it:

./bin/colophon --help

To install the built binary into $GOPATH/bin:

just install

Develop

Clone & verify
just test        # unit tests with coverage
just test-race   # tests under the race detector
just lint        # golangci-lint
just check       # pre-commit hooks across the tree
just ci          # the full local CI suite (tidy, generate, test, test-race, lint)

Run just ci before opening a pull/merge request — it mirrors what CI runs.

Project layout
Path What lives there
cmd/ The main entry point (main.go).
pkg/cmd/root/ The root command — wiring, config loading, feature flags.
pkg/cmd/root/assets/init/config.yaml The default configuration shipped with the tool.
internal/version/ Build-time version metadata (injected via ldflags).
docs/ The documentation site source (served by zensical).
.gtb/manifest.yaml The generator manifest (see below).

Add your own commands under pkg/cmd/<command>/ and your reusable packages under pkg/.

The manifest & regeneration model

colophon is scaffolded and kept in sync by GTB's generator. The .gtb/manifest.yaml file is the source of truth for the command tree and project settings. Two flows operate on it:

  • gtb generate command <name> — scaffold a new command, recording it in the manifest.
  • gtb regenerate — re-render the project from the manifest and the current GTB templates.

Generated files are hash-tracked in the manifest. If you hand-edit a generated file, the next regenerate detects the change as a conflict and prompts before overwriting it — so your edits are never silently lost. This README is one of those files: it is yours to edit, and regeneration will ask before replacing it.

Do not hand-edit generated files expecting silent re-generation. Put custom logic in your own packages, or accept the conflict prompt on the next regenerate.

If a generated file is one you deliberately own — a justfile you have extended, a Dockerfile, a real README.md — mark it hands-off in .gtb/ignore so regenerate stops re-rendering it and stops prompting:

gtb ignore add justfile      # or edit .gtb/ignore by hand
gtb ignore check justfile    # confirm it is now ignored, and by which rule

The scaffold ships a commented .gtb/ignore explaining the syntax. See the Configure Generator Ignore Rules how-to.

Configuration

Configuration is layered (highest precedence first): command-line flags → environment variables → config file → embedded defaults. The shipped defaults live in pkg/cmd/root/assets/init/config.yaml.

Any setting can be overridden from the environment using the COLOPHON prefix. For example, a log.level setting is overridden by COLOPHON_LOG_LEVEL.

Enabled built-ins

GTB provides built-in commands. The following are always available in this project: self-update, first-run init, MCP server, embedded documentation, doctor checks, and changelog.

The following opt-in built-ins are also enabled:

  • Config management — inspect and edit configuration.
  • gitlab

Change the feature set with gtb enable <feature> / gtb disable <feature> (e.g. gtb enable ai) — this updates .gtb/manifest.yaml and re-renders the root command, so the change survives gtb regenerate project. Do not hand-edit pkg/cmd/root/cmd.go; it is generated and will be overwritten.

Run colophon --help to see the full command list.

Documentation

The documentation site source lives in docs/ and is built with zensical. Serve it locally with:

just docs-serve

Then open the printed local URL in your browser.

Releasing

colophon releases itself, so this repository is also the worked example.

On the default branch, colophon publish --tag-only runs before colophon propose, and .gitlab-ci.yml enforces that ordering with needs:. It matters: after a release merge request merges, the release commit is on main but the tag does not exist yet, and the tag is what tells colophon the release happened. Propose first and it re-opens a request for the version about to be tagged. They are also two separate jobs on purpose, because a commit does not carry its own tags and propose only sees the new one because its fetch happens after publish pushed.

The tag is all the default branch produces. Binaries come from GoReleaser on the tag pipeline, and it builds and uploads but does not own the release: .goreleaser.yaml sets release: disable: true and pushes archives to the release store through a blobs: pipe that needs no release to exist. Then colophon-release, the job the cicd component adds when assets: true is set, creates the release last, carrying links to what was uploaded, and resolves every asset before publishing. A release is therefore never observably present-but-empty. It was, before assets: true was set here: v0.2.1's release existed twenty minutes before its first archive did.

Contributing

  • Follow Conventional Commits for every commit — the changelog and version bumps are computed from them.
  • Run just ci before opening a pull/merge request.
  • Do not hand-edit generated files (those tracked in .gtb/manifest.yaml); the next gtb regenerate will flag them as conflicts. If you mean to own a file permanently, add it to .gtb/ignore (or run gtb ignore add <path>).

Go deeper

GTB documentation:

Directories

Path Synopsis
cmd
colophon command
Registers the chat providers this tool ships, one module per line.
Registers the chat providers this tool ships, one module per line.
internal
gitserver
Package gitserver is a stand-in git remote for tests that must prove a token reached the forge it belongs to, without a network or a real forge.
Package gitserver is a stand-in git remote for tests that must prove a token reached the forge it belongs to, without a network or a real forge.
trustkeys
Package trustkeys exposes the public keys embedded in the binary for self-update signature verification.
Package trustkeys exposes the public keys embedded in the binary for self-update signature verification.
mocks
pkg
annotations
Package annotations names the trailers colophon acts on, and reports the ones a commit wrote where colophon cannot read them.
Package annotations names the trailers colophon acts on, and reports the ones a commit wrote where colophon cannot read them.
announce
Package announce tells people a release happened.
Package announce tells people a release happened.
announce/discord
Package discord announces a release to a Discord channel through a webhook.
Package discord announces a release to a Discord channel through a webhook.
announce/file
Package file announces a release by appending it to a structured file in a repository and committing it.
Package file announces a release by appending it to a structured file in a repository and committing it.
apply
Package apply reads what a commit asserted about a forge object and carries it there.
Package apply reads what a commit asserted about a forge object and carries it there.
artifacts
Package artifacts reads goreleaser's build manifest and says which of the things it produced belong on a release.
Package artifacts reads goreleaser's build manifest and says which of the things it produced belong on a release.
cmd/announce
Package announce implements the `announce` verb: tell people a release happened, through the adapters .colophon.yaml configures.
Package announce implements the `announce` verb: tell people a release happened, through the adapters .colophon.yaml configures.
cmd/apply
Package apply implements the `apply` verb: carry what a commit asserted to the forge object it names.
Package apply implements the `apply` verb: carry what a commit asserted to the forge object it names.
cmd/propose
Package propose implements the `propose` verb: write the release branch and open or update its merge request.
Package propose implements the `propose` verb: write the release branch and open or update its merge request.
cmd/publish
Package publish implements the `publish` verb: tag what landed and create its release.
Package publish implements the `publish` verb: tag what landed and create its release.
cmd/release
Package release implements the `release` verb: create the release object for a tag that already exists.
Package release implements the `release` verb: create the release object for a tag that already exists.
cmd/root
Self-update signature-verification enforcement defaults.
Self-update signature-verification enforcement defaults.
history
Package history reads a repository and produces exactly what a version decision needs: where the project is now, and what has landed since.
Package history reads a repository and produces exactly what a version decision needs: where the project is now, and what has landed since.
labels
Package labels offers to create the labels a release merge request asks for when the forge does not have them yet (spec 0029 D9).
Package labels offers to create the labels a release merge request asks for when the forge does not have them yet (spec 0029 D9).
manifest
Package manifest reads the optional file a maintainer commits to the release branch to hold a release back.
Package manifest reads the optional file a maintainer commits to the release branch to hold a release back.
notes
Package notes collects the prose a commit contributes to its release's notes.
Package notes collects the prose a commit contributes to its release's notes.
policy
Package policy decides what the next version is.
Package policy decides what the next version is.
proposal
Package proposal renders the Release merge request: its title and its body.
Package proposal renders the Release merge request: its title and its body.
propose
Package propose writes the release branch and opens or updates its merge request.
Package propose writes the release branch and opens or updates its merge request.
publish
Package publish cuts the release a merged Release merge request describes.
Package publish cuts the release a merged Release merge request describes.
release
Package release creates the release object for a tag that already exists.
Package release creates the release object for a tag that already exists.
remote
Package remote turns a git remote URL into the pieces a forge call needs.
Package remote turns a git remote URL into the pieces a forge call needs.
render
Package render turns a decided release into the text a human reads: the changelog entry, and the body of the merge request proposing it.
Package render turns a decided release into the text a human reads: the changelog entry, and the body of the merge request proposing it.
scheme
Package scheme holds the version schemes colophon can release under.
Package scheme holds the version schemes colophon can release under.
trailer
Package trailer reads git trailers from a commit message.
Package trailer reads git trailers from a commit message.
transient
Package transient retries a read from a forge that failed for a reason that can pass by itself: a timeout, a refused or reset connection, or a busy server.
Package transient retries a read from a forge that failed for a reason that can pass by itself: a timeout, a refused or reset connection, or a busy server.
tree
Package tree re-cuts the release branch.
Package tree re-cuts the release branch.
versionfile
Package versionfile writes a release's version into the files a language's own tooling reads it from, for a language whose version is not the tag (spec 0027 D2).
Package versionfile writes a release's version into the files a language's own tooling reads it from, for a language whose version is not the tag (spec 0027 D2).
versionfile/cargo
Package cargo writes a release's version into a Cargo crate or workspace: the package or workspace version, the requirements that name a member by path, and Cargo.lock (spec 0027 D3).
Package cargo writes a release's version into a Cargo crate or workspace: the package or workspace version, the requirements that name a member by path, and Cargo.lock (spec 0027 D3).
test
e2e/steps
Package steps holds the Godog step definitions for colophon's feature suite.
Package steps holds the Godog step definitions for colophon's feature suite.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL