diff --git a/pkg/cmd/attestation/attestation.go b/pkg/cmd/attestation/attestation.go index 75de9eca7..5b358a6bf 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" @@ -15,7 +16,11 @@ func NewCmdAttestation(f *cmdutil.Factory) *cobra.Command { Use: "attestation [subcommand]", Short: "Work with artifact attestations", Aliases: []string{"at"}, - Long: "Download and verify artifact attestations.", + Long: heredoc.Doc(` + # NOTE: This feature is currently in beta, and 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..fd6aa5f01 100644 --- a/pkg/cmd/attestation/download/download.go +++ b/pkg/cmd/attestation/download/download.go @@ -23,6 +23,8 @@ func NewDownloadCmd(f *cmdutil.Factory, runF func(*Options) error) *cobra.Comman 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", Long: heredoc.Docf(` + # NOTE: This feature is currently in beta, and 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..36682fac5 100644 --- a/pkg/cmd/attestation/inspect/inspect.go +++ b/pkg/cmd/attestation/inspect/inspect.go @@ -23,8 +23,10 @@ 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. + 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..63d0f949b 100644 --- a/pkg/cmd/attestation/tufrootverify/tufrootverify.go +++ b/pkg/cmd/attestation/tufrootverify/tufrootverify.go @@ -24,12 +24,14 @@ func NewTUFRootVerifyCmd(f *cmdutil.Factory, runF func() error) *cobra.Command { Short: "Verify the TUF repository from a provided TUF root", Hidden: true, Long: heredoc.Docf(` + # NOTE: This feature is currently in beta, and 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..1b3a6b511 100644 --- a/pkg/cmd/attestation/verify/verify.go +++ b/pkg/cmd/attestation/verify/verify.go @@ -25,6 +25,8 @@ 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. + Verify the integrity and provenance of an artifact using its associated cryptographically signed attestations.