Release evidence artifacts are versioned JSON snapshots of gate evaluation results. Each artifact records which gates were checked, what they found, whether they passed or failed, and when the check ran. These files serve as auditable proof of release readiness and can be archived, diffed across releases, and analyzed for trends over time.
All evidence commands use the schemaVersion: "v1" contract, making evidence files stable inputs for downstream scripts and compliance workflows.
Evidence JSON structure An evidence file produced by cops release evidence generate has this top-level shape:
{ "schemaVersion" : "v1" , "project" : "my-service" , "generatedAt" : "2026-04-01T12:00:00.000Z" , "overall" : "pass" , "gateCount" : 3 , "results" : [ { "gateId" : "jira-stories" , "type" : "jira-stories-exist" , "severity" : "high" , "owner" : "" , "team" : "" , "ticket" : "" , "slaHours" : "" , "rawStatus" : "pass" , "status" : "pass" , "blocking" : false , "waived" : false , "waiverExpires" : "" , "details" : "42 stories found" }, { "gateId" : "release-branch" , "type" : "bitbucket-release-branch-exists" , "severity" : "high" , "rawStatus" : "pass" , "status" : "pass" , "blocking" : false , "waiverApplied" : false , "details" : "Release branch exists" }, { "gateId" : "bamboo-build" , "type" : "bamboo-latest-build-success" , "severity" : "high" , "rawStatus" : "warn" , "status" : "fail" , "blocking" : true , "waiverApplied" : false , "details" : "MYPROJ-PLAN-42 is FAILED" } ] }
Top-level fields Field Type Description schemaVersionstring Always "v1". projectstring Project ID from cops.project.json. generatedAtstring ISO 8601 timestamp when the evidence was generated. overallstring Aggregate result: pass, warn, or fail. gateCountnumber Number of gate results in results. resultsarray One entry per evaluated gate.
Per-gate result fields Field Type Description gateIdstring Gate ID from cops.project.json. typestring Gate type. severitystring low, medium, high, or critical.rawStatusstring Raw evaluation result: pass, warn, or fail. statusstring Effective status after policy: pass, warn, fail, or waived. blockingboolean true when this gate’s failure prevents the release.waiverAppliedboolean true when an active waiver suppressed a non-pass result.waiverReasonstring Waiver reason text, when waiverApplied is true. waiverExpiresstring ISO 8601 waiver expiry, when set. detailsstring Human-readable description of what the gate found. ownerstring Optional owner label from gate config. teamstring Optional team label from gate config. ticketstring Optional reference ticket from gate config. slaHoursnumber Optional SLA hours from gate config.
Generate → validate → archive workflow
Generate evidence
Run all enabled gates and write the evidence artifacts to disk. cops release evidence generate --project my-service --outDir output
This produces two files in output/:
release-evidence-my-service.json — the structured evidence artifactrelease-evidence-my-service.md — a Markdown table for human review The command exits with a non-zero code when any gate is blocking, so it can gate a CI pipeline step directly.
Validate the evidence contract
Confirm the JSON file conforms to the schemaVersion: "v1" contract before archiving. cops release evidence validate --file output/release-evidence-my-service.json --strict
With --strict, the validator also checks for unknown top-level and per-gate result keys, and enforces the low|medium|high|critical severity enum. Without --strict, only the required fields and types are checked.
Archive or hand off
Store the validated evidence file in your artifact repository, compliance storage, or CI artifact archive. The file is stable, self-describing, and human-readable. # Example: copy to a dated archive directory cp output/release-evidence-my-service.json \ archive/releases/2026-04-01/release-evidence-my-service.json
cops release evidence generate Evaluates all enabled gates for the project and writes JSON and Markdown evidence artifacts.
cops release evidence generate [--project < i d > ] [--outDir < di r > ]
Flags Flag Default Description --projectdefault project Project key from cops.project.json. --outDiroutputDirectory to write evidence files into. Created if it does not exist. --outputtableOutput format: table, json, or markdown. Controls the command summary, not the artifact format. --profileactive profile Named auth profile to use. --insecurefalseDisable TLS certificate validation.
Output files File Description release-evidence-<project>.jsonStructured evidence artifact (schemaVersion v1). release-evidence-<project>.mdMarkdown table for human review in pull requests or wikis.
For the default project (legacy release key), files are named release-evidence.json and release-evidence.md without a suffix.
with project flag
with json output summary
with insecure TLS
cops release evidence generate --project my-service --outDir output
cops release evidence validate Validates that an evidence JSON file conforms to the schemaVersion: "v1" contract. Accepts a single file or a directory of evidence files.
cops release evidence validate --file < pat h > [--strict] cops release evidence validate --dir < pat h > [--prefix < prefi x > ] [--strict]
Flags Flag Default Description --file— Path to a single evidence JSON file. Mutually exclusive with --dir. --dir— Directory containing evidence JSON files. Mutually exclusive with --file. --prefixrelease-evidenceFilename prefix filter when using --dir. --strictfalseEnable strict validation: checks unknown keys and enforces severity enums. --outputtableOutput format for the validation report.
What is validated Base validation (always applied):
schemaVersion must be "v1"generatedAt must be a valid ISO datetimeoverall must be pass, warn, or failresults must be an array; gateCount must equal results.lengthEach result must have gateId, type, severity, rawStatus, status, blocking, and details
rawStatus must be pass|warn|fail; status must be pass|warn|fail|waivedblocking must be a boolean
Strict validation (with --strict):
No unknown top-level keys beyond the allowed set
No unknown per-gate result keys
severity must be low|medium|high|critical
validate single file
validate with strict mode
validate all files in a directory
cops release evidence validate --file output/release-evidence-my-service.json
cops release evidence diff Compares two evidence files and reports changes in overall status, gate statuses, and blocking flags. Exits with a non-zero code when any differences are found.
cops release evidence diff --previous < pat h > --current < pat h >
Flags Flag Required Description --previousYes Path to the previous release-evidence JSON file. --currentYes Path to the current release-evidence JSON file. --outputNo Output format: table, json, or markdown.
Change kinds reported Kind Description overallThe top-level overall status changed between the two files. status_changeA gate’s effective status changed (e.g. pass → fail). blocking_changeA gate’s blocking flag changed. added_gateA gate result is present in the current file but was absent in the previous file. removed_gateA gate result is present in the previous file but absent in the current file.
cops release evidence diff \ --previous archive/2026-03-15/release-evidence-my-service.json \ --current output/release-evidence-my-service.json
Run cops release evidence diff in CI to catch regressions between release candidates. A non-zero exit code means something changed and should be reviewed.
cops release evidence trend Analyzes a directory of evidence JSON files, sorts them by generatedAt, and summarizes pass/warn/fail/waived/blocking counts per file. Useful for tracking release health over time or identifying recurring gate failures.
cops release evidence trend [--dir < di r > ] [--prefix < prefi x > ] [--limit < n > ]
Flags Flag Default Description --diroutputDirectory containing evidence JSON files to analyze. --prefixrelease-evidenceFilename prefix filter. --limit20Maximum number of files to analyze, taken from the most recent by generatedAt. --outputtableOutput format: table, json, or markdown.
The command exits based on the most recent evidence file in the set:
Non-zero (blocking) when the latest file has any blocking gate.
Warning exit code when the latest file has any warn or fail results.
Zero when the latest file is fully green.
# Analyze the last 10 evidence files in an archive directory cops release evidence trend \ --dir archive/releases \ --prefix release-evidence-my-service \ --limit 10 \ --output json
Files that cannot be parsed or have no generatedAt timestamp are silently skipped. Only valid evidence JSON files contribute to the trend output.
