# Gitleaks allowlist patterns

## Version syntax

| Version | Allowlist syntax |
|---|---|
| v8.24.2 and earlier | `[allowlist]` (singular table) |
| v8.25.0 and later | `[[allowlists]]` (array of tables) |

**Critical**: using the wrong syntax produces no error but the allowlist silently does nothing. Always check `gitleaks version` first.

## v8.24.2 syntax (this repo uses 8.24.2)

### Suppress by path regex

Use for files that can never contain real secrets (research notes, terminal captures, test fixtures, generated docs).

```toml
[allowlist]
description = "research notes and terminal captures"
paths = [
  '''docs/research/.*''',
  '''tests/fixtures/.*''',
]
```

### Suppress by stopword

Use for placeholder values that match secret patterns but are clearly not real.

```toml
[allowlist]
description = "placeholder values"
stopwords = ["example", "placeholder", "changeme", "your-api-key-here"]
```

### Disable a default rule entirely

Use only when a rule has no value for this repo and produces pervasive false positives.

```toml
[extend]
useDefault = true
disabledRules = ["generic-api-key"]
```

## v8.25.0+ syntax (for reference)

```toml
[[allowlists]]
description = "research notes"
paths = ['''docs/research/.*''']

[[allowlists]]
description = "placeholder values"
stopwords = ["example", "placeholder"]
```

## .gitleaksignore (fingerprint-based — last resort)

```
# Format: <fingerprint>:<line-number>
# Generated by: gitleaks git -v --report-format json | jq -r '.[] | "\(.Fingerprint):\(.StartLine)"'
abc123def456:42
```

Avoid this approach: fingerprints embed line numbers. Any edit to the file shifts line numbers and invalidates the entry, re-surfacing the false positive.

## Verification after any change

```bash
# Scan current files
gitleaks dir -v .

# Scan with debug output to see which allowlists fired
gitleaks dir --log-level debug .

# Scan commit history
gitleaks git -v

# Scan only staged changes (what the pre-commit hook runs)
gitleaks git --staged --redact -v
```