Release evidence examples

This page shows practical release evidence layouts and CRA Evidence CLI commands. The examples are meant for CI/CD pipelines, but the same files can be uploaded manually from a workstation.

CRA Evidence does not require one specific build system. You can use GitHub Actions, GitLab CI, Azure DevOps, Jenkins, or another pipeline. What matters is that the evidence files are real release artifacts and that signed SBOM verification uses the signer identity and issuer from your signing system.

release-evidence/
  sbom.cdx.json
  sbom.cdx.json.sigstore.json
  provenance.intoto.jsonl
  risk-assessment.md
  threat-model.md
  eu-declaration-of-conformity.pdf
  vulnerability-disclosure-policy.md
  secure-update-process.md

Minimal SBOM upload and scan

craevidence upload-sbom \
  --product acme-router \
  --version 2.4.1 \
  --file release-evidence/sbom.cdx.json \
  --product-type software \
  --cra-role manufacturer \
  --environment production \
  --scan \
  --fail-on high

This uploads one SBOM, triggers a vulnerability scan, and fails the pipeline if high or critical vulnerabilities are found.

Signed SBOM verification

--sign creates a Sigstore bundle from the CI job's OIDC identity before upload. In GitHub Actions this requires permissions: id-token: write. For a strict release gate, set the signer policy once in CI:

export CRA_EVIDENCE_SIGNATURE_IDENTITY="https://github.com/acme/router/.github/workflows/release.yml@refs/heads/main"
export CRA_EVIDENCE_SIGNATURE_ISSUER="https://token.actions.githubusercontent.com"

Then sign, upload, verify, and fail the job if the pinned signer policy does not match:

craevidence upload-sbom \
  --product acme-router \
  --version 2.4.1 \
  --file release-evidence/sbom.cdx.json \
  --sign \
  --fail-untrusted \
  --scan \
  --fail-on high

For first setup, run once without --fail-untrusted to print the signer identity and issuer, then pin those values in CI.

For GitLab, Jenkins with an OIDC signer, Buildkite, CircleCI, GCP, or another signing system, keep the same environment variable names and change the values to the identity and issuer in your Sigstore certificate:

export CRA_EVIDENCE_SIGNATURE_IDENTITY="<signer identity from certificate>"
export CRA_EVIDENCE_SIGNATURE_ISSUER="<OIDC issuer from certificate>"

GitHub is only an example. CRA Evidence checks the identity and issuer you provide against the uploaded bundle; it does not assume GitHub.

Teams that already use Cosign can keep their existing signing step and use --signature-on. --signature-on expects the bundle next to the SBOM as <SBOM file>.sigstore.json.

If your bundle path is different, pass it explicitly:

craevidence upload-sbom \
  --product acme-router \
  --version 2.4.1 \
  --file release-evidence/sbom.cdx.json \
  --signature-bundle artifacts/acme-router-sbom.sigstore.json \
  --fail-untrusted

The CRA_EVIDENCE_SIGNATURE_IDENTITY and CRA_EVIDENCE_SIGNATURE_ISSUER environment variables still apply. You can override them per command with --signature-identity and --signature-issuer.

Required CRA documents

Upload documents with explicit --type values so CRA Evidence knows what each file represents.

craevidence upload-document \
  --product acme-router \
  --version 2.4.1 \
  --file release-evidence/risk-assessment.md \
  --type risk_assessment

craevidence upload-document \
  --product acme-router \
  --version 2.4.1 \
  --file release-evidence/eu-declaration-of-conformity.pdf \
  --type eu_declaration_of_conformity

craevidence upload-document \
  --product acme-router \
  --version 2.4.1 \
  --file release-evidence/vulnerability-disclosure-policy.md \
  --type vulnerability_policy

craevidence upload-document \
  --product acme-router \
  --version 2.4.1 \
  --file release-evidence/secure-update-process.md \
  --type update_mechanism_documentation

Common document type mappings:

For structured files that CRA Evidence can parse, add --require-structured-mapping when CI should fail unless the backend confirms that fields were mapped. Do not use that flag for normal PDFs or upload-only evidence.

Provenance attestation metadata

craevidence upload-attestation \
  --product acme-router \
  --version 2.4.1 \
  --file release-evidence/provenance.intoto.jsonl

This stores provenance metadata for the version. It is not shown as verified provenance unless CRA Evidence reports verification_status as valid.

GitHub artifact attestation JSONL and Cosign sign-blob bundles are different inputs. Use signed SBOM verification for the SBOM bundle. Use upload-attestation for provenance attestation metadata.

Readiness and export

craevidence status \
  --product acme-router \
  --version 2.4.1 \
  --fail-on high

craevidence export \
  --product acme-router \
  --version 2.4.1 \
  --format technical-file \
  -o acme-router-2.4.1-technical-file.zip

status --fail-on can fail CI when CRA readiness is incomplete or vulnerability thresholds are exceeded. export downloads the stored technical file bundle for review, audit, or customer delivery.