From 5619251faa9cc157eb3c46028487c39f080b4d20 Mon Sep 17 00:00:00 2001 From: Phill MV Date: Mon, 29 Apr 2024 16:24:49 -0400 Subject: [PATCH] Tweaked gh attestation help strings to generate nicer cli manual site. --- pkg/cmd/attestation/attestation.go | 4 ++-- pkg/cmd/attestation/download/download.go | 29 ++++++++++++------------ pkg/cmd/attestation/inspect/inspect.go | 2 +- pkg/cmd/attestation/verify/verify.go | 25 ++++++++++---------- 4 files changed, 29 insertions(+), 31 deletions(-) diff --git a/pkg/cmd/attestation/attestation.go b/pkg/cmd/attestation/attestation.go index 5b358a6bf..bfc0c3550 100644 --- a/pkg/cmd/attestation/attestation.go +++ b/pkg/cmd/attestation/attestation.go @@ -17,9 +17,9 @@ func NewCmdAttestation(f *cmdutil.Factory) *cobra.Command { Short: "Work with artifact attestations", Aliases: []string{"at"}, Long: heredoc.Doc(` - # NOTE: This feature is currently in beta, and subject to change. +### NOTE: This feature is currently in beta, and subject to change. - Download and verify artifact attestations. +Download and verify artifact attestations. `), } diff --git a/pkg/cmd/attestation/download/download.go b/pkg/cmd/attestation/download/download.go index fd6aa5f01..3af3b6200 100644 --- a/pkg/cmd/attestation/download/download.go +++ b/pkg/cmd/attestation/download/download.go @@ -21,41 +21,40 @@ func NewDownloadCmd(f *cmdutil.Factory, runF func(*Options) error) *cobra.Comman downloadCmd := &cobra.Command{ Use: "download [ | oci://] [--owner | --repo]", Args: cmdutil.ExactArgs(1, "must specify file path or container image URI, as well as one of --owner or --repo"), - Short: "Download an artifact's Sigstore bundle(s) for offline use", + Short: "Download an artifact's attestations for offline use", Long: heredoc.Docf(` - # NOTE: This feature is currently in beta, and subject to change. + ### NOTE: This feature is currently in beta, and subject to change. - Download an artifact's attestations, aka Sigstore bundle(s), for offline use. + Download attestations associated with an artifact for offline use. The command requires either: * a file path to an artifact, or * a container image URI (e.g. %[1]soci://%[1]s) - - (Note that if you provide an OCI URL, you must already be authenticated with - its container registry.) + * (note that if you provide an OCI URL, you must already be authenticated with + its container registry) In addition, the command requires either: - * the %[1]s--owner%[1]s flag (e.g. --owner github), or * the %[1]s--repo%[1]s flag (e.g. --repo github/example). - - The %[1]s--owner%[1]s flag value must match the name of the GitHub organization - that the artifact is associated with. + * the %[1]s--owner%[1]s flag (e.g. --owner github), or The %[1]s--repo%[1]s flag value must match the name of the GitHub repository - that the artifact is associated with. + that the artifact is linked with. - Any associated Sigstore bundle(s) will be written to a file in the + The %[1]s--owner%[1]s flag value must match the name of the GitHub organization + that the artifact's linked repository belongs to. + + Any associated bundle(s) will be written to a file in the current directory named after the artifact's digest. For example, if the digest is "sha256:1234", the file will be named "sha256:1234.jsonl". `, "`"), Example: heredoc.Doc(` - # Download Sigstore bundle(s) for a local artifact associated with a GitHub organization + # Download attestations for a local artifact linked with an organization $ gh attestation download example.bin -o github - # Download Sigstore bundle(s) for a local artifact associated with a GitHub repository + # Download attestations for a local artifact linked with a repository $ gh attestation download example.bin -R github/example - # Download Sigstore bundle(s) for an OCI image associated with a GitHub organization + # Download attestations for an OCI image linked with an organization $ gh attestation download oci://example.com/foo/bar:latest -o github `), // PreRunE is used to validate flags before the command is run diff --git a/pkg/cmd/attestation/inspect/inspect.go b/pkg/cmd/attestation/inspect/inspect.go index 36682fac5..9bbd23682 100644 --- a/pkg/cmd/attestation/inspect/inspect.go +++ b/pkg/cmd/attestation/inspect/inspect.go @@ -23,7 +23,7 @@ func NewInspectCmd(f *cmdutil.Factory, runF func(*Options) error) *cobra.Command Hidden: true, Short: "Inspect a sigstore bundle", Long: heredoc.Docf(` - # NOTE: This feature is currently in beta, and subject to change. + ### NOTE: This feature is currently in beta, and subject to change. Inspect a downloaded Sigstore bundle for a given artifact. diff --git a/pkg/cmd/attestation/verify/verify.go b/pkg/cmd/attestation/verify/verify.go index 1b3a6b511..08322771d 100644 --- a/pkg/cmd/attestation/verify/verify.go +++ b/pkg/cmd/attestation/verify/verify.go @@ -25,7 +25,7 @@ func NewVerifyCmd(f *cmdutil.Factory, runF func(*Options) error) *cobra.Command Args: cmdutil.ExactArgs(1, "must specify file path or container image URI, as well as one of --owner or --repo"), Short: "Verify an artifact's integrity using attestations", Long: heredoc.Docf(` - # NOTE: This feature is currently in beta, and subject to change. + ### NOTE: This feature is currently in beta, and subject to change. Verify the integrity and provenance of an artifact using its associated cryptographically signed attestations. @@ -33,23 +33,22 @@ func NewVerifyCmd(f *cmdutil.Factory, runF func(*Options) error) *cobra.Command The command requires either: * a file path to an artifact, or * a container image URI (e.g. %[1]soci://%[1]s) - - (Note that if you provide an OCI URL, you must already be authenticated with - its container registry.) + * (note that if you provide an OCI URL, you must already be authenticated with + its container registry) In addition, the command requires either: - * the %[1]s--owner%[1]s flag (e.g. --owner github), or * the %[1]s--repo%[1]s flag (e.g. --repo github/example). - - The %[1]s--owner%[1]s flag value must match the name of the GitHub organization - that the artifact is associated with. + * the %[1]s--owner%[1]s flag (e.g. --owner github), or The %[1]s--repo%[1]s flag value must match the name of the GitHub repository - that the artifact is associated with. + that the artifact is linked with. + + The %[1]s--owner%[1]s flag value must match the name of the GitHub organization + that the artifact's linked repository belongs to. By default, the verify command will attempt to fetch attestations associated with the provided artifact from the GitHub API. If you would prefer to verify - the artifact using attestations stored on disk (i.e. from the download command), + the artifact using attestations stored on disk (c.f. the %[1]sdownload%[1]s command), provide a path to the %[1]s--bundle%[1]s flag. To see the full results that are generated upon successful verification, i.e. @@ -58,10 +57,10 @@ func NewVerifyCmd(f *cmdutil.Factory, runF func(*Options) error) *cobra.Command For more policy verification options, see the other available flags. `, "`"), Example: heredoc.Doc(` - # Verify a local artifact associated with a repository + # Verify a local artifact linked with a repository $ gh attestation verify example.bin --repo github/example - # Verify a local artifact associated with an organization + # Verify a local artifact linked with an organization $ gh attestation verify example.bin --owner github # Verify an OCI image using locally stored attestations @@ -136,7 +135,7 @@ func NewVerifyCmd(f *cmdutil.Factory, runF func(*Options) error) *cobra.Command verifyCmd.Flags().IntVarP(&opts.Limit, "limit", "L", api.DefaultLimit, "Maximum number of attestations to fetch") cmdutil.AddFormatFlags(verifyCmd, &opts.exporter) // policy enforcement flags - verifyCmd.Flags().BoolVarP(&opts.DenySelfHostedRunner, "deny-self-hosted-runners", "", false, "Fail verification for attestations generated on self-hosted runners.") + verifyCmd.Flags().BoolVarP(&opts.DenySelfHostedRunner, "deny-self-hosted-runners", "", false, "Fail verification for attestations generated on self-hosted runners") verifyCmd.Flags().StringVarP(&opts.SAN, "cert-identity", "", "", "Enforce that the certificate's subject alternative name matches the provided value exactly") verifyCmd.Flags().StringVarP(&opts.SANRegex, "cert-identity-regex", "i", "", "Enforce that the certificate's subject alternative name matches the provided regex") verifyCmd.MarkFlagsMutuallyExclusive("cert-identity", "cert-identity-regex")