From 0740c00f0aa3e8bc3492df2ae90cde90da49cdd8 Mon Sep 17 00:00:00 2001 From: Andy Feller Date: Mon, 29 Apr 2024 12:46:01 -0400 Subject: [PATCH] Add beta designation on attestation command set With the `gh attestation` command set going into public beta, users should be reminded the feature is in beta and subject to change. Both the short and long help usage are updated for individual command `--help` as well as `gh reference`. --- pkg/cmd/attestation/attestation.go | 9 +++++++-- pkg/cmd/attestation/download/download.go | 4 +++- pkg/cmd/attestation/inspect/inspect.go | 8 +++++--- pkg/cmd/attestation/tufrootverify/tufrootverify.go | 10 ++++++---- pkg/cmd/attestation/verify/verify.go | 4 +++- 5 files changed, 24 insertions(+), 11 deletions(-) diff --git a/pkg/cmd/attestation/attestation.go b/pkg/cmd/attestation/attestation.go index 75de9eca7..1283f4732 100644 --- a/pkg/cmd/attestation/attestation.go +++ b/pkg/cmd/attestation/attestation.go @@ -1,6 +1,7 @@ package attestation import ( + "github.com/MakeNowJust/heredoc" "github.com/cli/cli/v2/pkg/cmd/attestation/download" "github.com/cli/cli/v2/pkg/cmd/attestation/inspect" "github.com/cli/cli/v2/pkg/cmd/attestation/tufrootverify" @@ -13,9 +14,13 @@ import ( func NewCmdAttestation(f *cmdutil.Factory) *cobra.Command { root := &cobra.Command{ Use: "attestation [subcommand]", - Short: "Work with artifact attestations", + Short: "(BETA) Work with artifact attestations", Aliases: []string{"at"}, - Long: "Download and verify artifact attestations.", + Long: heredoc.Doc(` + # BETA: Feature subject to change + + Download and verify artifact attestations. + `), } root.AddCommand(download.NewDownloadCmd(f, nil)) diff --git a/pkg/cmd/attestation/download/download.go b/pkg/cmd/attestation/download/download.go index 162f36e72..a287edefd 100644 --- a/pkg/cmd/attestation/download/download.go +++ b/pkg/cmd/attestation/download/download.go @@ -21,8 +21,10 @@ 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: "(BETA) Download an artifact's Sigstore bundle(s) for offline use", Long: heredoc.Docf(` + # BETA: Feature subject to change + Download an artifact's attestations, aka Sigstore bundle(s), for offline use. The command requires either: diff --git a/pkg/cmd/attestation/inspect/inspect.go b/pkg/cmd/attestation/inspect/inspect.go index abc5d7665..fe3b240af 100644 --- a/pkg/cmd/attestation/inspect/inspect.go +++ b/pkg/cmd/attestation/inspect/inspect.go @@ -21,10 +21,12 @@ func NewInspectCmd(f *cmdutil.Factory, runF func(*Options) error) *cobra.Command Use: "inspect [ | oci://] --bundle ", Args: cmdutil.ExactArgs(1, "must specify file path or container image URI, as well --bundle"), Hidden: true, - Short: "Inspect a sigstore bundle", + Short: "(BETA) Inspect a sigstore bundle", Long: heredoc.Docf(` + # BETA: Feature subject to change + Inspect a downloaded Sigstore bundle for a given artifact. - + The command requires either: * a relative path to a local artifact, or * a container image URI (e.g. %[1]soci://%[1]s) @@ -37,7 +39,7 @@ func NewInspectCmd(f *cmdutil.Factory, runF func(*Options) error) *cobra.Command command). By default, the command will print information about the bundle in a table format. - If the %[1]s--json-result%[1]s flag is provided, the command will print the + If the %[1]s--json-result%[1]s flag is provided, the command will print the information in JSON format. `, "`"), Example: heredoc.Doc(` diff --git a/pkg/cmd/attestation/tufrootverify/tufrootverify.go b/pkg/cmd/attestation/tufrootverify/tufrootverify.go index bc07bfdee..5a4f704b3 100644 --- a/pkg/cmd/attestation/tufrootverify/tufrootverify.go +++ b/pkg/cmd/attestation/tufrootverify/tufrootverify.go @@ -21,15 +21,17 @@ func NewTUFRootVerifyCmd(f *cmdutil.Factory, runF func() error) *cobra.Command { var cmd = cobra.Command{ Use: "tuf-root-verify --mirror --root ", Args: cobra.ExactArgs(0), - Short: "Verify the TUF repository from a provided TUF root", + Short: "(BETA) Verify the TUF repository from a provided TUF root", Hidden: true, Long: heredoc.Docf(` + # BETA: Feature subject to change + Verify a TUF repository with a local TUF root. - The command requires you provide the %[1]s--mirror%[1]s flag, which should be the URL + The command requires you provide the %[1]s--mirror%[1]s flag, which should be the URL of the TUF repository mirror. - - The command also requires you provide the %[1]s--root%[1]s flag, which should be the + + The command also requires you provide the %[1]s--root%[1]s flag, which should be the path to the TUF root file. GitHub relies on TUF to securely deliver the trust root for our signing authority. diff --git a/pkg/cmd/attestation/verify/verify.go b/pkg/cmd/attestation/verify/verify.go index 451ba91d7..ebf9ce61b 100644 --- a/pkg/cmd/attestation/verify/verify.go +++ b/pkg/cmd/attestation/verify/verify.go @@ -23,8 +23,10 @@ func NewVerifyCmd(f *cmdutil.Factory, runF func(*Options) error) *cobra.Command verifyCmd := &cobra.Command{ Use: "verify [ | oci://] [--owner | --repo]", 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", + Short: "(BETA) Verify an artifact's integrity using attestations", Long: heredoc.Docf(` + # BETA: Feature subject to change + Verify the integrity and provenance of an artifact using its associated cryptographically signed attestations.