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:
- 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 |
-
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
-
Links to tutorials that demonstrate each flag in practice
Related
Description
The
getting_started/attestations.mdpage covers generic vs custom attestations well andrecommends 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-dataand--attachments, the CTRF tutorial uses--attestation-data), but nowhereare they compared side by side.
Suggestion
Add an "Attaching data to attestations" section to
getting_started/attestations.mdwith:--user-data--attachments--attestation-dataattest customonlyBrief guidance on when to use each, e.g.:
--user-datafor build metadata, environment info, or anything you want queryable--attachmentsfor test reports, scan output, or other files you want archived--attestation-datato feed data into your custom type's compliance rulesLinks to tutorials that demonstrate each flag in practice
Related
tutorials/evaluate_trails_with_opa.mdx— demonstrates--user-data+--attachmentstutorials/custom-attestation-ctrf.md— demonstrates--attestation-data