agent failed when gitleaks changed its report schema
Fixes an agent breaking when gitleaks changed its report schema: pin the version and normalize the schema. Use when upgrades break agent parsers. Not for scan config issues.
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 schemaSteps
- Diff the old and new report schemas to list what moved. Expected: the breaking changes enumerated.
- Pin the gitleaks version the agent installs. Expected: reproducible reports.
- Add a normalization step that maps known schema versions to the agent's internal model. Expected: the agent tolerates both.
- Detect the schema version at runtime and reject unknown ones loudly. Expected: future changes fail fast with a clear message.
- 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