Get started
Core concepts
One vocabulary runs through the whole ecosystem: an evidence record that escalates trust from an in-loop log to a signed, audit-grade attestation.
The evidence record
Everything starts with one shape — the evidence record, defined once in github.com/zegit-zoo/common/evidence (schema version 0.1) and emitted by every producer (mongoose, the plugins, zegit). There is a single record shape across all trust levels; only the envelope grows.
Each record binds itself to git state — a commit_sha and tree_sha (or, outside a repo, a dirty flag plus a diff hash). It carries the producer, an actor (a human or an agent harness + model), the steps that ran, optional reviewers, an optional policy decision, and the envelope.
| Field | Meaning |
|---|---|
producer | What emitted the record — mongoose, agent-guardrails, or zegit. |
actor | Who acted — kind: human or agent (with harness + model). |
subject | The git binding: commit_sha, tree_sha, dirty, diff_sha256, run_id. |
steps[] | What ran — each with a kind (job/agent/skill/check/review) and status. |
policy_ref | The policy the record was produced under (a digest, optionally a contract hash). |
decision | The policy verdict — nil until evaluated. |
envelope | The trust level — see below. |
Envelopes: the trust ladder
The same record climbs three trust levels. This is the spine of the whole platform — the upgrade from log to proof is just running the next tool over the same record.
| Level | What it is | Set by |
|---|---|---|
| unsigned | An in-loop local record. No signature. | mongoose / the plugins |
| validated | A policy Decision has been stamped on; still unsigned. | zg evidence evaluate --stamp |
| signed | DSSE-wrapped and signed; audit-grade. | zg validate / zg evidence sign |
AoV — Attestation of Validation
An AoV is a signed (envelope-level signed) evidence record, produced by zg validate on success. It proves that a passkey-authenticated identity asserts this validation ran under this policy, for a specific commit and tree. It is stored in Git itself, as a blob at refs/zegit/aov/<commit_sha>, and pushed alongside your commits by the zg init pre-push hook.
What a v1 AoV does and doesn't prove
An AoV is non-repudiable and audit-grade: it binds an identity, a commit, a tree, and a policy. It does not yet prove the validation actually executed as claimed — that needs attested runner images (a post-MVP tier). The platform is deliberately honest about this — see how attested runners will close the gap below.
Short-lived certs expire
Verification checks the signer certificate at the current time, so an AoV becomes unverifiable once its short-lived cert expires. Re-run zg validate to re-sign.
How attested runners will close the execution gap
A v1 AoV proves that "a passkey-authenticated identity asserts this validation ran under this policy." That is non-repudiable and audit-grade, but it does not prove the validation actually executed as claimed. The gateway verifies the signature and the commit binding, yet has no evidence the pipeline ran or passed — it gives you authenticity of the attester, not integrity of the attested process. A developer can point .zegit/config.yaml at a check that trivially passes and still produce a valid AoV. That is the honest limit of a software-attested model.
The planned fix is to bind the AoV to a trusted builder, so the decision comes from something the committer cannot trivially forge. ZeGit's build runner images — distributed OCI images, pinned by digest — are the vehicle. This is roadmap, not shipped: Tier 2 "Verified" images land in Phase 2 and Tier 3 in Phase 3. What follows is how it is designed to work, not behavior available today.
- Today (v1, shipped): the Control Plane issues a short-lived signing certificate after a WebAuthn passkey ceremony — subject identity is the enrolled passkey identity, lifetime is the role's auth-timeout (8h developer, 1h maintainer, minutes for owner).
zg validatesigns the AoV with that cert's key — analogous to sigstore keyless, but passkey-bound rather than OIDC. - Tier 2 (Phase 2, planned): the same validation runs inside a Verified build runner image — a signed image plus digest, an SBOM, a stricter hardening baseline, a formal patch SLA, and reproducible build inputs (pinned dependencies).
- Runner-signed AoVs: the AoV is then signed by the attested runner identity rather than the developer identity. This is the named mechanism that closes the v1 gap — the decision originates from a known-good, digest-pinned runner image instead of from whoever holds the developer signing key.
- Policy enforcement: in the design, the org-repo baseline gains a hook to pin approved runner images — the mechanism a verifier would use to require that protected refs carry a runner-signed AoV from an approved digest. This hook is not specified or built in v1.
- Tier 3 (Phase 3, optional): everything in Tier 2 plus TPM-backed runner attestation and full hermetic builds, and a conformity-assessment path (third-party or notified-body aligned) producing CRA-suitable technical documentation.
| Aspect | Today — v1 AoV | With attested runners |
|---|---|---|
| What the AoV proves | A passkey-authenticated identity asserts validation ran under this policy — non-repudiable, audit-grade. | A digest-pinned, approved runner produced the decision — integrity of the process, not just authenticity of the attester. |
| Who signs the AoV | The developer, via a short-lived passkey-bound cert. | The attested runner identity (a runner-signed AoV). |
| Forgeability | A developer can hand-craft an ALLOW AoV without running the real checks. | The decision is bound to a trusted builder the committer cannot trivially forge. |
| Build runner image | Local or user-provisioned; minimal build provenance. | Tier 2 Verified OCI image (signed, SBOM, hardened, patch SLA, pinned inputs); Tier 3 adds hermetic builds + TPM attestation. |
| Availability | shipped the MVP trust model. | roadmap Tier 2 in Phase 2, Tier 3 in Phase 3. |
Attested runners are roadmap, not shipped
Runner-signed AoVs are a post-MVP upgrade. Tier 2 Verified build runner images are a Phase 2 item; Tier 3 notified-body assessed images and TPM-backed runner attestation are Phase 3. Today every AoV is developer-signed and self-attested: it proves who asserted the validation, not that the pipeline executed as claimed. The exact runner identity, its certificate, and the verifier-side checks are sketched in the design — not yet specified or built.
Until attested runners ship, the AoV stays a passkey-bound assertion at the heart of the envelope model — honest about proving who vouched for a validation, with runner-signed AoVs the planned step that turns that assertion into proof the validation actually ran.
DSSE & in-toto
A signed AoV is a DSSE envelope wrapping an in-toto Statement whose predicate is the evidence record. DSSE/in-toto compatibility is a day-one requirement, so the signatures interoperate with the wider supply-chain tooling ecosystem.
The policy engine
The policy engine evaluates a record and returns one of three decisions. The mapping to enforcement is fixed:
| Decision | Meaning | Enforcement |
|---|---|---|
| ALLOW | All gates passed; policy permits autonomous delivery. | Gateway accepts the push. |
| REQUIRE_REVIEW | A reviewer was non-passing, or risk policy requires review. | Routed to a Tag Request / approval. |
| BLOCK | A required step failed, evidence is stale, or risk blocks. | Gateway rejects with a ZG_ERR_* code. |
Evaluation is first-match-wins: an invalid required task contract blocks; stale evidence (the record's commit/tree ≠ the pushed commit/tree) blocks; a missing required step blocks; a non-passing reviewer requires review; otherwise the risk policy decides. See the exact ordering and the matching error codes.
Know · work · prove
The three tools map to a mnemonic that also describes the data flow:
- meerkat knows — agents query a curated knowledge base before they act.
- mongoose works — the agent does the work and emits an unsigned record per run, bound to git state.
- zegit proves — that same record is evaluated, signed into an AoV, and gated at the release boundary.
mongoose only ever emits unsigned records; the editor plugins do the same. Signing is always zegit's job — which is why "the upgrade from log to proof is just installing zegit."
Authoritative reference, generated from the component repos. Spot something stale? Tell us.