Skip to main content
The cops release evidence commands produce and inspect machine-readable release evidence artifacts. Evidence files record gate evaluation results in a versioned JSON schema (v1) and an accompanying Markdown report. They are designed to be stored as release artifacts and compared across releases.

cops release evidence generate

Evaluate all enabled gates from cops.project.json and write a release-evidence.json and release-evidence.md to the output directory.

​
Usage

cops release evidence generate [flags]

​
Flags

​
--project
string
Project key from cops.project.json. Defaults to defaultProject or the top-level release block.
​
--outDir
string
default:"output"
Directory to write the generated evidence artifacts. Created if it does not exist.
​
--output
string
default:"table"
Output format for the command summary: table, json, or markdown.
​
--insecure
boolean
default:"false"
Disable TLS certificate validation. Use only with self-signed certificates in trusted networks.
​
--profile
string
Override the active config profile.

​
Output columns

artifact, path, overallTwo rows are written per run — one for the JSON artifact and one for the Markdown report.

​
Evidence file schema (v1)

{
  "schemaVersion": "v1",
  "project": "my-service",
  "generatedAt": "2026-03-19T10:00:00.000Z",
  "overall": "pass",
  "gateCount": 3,
  "results": [
    {
      "gateId": "bamboo-build-check",
      "type": "bamboo-latest-build-success",
      "severity": "high",
      "rawStatus": "pass",
      "status": "pass",
      "blocking": false,
      "details": "PROJ-PLAN-42 is successful"
    }
  ]
}
The overall field is pass, warn, or fail:
  • fail — at least one blocking gate failed
  • warn — at least one gate is warn or waived, no blocking failures
  • pass — all gates passed

​
Exit codes

CodeMeaning
0All gates passed (overall: pass)
20At least one blocking gate failed (overall: fail)
10At least one gate warned or was waived (overall: warn)

​
Examples

cops release evidence generate

artifact  path                              overall
────────  ────────────────────────────────  ───────
json      /workspace/output/release-evidence.json  pass
markdown  /workspace/output/release-evidence.md    pass
Validate one or more release evidence JSON files against the v1 schema contract. Use --strict to enforce allowed keys and enum values.

​
Usage

cops release evidence validate --file <path> [flags]
cops release evidence validate --dir <directory> [flags]

​
Flags

​
--file
string
Path to a single evidence JSON file to validate. Provide either --file or --dir.
​
--dir
string
Directory containing evidence JSON files. Validates all files matching the --prefix filter.
​
--prefix
string
default:"release-evidence"
Filename prefix filter when using --dir.
​
--strict
boolean
default:"false"
Enable strict validation: enforces allowed top-level and result keys, and validates severity against low|medium|high|critical.
​
--output
string
default:"table"
Output format: table, json, or markdown.

​
Output columns

file, status, details

​
Exit codes

CodeMeaning
0All files passed validation
20One or more files failed validation

​
Validation rules (v1)

  • schemaVersion must be v1
  • generatedAt must be a valid ISO datetime
  • overall must be pass, warn, or fail
  • results must be an array
  • gateCount must equal results.length
  • Each result must have gateId, type, severity, rawStatus (pass|warn|fail), status (pass|warn|fail|waived), blocking (boolean), and details
In strict mode, unknown top-level keys and unknown result keys are also reported as errors.

​
Examples

cops release evidence validate --file output/release-evidence.json

file                    status  details
──────────────────────  ──────  ───────────────────────────
release-evidence.json   pass    valid v1 evidence contract
Compare two release evidence JSON artifacts. Reports added gates, removed gates, status changes, and blocking flag changes between a previous and current evidence file.

​
Usage

cops release evidence diff --previous <path> --current <path> [flags]

​
Flags

​
--previous
string
required
Path to the previous release evidence JSON file.
​
--current
string
required
Path to the current release evidence JSON file.
​
--output
string
default:"table"
Output format: table, json, or markdown.

​
Output columns

kind, gateId, previous, current, details
ColumnDescription
kindChange type: overall, status_change, blocking_change, added_gate, removed_gate
gateIdGate identifier (or - for overall changes)
previousPrevious value
currentCurrent value
detailsHuman-readable description of the change

​
Exit codes

CodeMeaning
0No differences found
10One or more differences detected

​
Examples

cops release evidence diff --previous artifacts/prev/release-evidence.json --current artifacts/current/release-evidence.json

kind          gateId             previous  current  details
────────────  ─────────────────  ────────  ───────  ────────────────────────
status_change bamboo-build-check  warn     pass     Gate status changed
Analyze gate status trend across multiple release evidence JSON files in a directory. Files are sorted by generatedAt and the most recent --limit files are analyzed.

​
Usage

cops release evidence trend [flags]

​
Flags

​
--dir
string
default:"output"
Directory containing evidence JSON files to analyze.
​
--prefix
string
default:"release-evidence"
Filename prefix filter. Only files starting with this prefix are included.
​
--limit
number
default:"20"
Maximum number of files to analyze (most recent by generatedAt).
​
--output
string
default:"table"
Output format: table, json, or markdown.

​
Output columns

file, generatedAt, overall, gates, pass, warn, fail, waived, blockingEach row represents one evidence file. Rows are ordered oldest to newest.

​
Exit codes

CodeMeaning
0Most recent evidence has no blocking gates and no warn/fail
20Most recent evidence has one or more blocking gates
10Most recent evidence has warn or fail gates (no blocking)

​
Examples

cops release evidence trend

file                    generatedAt           overall  gates  pass  warn  fail  waived  blocking
──────────────────────  ────────────────────  ───────  ─────  ────  ────  ────  ──────  ────────
release-evidence.json   2026-03-17T08:00:00Z  warn     5      4     1     0     0       0
release-evidence.json   2026-03-18T08:00:00Z  pass     5      5     0     0     0       0
release-evidence.json   2026-03-19T08:00:00Z  pass     5      5     0     0     0       0
Store evidence files from each release cycle in a shared directory to build a history you can trend over time. Include the release date or version in the filename (or subdirectory) to distinguish runs.

cops release check

Run release gates and view gate evaluation details.

cops release summary

Cross-product release readiness summary.

Build docs developers (and LLMs) love

Get started for freeTalk to us