Baselines and .gitleaksignore

Two related mechanisms that suppress specific findings (not entire rules or paths). Use them when an allowlist would be too broad.

.gitleaksignore

A newline-delimited file of fingerprints. Loaded via Detector.AddGitleaksIgnore (detect/detect.go).

A fingerprint has one of two shapes (depending on whether the finding came from git history or the working tree):

Form	Format	Example
Global	file:rule-id:start-line	cmd/generate/config/rules/sidekiq.go:sidekiq-secret:23
Commit	commit:file:rule-id:start-line	cd5226711335c68be1e720b318b7bc3135a30eb2:cmd/generate/config/rules/sidekiq.go:sidekiq-secret:23

AddGitleaksIgnore reads line by line, trims whitespace, skips comments (#) and empty lines, and normalizes path separators (\ → /) for cross-platform compatibility. The fingerprint set is stored as a map[string]struct{} for O(1) lookup.

Detector.AddFinding checks both fingerprints (global and commit) against the loaded ignore set before appending. If either matches, the finding is dropped with a skipping finding: global fingerprint (or ... fingerprint) trace log.

The repo's own .gitleaksignore is 944 lines — almost entirely fingerprints for testdata files that contain intentional fake secrets.

Resolution path for .gitleaksignore

The --gitleaks-ignore-path flag (default .) determines where Gitleaks looks. The detector checks (in cmd/root.go's Detector(...)):

1. The path itself, if it's a file.
2. <gitleaksIgnorePath>/.gitleaksignore, if that exists.
3. <source>/.gitleaksignore, if scanning a directory.

All three locations are consulted and merged.

Baselines

A baseline is a previously generated JSON report passed via --baseline-path. Findings present in the baseline are filtered out, so only new findings are reported.

Workflow:

# 1. Generate a baseline of current findings
gitleaks git --report-path baseline.json -r baseline.json

# 2. Run later with the baseline applied
gitleaks git --baseline-path baseline.json --report-path findings.json

The baseline is just a JSON report — any prior --report-format=json output works.

Loading

detect.LoadBaseline (detect/baseline.go) reads the file and json.Unmarshals into []report.Finding. It rejects non-JSON formats with "the format of the file %s is not supported".

Detector.AddBaseline(path, source) then:

1. Computes the baseline path relative to source (so it can be excluded from the scan via Config.Path / baselinePath checks in DetectContext).
2. Stores the loaded findings on Detector.baseline.
3. Stores the relative path on Detector.baselinePath.

Equality check

detect.IsNew(finding, redact, baseline) (detect/baseline.go) implements the "is this finding already in the baseline?" check. The author chose explicit field-by-field comparisons over reflect.DeepEqual for performance; the trade-off is documented:

// Explicitly testing each property as it gives significantly better performance in comparison to cmp.Equal().
// Drawback is that the code requires maintenance if/when the Finding struct changes

The compared fields are: RuleID, Description, StartLine, EndLine, StartColumn, EndColumn, Match, Secret (if redact is 0), File, Commit, Author, Email, Date, Message, Entropy. Fingerprint is deliberately excluded so that fingerprint-format changes don't invalidate baselines.

Filtering

Detector.AddFinding calls IsNew after the .gitleaksignore check:

if d.baseline != nil && !IsNew(finding, d.Redact, d.baseline) {
    logger.Debug().Str("fingerprint", finding.Fingerprint).Msgf("skipping finding: baseline")
    return
}

If the baseline is non-nil and the finding matches a baseline entry, it's silently dropped.

When to use which

Tool	Use when
Allowlist	A pattern produces false positives systematically (test fixtures, example values)
gitleaks:allow inline marker	A single line is intentionally a "leak" you can annotate at the source
.gitleaksignore	A specific finding (file + rule + line) is acknowledged but you can't change the source
Baseline	You're starting Gitleaks on an old codebase with hundreds of findings and only want new ones to fail CI

.gitleaksignore is durable across rule rewrites because it's keyed on file/line/rule — but if a file is renamed, the fingerprint moves. Baselines are one-shot snapshots that can capture commit-level fingerprints.

Related

• Allowlists — pattern-based suppression
• systems/detect — Detector.AddFinding is where both filters fire