Configuration reference¶

colophon's own configuration, as against the per-repository release manifest.

Config files¶

Read in order, later files overriding earlier ones:

/etc/colophon/config.yaml
~/.colophon/config.yaml

Override the list with --config, which may be repeated.

colophon init writes a starting file; colophon config inspects the resolved result.

Keys¶

log:
  level: info

server:
  grpc:
    reflection: true

update:
  policy: ""
  check_interval: ""
announce: {}

Key	Type	Default	Meaning
`log.level`	string	`info`	Log verbosity. `--debug` forces debug regardless.
`server.grpc.reflection`	boolean	`true`	gRPC server reflection, for the framework's server mode.
`update.policy`	string	empty	`disabled` (log only), `prompt` (ask; declining continues), or `enabled` (block until updated). Empty uses the compiled-in baseline.
`update.check_interval`	duration	empty	Any Go duration, e.g. `24h`, `168h`. `0` checks on every invocation. Empty uses the baseline, 24h.

Environment variables¶

Configuration keys map to environment variables under the COLOPHON prefix, so log.level is COLOPHON_LOG_LEVEL.

Forge credentials do not use that prefix. The token is read from <FORGE>_TOKEN, upper-cased from the forge name derived from the git remote, or from forge in .colophon.yaml (or --forge) when the remote's host is a self-hosted instance:

Forge	Variable	Git basic-auth user
GitLab	`GITLAB_TOKEN`	`oauth2`
GitHub	`GITHUB_TOKEN`	`x-access-token`
Bitbucket	`BITBUCKET_TOKEN`	`x-token-auth`
Gitea, Codeberg	`GITEA_TOKEN`, `CODEBERG_TOKEN`	`x-access-token`

A self-hosted GitLab reads GITLAB_TOKEN and a GitHub Enterprise Server reads GITHUB_TOKEN: the variable follows the forge named, not the host.

The username column is go/repo v0.4.0's basicAuthUsername: GitLab is oauth2, Bitbucket is x-token-auth, and everything else is x-access-token.

The token is resolved lazily, so only the commands that authenticate need one. plan never does.

A release push always needs a credential, whatever the repository's visibility, so an absent token fails fast with a hint rather than being attempted unauthenticated. An unauthenticated attempt surfaces as a rejected push, which reads as a permissions problem rather than a missing variable.

In CI, the token must not be CI_JOB_TOKEN: a tag pushed with it does not fire downstream tag pipelines. See Run it in GitLab CI.

Global flags¶

Available on every command.

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

`announce`¶

The operator's settings for the announce adapters, in the manifest's own shape and read by the manifest's own parser, so a literal secret or an unknown field is refused for the same reasons:

announce:
  file:
    repo: phpboyscout/blog
    token: $GITLAB_TOKEN
    path: data/releases/{path_dashed}.yaml
    list: releases
    key: url
    entry:
      name: "{name}"
      tag: "{tag}"
      date: "{released_at}"
      url: "{url}"

Settings only. An adapter here does nothing until a project's .colophon.yaml names it (file: {}), and a project's own fields lay over these. A CI component that ships this block for every project is the intended reader.

Every COLOPHON_* environment variable is bound to a configuration key, so a shell variable that happens to share the prefix (COLOPHON_ANNOUNCE_FLAGS, say) lands in this block. A refusal names such a variable when one is present; a CI job keeps its own state under another prefix.