---
since: 1.1.1
---

# gitaiflow — Security and Privacy

gitaiflow is designed around a local-first execution model. Git discovery, diff generation, filtering, artifact creation, usage accounting, and provider configuration happen locally. The main external data boundary is the configured AI endpoint used for summary generation, plus the optional anonymous telemetry endpoint when telemetry has been explicitly enabled.

## Security and Privacy Architecture

```mermaid
flowchart TD
    A["🔐 Sensitive Repository Data"]

    A --> B["🛡️ Protection Before AI Request"]

    B --> C["File Exclusions<br/><small>.env · certificates · generated artifacts<br/>binary / generated files</small>"]
    B --> D["Secret Redaction<br/><small>SECRET_KEY · API_KEY · PRIVATE_KEY<br/>ACCESS_KEY · CLIENT_SECRET</small>"]

    C --> E["📤 Filtered Diff"]
    D --> E

    E --> F{"Where is the AI request sent?"}

    F -->|Local endpoint| G["🖥️ Local AI<br/><small>Ollama / vLLM / LM Studio</small>"]
    F -->|Cloud endpoint| H["☁️ External AI Provider<br/><small>Gemini · OpenAI · OpenRouter<br/>Grok · DeepSeek · Custom</small>"]

    H --> I["⚠️ Provider Data Boundary<br/><small>Provider controls retention,<br/>logging and data-use policies</small>"]

    J["🔑 API Credentials<br/><small>Environment variables / .env</small>"]
    J --> K["AI Client"]
    K --> F

    L["📁 Local Artifacts<br/><small>Diff · JSON · Markdown</small>"]
    E --> L

    M["📊 Local Usage Log<br/><small>Operational metadata only</small>"]

    M --> N{"Telemetry enabled?"}

    N -->|No| O["🚫 No Telemetry Transmission"]
    N -->|Yes| P["📡 Anonymous Telemetry<br/><small>Version · provider · model · counts<br/>duration · OS · success/failure</small>"]

    P --> Q["🌐 Telemetry Endpoint"]

    R["🚫 Never included in telemetry<br/><small>Repository · paths · diff · branch<br/>author · commit message · summary</small>"]
    R -.-> P

    S["⚠️ Best-Effort Protection<br/><small>Redaction is not a complete secret scanner</small>"]
    S -.-> D

    classDef sensitive fill:#fff0f0,stroke:#d64545,stroke-width:2px,color:#5c2020;
    classDef security fill:#fff4df,stroke:#d59a2a,stroke-width:2px,color:#5c420b;
    classDef local fill:#e8f7f1,stroke:#2b9a78,stroke-width:2px,color:#174d3d;
    classDef external fill:#eeeaff,stroke:#7957c7,stroke-width:2px,color:#382568;
    classDef safe fill:#e8f1ff,stroke:#4a78c2,stroke-width:2px,color:#172b4d;
    classDef warning fill:#fff8e8,stroke:#c58a18,stroke-width:2px,color:#654800;

    class A sensitive;
    class B,C,D,J,S security;
    class E,G,L,M,O local;
    class H,I,P,Q external;
    class K,N,R safe;
```


## Data Flow

### 1. Local Git Data

gitaiflow reads the selected repository and obtains:

- changed files
- diff content
- repository name
- current branch
- resolved base reference
- Git author
- change timestamps
- file status

These values are collected locally.

### 2. Diff Filtering and Redaction

Before a normal AI request, the generated diff is filtered.

The implementation excludes sensitive/environmental material including:

```text
.env
.env.env.bak
.env.env.decrypted.bak
.certs
change-summary
```

It also skips configured binary/generated file types such as Markdown, fonts, images, minified assets, and packages.

Sensitive-line matching covers names such as:

```text
SECRET_KEY
API_KEY
PRIVATE_KEY
ACCESS_KEY
CLIENT_SECRET
```

and their lowercase forms. Matching is deliberately pattern-based and only redacts lines that match the implementation's sensitive-line heuristic.

> **Important:** this is best-effort redaction, not a complete secret scanner. A repository can contain credentials under other names or in formats that do not match these patterns. Review the generated diff before sending sensitive code to a third-party provider.

### 3. AI Provider Boundary

`AIClient` sends a JSON chat-completions request containing:

- the generated system prompt
- the filtered/redacted diff
- configured model parameters

The destination is determined by `AIConfig`.

Possible destinations include:

- Gemini's OpenAI-compatible API
- OpenAI
- OpenRouter
- Grok
- DeepSeek
- Ollama
- vLLM
- LM Studio
- another OpenAI-compatible endpoint configured by the user

For cloud providers, the provider can therefore process the repository diff and prompt content. gitaiflow cannot control provider-side retention, logging, training, billing, or privacy policies.

For local providers such as Ollama, the request can remain within the local environment.

## Credentials

AI credentials are supplied through environment variables or a `.env` file discovered from the current directory upward to the repository root.

Typical configuration:

```text
AI_API_KEY=<secret>
AI_BASE_URL=<endpoint>
AI_MODEL=<model>
```

The `.env` file should not be committed to source control.

gitaiflow does not put the configured API key into the generated JSON or Markdown artifacts.

## Local Artifacts

Normal runs create:

```text
change-summary/
└── <YYYY>/<MM>/<DD>/
    ├── diff/
    ├── json/
    └── markdown/
```

The JSON payload intentionally contains Git/application metadata and the generated commit summary. It can include:

- repository name
- branch
- base reference
- Git author name/email
- changed file paths and statuses
- selected provider/model
- generated commit title/body

Because these artifacts are local files, their confidentiality depends on the permissions and storage security of the user's machine and repository workspace.

The intermediate `diff/` artifacts are also local, but they contain the filtered diff used for the current run. They should be treated as potentially sensitive even after redaction.

## Local Usage Log

Usage accounting is stored locally at:

```text
~/.gitaiflow/usage.jsonl
```

The local usage record includes operational fields such as:

- timestamp
- repository name
- target type
- provider
- model
- changed-file count
- estimated input/output tokens
- duration
- success/failure

This local log is not transmitted unless the separate telemetry path is enabled.

## Telemetry

Telemetry is **disabled unless the user opts in**.

Consent can be controlled with:

```bash
gitaiflow --telemetry enable
gitaiflow --telemetry disable
gitaiflow --telemetry status
gitaiflow --telemetry history
```

For a single process/session, `GITAIFLOW_TELEMETRY=true|false` overrides the stored decision without changing the saved consent.

When telemetry is enabled, the transmitted run payload contains only the documented operational fields:

- install ID
- event type
- timestamp
- gitaiflow version
- AI provider
- model name
- target type
- changed-file count
- estimated input/output token counts
- duration
- success/failure
- operating-system name

The telemetry payload does **not** contain:

- repository path or repository name
- file paths
- diff contents
- generated summary text
- Git author
- Git branch
- commit message

Telemetry uses a short request timeout and failures are non-fatal to the main gitaiflow run.

## Consent Persistence

The durable consent record is stored separately from the local usage directory:

```text
~/.gitaiflow_telemetry_consent
```

This prevents deleting `~/.gitaiflow` from unintentionally changing the telemetry decision.

The consent history records the answer, gitaiflow version, and timestamp.

## Privacy Boundary

The strongest privacy boundary is the choice of AI provider:

```text
Local repository
      │
      ├── local-only processing ──→ Ollama / local compatible endpoint
      │
      └── external processing ────→ configured cloud AI provider
```

Even with redaction and telemetry disabled, a cloud AI provider still receives the diff and prompt necessary to generate the requested summary. Users should select a provider whose data-handling policy is appropriate for the repository being analyzed.

## Security Recommendations

1. Never commit `.env` files or API credentials.
2. Treat `change-summary/diff/` and generated JSON/Markdown artifacts as potentially sensitive.
3. Review redaction-sensitive diffs before sending proprietary or regulated code to a cloud provider.
4. Prefer a local provider when repository contents must remain inside the local environment.
5. Keep telemetry disabled when anonymous operational reporting is not desired.
6. Restrict filesystem access to repositories and generated artifacts according to the sensitivity of the source code.