Visit djangoplay.org ↗
gitaiflow / API / Configuration Contract
DocsgitaiflowAPIConfiguration Contract

Configuration Contract

gitaiflow reads its configuration from environment variables, optionally supplied via a .env file discovered by walking upward from the current working directory to the repository root. An already-...

3 min readApplies to v1.1.3
On this page ▾
  1. Schema
  2. Fail-fast behavior
  3. Precedence
  4. Provider examples
  5. Consent storage (outside .env)
  6. Related

Schema

Variable Type Default Required
AI_PROVIDER free-form label (gemini, openai, ollama, custom, ...) (none) Yes
AI_BASE_URL string (URL) (none) Yes
AI_API_KEY string (none) Yes — required for every provider, including ones (e.g. Ollama) that ignore its value
AI_MODEL string (none) Yes
AI_TEMPERATURE float 0.2 No
AI_MAX_TOKENS integer 4096 No
AI_REQUEST_TIMEOUT integer (seconds) 60 No
GITAIFLOW_REMOTE string unset No — standing fallback for git remote resolution
GITAIFLOW_MAX_RUNS_PER_DAY integer unset (no limit) No
GITAIFLOW_MAX_TOKENS_PER_DAY integer unset (no limit) No
GITAIFLOW_TELEMETRY boolean (true/false) unset (falls back to saved consent, or a prompt at an interactive terminal) No
GITAIFLOW_TELEMETRY_URL string (URL) maintainer's default endpoint No

AI_PROVIDER, AI_API_KEY, AI_BASE_URL, and AI_MODEL have no built-in defaults or provider presets anymore — all four must resolve to a non-empty value from one of the three tiers below.

Fail-fast behavior

If any of the four mandatory variables is still empty after checking all three configuration tiers, gitaiflow fails immediately, naming exactly which ones are missing, before any Git analysis or AI request is attempted. This is deliberate — a normal summary run should never partially execute (spend time generating a diff, then fail) due to missing provider configuration.

Precedence

text
Real environment variable (exported, CI secret, etc.)
        │
        │  always wins over
        ▼
Project-local .env file value
   (discovered walking upward from cwd to repo root)
        │
        │  falls back to
        ▼
Global ~/.gitaiflow/config.env
   (created empty by the installer, left untouched on upgrades)

GITAIFLOW_REMOTE follows this same three-tier lookup, but stays optional.

GITAIFLOW_TELEMETRY is a special case: it overrides the durably saved telemetry consent decision for the current process only, without changing what's saved. See ../user-guide/telemetry.md for the distinction between this env var and gitaiflow --telemetry enable/disable.

Provider examples

There are no provider presets — every provider needs all four mandatory variables set explicitly:

Provider Example AI_BASE_URL Example AI_MODEL AI_API_KEY
Gemini https://generativelanguage.googleapis.com/v1beta/openai gemini-flash-lite-latest Real key
OpenAI https://api.openai.com/v1 gpt-4.1-mini Real key
Ollama http://127.0.0.1:11434/v1 llama3.2:3b Any non-empty value — Ollama ignores it, but gitaiflow still requires one
Custom Your endpoint Your model id Real key

Telemetry consent is intentionally not part of the .env/environment-variable contract above — it's a separate, durable, per-machine file:

text
~/.gitaiflow_telemetry_consent

Kept deliberately separate from the local usage log (~/.gitaiflow/usage.jsonl) so clearing the usage log never resets the telemetry decision. See ../user-guide/telemetry.md for the full consent model.