colophon

module
v0.2.1 Latest Latest
Warning

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

Go to latest
Published: Sep 1, 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.

Three 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.

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. GitLab is the one it has been run against in earnest, and the one the estate releases with daily; treat the others as supported by the library rather than proven by use, and 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 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.

Binaries come from GoReleaser, which builds and uploads but does not own the release. .goreleaser.yaml sets release: disable: true and pushes archives to the package registry through an uploads: pipe that needs no release to exist. colophon then creates the release last, on the tag pipeline, carrying links to what was uploaded, and resolves every asset before publishing. A release is therefore never observably present-but-empty.

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
Activates OS keychain support by blank-importing the go-keyring-backed Backend.
Activates OS keychain support by blank-importing the go-keyring-backed Backend.
internal
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.
pkg
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/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/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.
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.
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.
trailer
Package trailer reads git trailers from a commit message.
Package trailer reads git trailers from a commit message.
tree
Package tree re-cuts the release branch.
Package tree re-cuts the release branch.
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