March 10, 2025"> October 15, 2026">
Skip to content

Configuration

Initialize configuration interactively:

gptchangelog config init

Project configuration is stored in .gptchangelog/config.ini; global configuration is stored in ~/.config/gptchangelog/config.ini. Project values take precedence over global values.

Example

[openai]
provider = openai
profile = balanced
model = gpt-5.6-terra

Supported providers are openai and codex. Unsupported or misspelled values are rejected.

Supported profiles are:

Profile OpenAI model Codex model
balanced (default) gpt-5.6-terra gpt-6.1-sol
quality gpt-5.6-sol gpt-5.6-sol

An explicit --model or GPTCHANGELOG_MODEL overrides the profile model. This selects the final changelog model. Commit messages are first processed by gpt-6-luna in batches of up to 40 using its default reasoning effort, for both providers. Commit processing does not override source IDs, categories, or the locally calculated version.

Authentication

For the OpenAI provider, use an environment variable:

export OPENAI_API_KEY='...'

The initializer uses hidden input if you explicitly choose to persist a key, and any credential-bearing configuration is written with owner-only permissions. Environment-based credentials are preferred. On POSIX systems, GPTChangelog rejects a stored-key configuration if group or world permission bits are present and reports the exact chmod 600 command to repair it.

For Codex subscription access:

codex login

GPTChangelog uses Codex's supported non-interactive client. Codex owns login caching and token refresh. Invocations ignore personal Codex configuration so model defaults, including Luna's reasoning effort, apply consistently; Codex authentication is retained.

Precedence

  1. --provider, --profile, and --model
  2. GPTCHANGELOG_PROVIDER, GPTCHANGELOG_PROFILE, and GPTCHANGELOG_MODEL
  3. project configuration
  4. global configuration
  5. Codex provider and the balanced profile (GPT-6.1 Sol for the release draft)

When no provider is selected, Codex is used even if OPENAI_API_KEY is set. Select openai explicitly to use the API. Configuration files that omit provider also default to Codex.

Provider overrides do not accidentally reuse a model configured for a different provider.

Inspect and validate

gptchangelog config show
gptchangelog config validate

show redacts secrets. validate checks syntax, model resolution, and authentication availability.

Debug logging

Set GPTCHANGELOG_DEBUG=1 to enable debug diagnostics on stderr. Raw model responses are never written automatically because they can contain repository data.