colophon

module
v0.1.0 Latest Latest
Warning

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

Go to latest
Published: Aug 30, 2026 License: MIT

README

colophon

Release orchestration for GitLab and Go — propose a release, confirm what actually landed on the target branch, and cut the tag from that commit and nothing else.

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

What is this?

Describe your tool here. colophon is a command-line tool built on the GTB framework. Tell readers what it does and why they would reach for it. The sections below explain how to install, run, and develop on it.

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

Releases are driven by Conventional Commits and run through the scaffolded CI pipeline (GitLab CI under .gitlab-ci.yml) together with GoReleaser (.goreleaser.yaml). Merging a release cuts the tag and publishes the build artefacts.

See the GTB release guide for the full workflow: https://gtb.phpboyscout.uk/how-to/custom-release-source/

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