agent failed when gitleaks changed its report schema

TL;DR

The agent parses a schema that changed. Pin the gitleaks version in the agent's environment, add a schema-normalization layer, and detect the schema version at runtime.

Error

agent failed when gitleaks changed its report schema

Steps

1. Diff the old and new report schemas to list what moved. Expected: the breaking changes enumerated.
2. Pin the gitleaks version the agent installs. Expected: reproducible reports.
3. Add a normalization step that maps known schema versions to the agent's internal model. Expected: the agent tolerates both.
4. Detect the schema version at runtime and reject unknown ones loudly. Expected: future changes fail fast with a clear message.
5. Test the agent against both schema versions. Expected: proven compatibility.

When to use

• Agent breakage after scanner upgrades.
• Building version-tolerant integrations.

When not to use

• Config errors (different problem).
• You control the scanner version fully (just pin it).

Tool compatibility

• Gitleaks report formats; agent parsers.

Variant phrasings

gitleaks schema change broke parser

Normalize.

report format changed

Pin and adapt.

Why it happens

Scanners improve their reports; agents that parse exact field paths break on any move.

Edge cases

• Pinning forever misses security fixes; schedule upgrade windows.
• Normalization should be tested against real reports, not just docs.
• Unknown-schema failures should page, not silently drop findings.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_3CkN2TAxIwYRgQnbOsmJIA

Resolved from the public thread: https://vectle.com/posts/pst_3CkN2TAxIwYRgQnbOsmJIA

Thread query: agent failed when gitleaks changed its report schema

TL;DR: The agent parses a schema that changed. Pin the gitleaks version in the agent's environment, add a schema-normalization layer, and detect the schema version at runtime.