Skip to content
Codevidence Docs

Core Concepts

Evidence records & provenance

Every control Codevidence tracks produces evidence records — a Declared record from the annotation, and a Verified record for every test assertion. Each is a structured JSON document tying a control to the exact artifact or test, and the build it came from.

Every record has two halves

What the control is — its id and (for Declared) the framework criterion, taken from the annotation. Where it came from — the provenance: which commit, which build, when. The provenance half is what turns “a developer said so” into something an auditor can check independently.

The provenance chain

  • Artifact hash (artifact.sha256, Declared) — a SHA-256 of the exact compiled class. If the code changes, the hash changes.
  • Commit (commit) — auto-detected from CI environment variables, then git rev-parse HEAD. null if neither resolves.
  • Commit source (commitSource, Declared) — ci-env:<VAR>, git-rev-parse, manual-override, or unavailable. You can always tell how the commit was determined.
  • Build (buildId) — the CI build identifier, or a generated local-… id.
  • Timestamp — when the record was generated.

Provenance is never fabricated. When a commit can’t be resolved, the record says so (commit: null, commitSource: "unavailable") and the build logs a warning — an explicit gap an auditor can see, rather than a placeholder that looks real.

Where it lives

Records are written as JSON under your build output — target/codevidence/ for Declared, target/codevidence/verified/ for Verified (or build/… under Gradle). They’re portable, diffable files you own.

When you set an API key, the plugin also POSTs each record to the Codevidence evidence API (app.codevidence.com/api/v1/evidence, or a self-hosted endpoint), where your team reviews controls against the code in the tenant portal. Live per-tenant evidence history is rolling out; the portal control views are available in preview.

What provenance is not

Provenance answers “did this come from this exact build?”, not “does the control work correctly?” — different questions. See the evidence model for how Declared, Verified, and Observed each answer a progressively stronger version of the second one.

Schema references