Configuration

shithub uses a layered configuration loader. Sources, in increasing-precedence order:

1. Built-in defaults. Encoded in internal/infra/config/Defaults().
2. TOML file. Path comes from SHITHUB_CONFIG env var, falling back to /etc/shithub/config.toml. Absence is fine; bad syntax is a hard error.
3. Environment variables. SHITHUB_<area>__<key> (double-underscore separates nested keys). Examples below.
4. CLI flag overrides. Passed in by the caller (mostly --addr from shithubd web).

After all four merge, config.Load applies a small set of named aliases (e.g. SHITHUB_DATABASE_URL → db.url) for backward compatibility, then runs Validate. Any validation failure causes shithubd to exit non-zero with a one-line error pointing at the offending key.

Inspecting the active configuration

shithubd config print     # writes the resolved config as TOML, with secrets redacted
shithubd config validate  # exits non-zero if the resolved config is invalid
shithubd version          # includes a one-line summary of which sinks are configured

config print redacts any field whose name contains password, pass, secret, key, token, dsn, or url (URL fields are redacted because they often carry credentials in the userinfo component).

Reference

Env-var examples

# Listen elsewhere
export SHITHUB_WEB__ADDR=:9090

# Connect to Postgres
export SHITHUB_DATABASE_URL=postgres://shithub:dev@127.0.0.1:5432/shithub?sslmode=disable
# (equivalent: export SHITHUB_DB__URL=...)

# JSON logs for prod
export SHITHUB_LOG__FORMAT=json
export SHITHUB_LOG__LEVEL=info

# Enable tracing
export SHITHUB_TRACING__ENABLED=true
export SHITHUB_TRACING__ENDPOINT=http://otel-collector.bare-metal:4318
export SHITHUB_TRACING__SAMPLE_RATE=0.05

# Error reporting via GlitchTip
export SHITHUB_ERROR_REPORTING__DSN=https://glitchtip.bare-metal/<project-id>

# Session signing key (deterministic across restarts in prod)
export SHITHUB_SESSION_KEY=$(openssl rand -base64 32)

# Gate /metrics behind Basic auth
export SHITHUB_METRICS__BASIC_AUTH_USER=prom
export SHITHUB_METRICS__BASIC_AUTH_PASS=<long-random>

Secrets

• Never commit secrets. .env is gitignored; production keys live in a systemd EnvironmentFile= with mode 0600.
• The redaction behavior of config print is documented above and tested in internal/infra/config/config_test.go. If you add a new secret-bearing field, name it so the redactor matches it (containing pass, secret, key, token, dsn, password, or url) — or extend secretFieldNames in internal/infra/config/redact.go.
• Log-line redaction is independent (see docs/internal/observability.md). Both layers exist on purpose; secrets in env-loaded config and in handler-emitted logs travel different paths.

Adding a new key

1. Add the field to the appropriate config struct in internal/infra/config/config.go with a toml: tag.
2. Set its default in Defaults().
3. Add validation in Validate() if it has invariants.
4. If it's secret-bearing, confirm its name matches the redactor.
5. Document it in this file.
6. Update .env.example if the env-var form is the typical usage.