---
since: 1.1.1
---

# 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-set real environment variable always takes precedence over a value loaded from `.env`.

## 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`](../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 |

## Consent storage (outside `.env`)

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`](../user-guide/telemetry.md) for the full consent model.

## Related

- [`../user-guide/configuration.md`](../user-guide/configuration.md) — practical guide with worked examples
- [`../architecture/security-and-privacy.md`](../architecture/security-and-privacy.md) — how credentials flow through the AI client boundary