Documentation for the centralized tooling this repository provides to every
zircote/* repository: the attested-delivery workflows, reusable CI/CD
workflows, and shared automation.
The docs follow the Diátaxis framework — four kinds of documentation for four kinds of need:
| You want to... | Read |
|---|---|
| Learn the system hands-on | Tutorials |
| Get a specific task done | How-to guides |
| Look up exact inputs, outputs, and behavior | Reference |
| Understand why it works this way | Explanation |
- Your first attested release — build, sign, attest, and verify a container image end to end using the centralized workflows.
- Wire your first attested quality gate — run a CodeQL SAST gate and verify its signed, digest-bound verdict.
- Onboard a repo to attested delivery
- Onboard a repo to attested quality gates
- Enforce action SHA pinning
- Generate an SBOM and vulnerability scan
- Emit DORA deployment metrics
- Enforce admission of attested images (Kubernetes/Kyverno and pre-deploy gates)
For coding agents (Claude Code, Copilot, gh-aw), the attested-delivery skill packages all of the above — architecture, platform constraints, caller recipes with baked-in workflow templates, rollout checklist, and verification — as an executable, fully self-contained onboarding protocol for any org or repo.
- Reusable workflows — every centralized attested-delivery workflow: inputs, outputs, secrets, permissions.
- Quality-gate workflows — the SAST, SCA, Trivy, Scorecard, VEX, k6, ZAP, seam, and verify-gates workflows: role, key inputs, evidence, predicate type, signer.
- Attestation predicate definitions — the custom predicate types the quality gates sign: URI, body format, verdict rule, JSON Schema.
- Language CI, release, security, and docs workflows are summarized in CLAUDE.md and the repo README.
- Why attested delivery — the promotion invariant, the signing-isolation boundary, admission-time enforcement, and the change-record gate.
- Why attested quality gates — the verdict-as-attestation model, signer pinning, custom predicate types, and the "signed ≠ passed" caveat.
Plans are working project artifacts, not user documentation, and sit outside the Diátaxis quadrants:
- Presentations — the slide-deck generation system.
| Tool / component | Tutorial | How-to | Reference | Explanation |
|---|---|---|---|---|
build-attest.yml |
Yes | Yes | Yes | Yes |
sign-and-attest.yml |
Yes | Yes | Yes | Yes |
verify-attestation.yml |
Yes | Yes | Yes | Yes |
promote.yml / promote-prod.yml |
— | Yes | Yes | Yes |
sbom-and-scan.yml |
— | Yes | Yes | — |
dora-emit.yml |
— | Yes | Yes | Yes |
pin-check.yml |
— | Yes | Yes | — |
| Admission enforcement (Kyverno / pre-deploy gate) | — | Yes | — | Yes |
| Attested quality gates (SAST/SCA/Trivy/Scorecard/VEX/k6/ZAP) | Yes (SAST) | Yes | Yes | Yes |
Attestation seam (reusable-attest-scan.yml) |
Yes | Yes | Yes | Yes |