Skip to content

Add documentation around gh attestation verify JSON output #10440

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
malancas wants to merge 3 commits into from
Closed

Add documentation around gh attestation verify JSON output #10440

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
bd7e814
docs around verificationResult output
malancas Feb 13, 2025
aae4032
Merge branch 'trunk' into gh-att-verify-output-docs
malancas Feb 13, 2025
4e691cc
Merge branch 'trunk' into gh-att-verify-output-docs
malancas Mar 14, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions pkg/cmd/attestation/verify/verify.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,6 +81,15 @@ func NewVerifyCmd(f *cmdutil.Factory, runF func(*Options) error) *cobra.Command
or %[1]s--cert-identity%[1]s flags to validate the signer workflow's identity.

For more policy verification options, see the other available flags.

When the %[1]s--format json%[1]s flag is included, the command will output
an array of JSON objects. Each object contains a verified attestation
bundle and another object called verificationResult. The verificationResult
object contains detailed information about the bundle's content and
fields used during the verification process. This includes:
- The attestation's signature
- The attestation's statement
- The attestation's predicate
Comment on lines +89 to +92
Copy link
Copy Markdown
Contributor

@jkylekelly jkylekelly Mar 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this a comprehensive list? And just checking, is this the right place to list what fields are used during the verification process? Maybe we could note what is verified under the "By default, the verify command will:" section, and then in the --json helper notes we can mention that details used for verification are within the verificationResult object.

Copy link
Copy Markdown
Contributor Author

@malancas malancas Mar 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It isn't an exhaustive list, it just includes a lists a few fields surfaced in the verificationResult object the user might find particularly useful. These could definitely be moved under a json helper notes section.

Copy link
Copy Markdown
Contributor

@jkylekelly jkylekelly Mar 25, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ah okay, it might be good to say "This includes useful fields, such as: " or similar. Just in case others assume it's exhaustive.

Copy link
Copy Markdown
Contributor

@phillmv phillmv Mar 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm going to take a stab at this tomorrow fwiw.

`, "`"),
Example: heredoc.Doc(`
# Verify an artifact linked with a repository
Expand Down
Loading