docs: add configuration reference for the application config file

Context

The application configuration file had no field-by-field reference for the people who configure the service, config.example.yaml omitted the storage block entirely, and several fields read as optional-with-default when the service actually requires them at startup.

Found while building the self-managed CNG install baseline for the closed beta (gitlab-org&21052).

What's included

  • docs/dev/configuration-reference.md: a field-by-field reference for configuration schema v1 (type, required or optional, default) covering every block. Written for the users, administrators, and operators who configure the service: it documents behavior only, without source references or schema internals.
  • config.example.yaml: a live storage block (the service fails to start without a storage backend), a note that the bootstrap token currently comes from the AR_BOOTSTRAP_TOKEN environment variable, and comment cleanups for the same audience.
  • A CLAUDE.md guardrail and a GitLab Duo review rule (config-doc-pairing) that flag configuration schema, loader, or example changes made without a matching update to the reference doc, so the reference does not drift the way config.example.yaml did.

Two gaps between the schema and the runtime surfaced while cross-checking the reference against the loader; both are tracked under the closed-beta epic, and the reference documents the current behavior:

  • #302: the auth block is never read; the token comes only from AR_BOOTSTRAP_TOKEN.
  • #303: the defaults documented in the schema comments (server, s3.path_style) are not applied.
Edited by João Pereira

Merge request reports

Loading
Loading