colophon¶

The jobs:

A wrapper over phpboyscout/colophon, the release orchestrator this estate owns and can fix. Sibling of releaser-pleaser, which it is intended to replace — see spec 0077.

$ colophon plan          # tag present
No release due — 0.1.0, 0 commits considered

$ colophon plan          # same commit, tag removed
0.0.0 → 0.1.0 (minor), decided by 30 commits

What changes if you swap from releaser-pleaser¶

One thing, and it is deliberate.

colophon releases on perf and refactor. releaser-pleaser releases on neither. So a project that swaps will see release-worthy commits it did not see before, and a changelog entry under Other.

Measured on colophon's own history, both tools over the same commits:

• both compute the same version (v0.1.0)
• the changelogs differ by exactly one entry — the single refactor: commit
• nothing releaser-pleaser lists is missing from colophon's

Run colophon plan on a project before swapping it and diff the answer. That is what plan is for: it computes what colophon would do and writes nothing.

What gets simpler¶

releaser-pleaser needs a second job, a second container image, and a forced squash: true on every Release MR. All of that exists to work around one upstream behaviour: it picks the release commit as merge-commit, else squash-commit, else the merge request's recorded head — and GitLab 19.2's automatic rebase never writes a rebase back to that record. Measured 2026-08-01, 9 of 231 recent tags across phpboyscout/go were not on their default branch, over 8 repositories.

colophon cannot reach that code path. It resolves the release commit with forge.PullRequests.ResolveMergedCommit, which returns a commit confirmed present on the target branch or ErrNotFound, and forge.PullRequest carries no head-SHA field at all — there is nothing to fall back to and be wrong about.

So this component has no verify job, forces nothing on your merge requests, and pulls one image.

Not inputs, deliberately¶

Anything colophon reads from the repository has no component input, because a second place to say it is a second thing to disagree with:

A hold stops publish acting. It does not stop the version being computed or the Release MR being maintained — a hold should make the pending release easier to look at, not hide it.

The checkout must be full¶

Every colophon job sets GIT_DEPTH: "0". colophon reads the history back to the last release tag, and the tags, from the job's checkout, and a shallow clone fails every verb with:

ERRO reading commits: iterating commits: object not found

GitLab's project default depth of 20 is shallow enough to fail. The component's per-job setting wins over the project default; do not override it in a default: or variables: block that reaches these jobs. The full contract a pipeline has to meet is colophon's pipeline requirements page.

colophon-release-check is the one job here that runs the git CLI against the checkout, and the runner's helper creates that checkout as root while the image runs as uid 1000, so the job adds safe.directory for the project before its first git command. Without it git diff a b refuses silently and prints error: Could not access '<sha>'.

Nested tags (tag_also)¶

colophon 0.4.0 can cut <dir>/<root tag> alongside the root tag for a nested Go module listed under tag_also in .colophon.yaml. Three things follow for a consumer that adopts it:

• A nested tag starts a tag pipeline wherever the project's workflow: admits $CI_COMMIT_TAG. Narrow that rule to $CI_COMMIT_TAG =~ /^v/ unless the nested tag should build something.
• colophon-release and goreleaser both gate on tag_pattern, whose default matches root tags only, so a nested tag never starts a release or a build.
• A v* protected-tag pattern does not cover lint/v*; protect the nested pattern separately if it matters.

Inputs¶

Carrying a decision to a ticket or a spec¶

colophon-apply runs on every push to the target branch, not only when a release is cut. It reads the commits that push added and acts on the Updates: trailers they carry:

fix(publish): read the manifest at the released commit

Updates: #13 shipped Fixed in v0.5.0.
Updates: cicd/wikis/specs/0079-pipeline-churn implemented

Keywords are a closed vocabulary — shipped and implemented. A word colophon does not know is refused and reported, never guessed at.

A page whose frontmatter does not carry the field a keyword names is refused rather than grown one, and a page already carrying the value is reported unchanged and not rewritten. Re-running is safe: each comment carries an idempotency key naming the commit that asserted it, so a retried pipeline posts nothing twice.

Announcing a release¶

When publish creates a release object it announces it — through whatever adapters the project's .colophon.yaml names, and only those. Nothing is announced by default, and nothing here changes that: a project opts in.

Two adapters exist. discord is the project's own word and lives wholly in the manifest:

announce:
  discord:
    webhook: $DISCORD_RELEASE_WEBHOOK   # an environment reference, never a value
    when: any                           # the smallest release to announce

file appends the release to the estate's feed in phpboyscout/blog, and its settings are this component's, not the project's: for a public project the job writes them to a colophon config file and passes it with --config. A project enables the feed with one line, and inherits everything else:

announce:
  file: {}

A project block with fields lays over the operator's field by field. A private project never gets the settings at all ($CI_PROJECT_VISIBILITY), because a private release must not reach a public feed — and it has no file: {} either way.

The announcement happens inside the job that creates the release, immediately after the release object exists: colophon-publish on the default branch for most projects, colophon-release on the tag pipeline for an assets: true one. There is no separate announce job and nothing to order: the old discord-release component announced from the tag pipeline, which on a project without assets starts before the release object exists (publish tags first, then releases), and retried around the gap. That gap cannot open here. The verb exits 0 whatever the adapters report — a chat message must not redden a release — and the report gains an announce <tag> section saying announced, skipped, failed or unchanged per adapter.

The feed's credential is the group GITLAB_TOKEN (feed_token), reaching colophon as $CICD_FEED_TOKEN: the publish job exports GITLAB_TOKEN as the colophon token, so a config file naming $GITLAB_TOKEN would quietly read the wrong one.

announce: false passes --no-announce to both verbs. feed_repo: ./out (any path) writes the feed under that directory and commits nothing — what the self-test uses, and a dry run of what the blog would receive.

Spec 0100 and colophon spec 0026.

Usage¶

stages:
  - lint
  - test
  - release

include:
  - component: gitlab.com/phpboyscout/cicd/[email protected]
    inputs:
      stage: release
      branch: main

Migrating in stages? Start with publish: false, which writes a branch and a merge request and cuts nothing, and compare its Release MR against the one releaser-pleaser is already maintaining.

Recovering with a hand-cut tag¶

When colophon itself cannot cut a release, a maintainer can push the vX.Y.Z annotated tag by hand (v* tags are protected at Maintainer across the estate). The tag pipeline runs as usual. For an assets: true project colophon-release runs colophon release --tag $CI_COMMIT_TAG, which starts from the tag rather than from the last merged release MR, so the hand-cut tag gets its release object, assets and announcement exactly as a merged one would (colophon spec 0005 D7). A project without assets gets the tag and its build, and the release object is created by running colophon release --tag vX.Y.Z by hand.

colophon's runbook walks through it: Recover with a hand-cut tag.

A project that names its own assets¶

A release's files usually come from goreleaser, and dist points at where it put them. A project that no build tool describes can instead list them in its own .colophon.yaml (colophon ≥ 0.10.0), and then there is no dist to point at:

include:
  - component: gitlab.com/phpboyscout/cicd/[email protected]
    inputs:
      stage: release
      branch: main
      assets: true
      dist: ""

dist: "" is required, and it is the part that is easy to miss. The two sources are alternatives rather than a union — colophon refuses both at once, deliberately, so that a missing asset has exactly one place it should have come from. This input's default is goreleaser-shaped, so a manifest project that says nothing inherits a dist it does not have and is refused at the end of its first release pipeline, on an error naming a flag it never passed.

Blanking it is not a workaround. dist means goreleaser's output directory, and a project with no goreleaser has none.

asset_base still applies: it is the URL the files were uploaded under, whichever source named them. phpboyscout/ffmpeg-wasi is the worked example in the estate.