Skip to content

Add data flags comparison to getting started attestations page #171

@dangrondahl

Description

@dangrondahl

Description

The getting_started/attestations.md page covers generic vs custom attestations well and
recommends custom over generic, but it never explains the three data flags available on
attest commands: --user-data, --attachments, and --attestation-data.

Users encountering these flags for the first time have no conceptual guide to understand
when to use which. The tutorials demonstrate them individually (e.g., the OPA tutorial uses
--user-data and --attachments, the CTRF tutorial uses --attestation-data), but nowhere
are they compared side by side.

Suggestion

Add an "Attaching data to attestations" section to getting_started/attestations.md with:

  1. A comparison table:
Flag Available on Purpose
--user-data all attest commands Structured JSON metadata stored and visible alongside the attestation in the UI
--attachments all attest commands Files/directories archived in the evidence vault as compressed downloads
--attestation-data attest custom only JSON payload evaluated by the custom type's jq expression to determine compliance
  1. Brief guidance on when to use each, e.g.:

    • Use --user-data for build metadata, environment info, or anything you want queryable
    • Use --attachments for test reports, scan output, or other files you want archived
    • Use --attestation-data to feed data into your custom type's compliance rules
  2. Links to tutorials that demonstrate each flag in practice

Related

Metadata

Metadata

Assignees

Labels

contentWriting, adding, or updating doc pagesenhancementNew feature or request

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions