Add beta designation on attestation command set

[andyfeller]

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.

Output

• gh reference

  By updating commands' Short field, the visible commands in gh reference reinforce the beta designation:

  andyfeller@Andys-MBP:cli/cli ‹andyfeller/attestation-beta-usage*›$ ./bin/gh reference | grep -A 5 "gh at"
  ## `gh attestation [subcommand]`
  
  (BETA) Work with artifact attestations
  
  ### `gh attestation download [<file-path> | oci://<image-uri>] [--owner | --repo] [flags]`
  
  (BETA) Download an artifact's Sigstore bundle(s) for offline use
  
    -d, --digest-alg string       The algorithm used to compute a digest of the artifact: {sha256|sha512} (default "sha256")
    -L, --limit int               Maximum number of attestations to fetch (default 30)
  --
  ### `gh attestation verify [<file-path> | oci://<image-uri>] [--owner | --repo] [flags]`
  
  (BETA) Verify an artifact's integrity using attestations
  
    -b, --bundle string                Path to bundle on disk, either a single bundle in a JSON file or a JSON lines file with multiple bundles
        --cert-identity string         Enforce that the certificate's subject alternative name matches the provided value exactly

• gh attestation --help

  andyfeller@Andys-MBP:cli/cli ‹andyfeller/attestation-beta-usage*›$ ./bin/gh at --help         
  # BETA: Feature subject to change
  
  Download and verify artifact attestations.
  
  
  USAGE
    gh attestation [subcommand] [flags]
  
  ALIASES
    at
  
  AVAILABLE COMMANDS
    download:    (BETA) Download an artifact's Sigstore bundle(s) for offline use
    verify:      (BETA) Verify an artifact's integrity using attestations
  
  INHERITED FLAGS
    --help   Show help for command
  
  LEARN MORE
    Use `gh <command> <subcommand> --help` for more information about a command.
    Read the manual at https://cli.github.com/manual

• gh attestation download --help

  andyfeller@Andys-MBP:cli/cli ‹andyfeller/attestation-beta-usage*›$ ./bin/gh at download --help
  # BETA: Feature subject to change
  
  Download an artifact's attestations, aka Sigstore bundle(s), for offline use.
  
  The command requires either:
  * a file path to an artifact, or
  * a container image URI (e.g. `oci://<image-uri>`)

• gh attestation inspect --help

  andyfeller@Andys-MBP:cli/cli ‹andyfeller/attestation-beta-usage*›$ ./bin/gh at inspect --help
  # 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. `oci://<my-OCI-image-URI>`)

• gh attestation tuf-root-verify --help

  andyfeller@Andys-MBP:cli/cli ‹andyfeller/attestation-beta-usage*›$ ./bin/gh at tuf-root-verify --help
  # BETA: Feature subject to change
  
  Verify a TUF repository with a local TUF root.
  
  The command requires you provide the `--mirror` flag, which should be the URL
  of the TUF repository mirror.

• gh attestation verify --help

  andyfeller@Andys-MBP:cli/cli ‹andyfeller/attestation-beta-usage*›$ ./bin/gh at verify --help 
  # BETA: Feature subject to change
  
  Verify the integrity and provenance of an artifact using its associated
  cryptographically signed attestations.
  
  The command requires either:
  * a file path to an artifact, or
  * a container image URI (e.g. `oci://<image-uri>`)

[cliAutomation]

Hi! Thanks for the pull request. Please ensure that this change is linked to an issue by mentioning an issue number in the description of the pull request. If this pull request would close the issue, please put the word 'Fixes' before the issue number somewhere in the pull request body. If this is a tiny change like fixing a typo, feel free to ignore this message.

[williammartin]

Best to get a LGTM from package security but looks good to me.

[steiza]

I don't totally understand how cobra works. This will show up if I do gh attestation verify --help but not gh attestation verify?

[andyfeller]

Yeah, the Long field shows up when --help is used for a command OR gh reference which is a custom command that lists all GH CLI commands help in 1 place

[andyfeller]

As an aside, recommend checking out https://cobra.dev/

[williammartin]

And also visible in the online manual e.g. https://cli.github.com/manual/gh_auth_login and manpages

[andyfeller]

Also worth calling out that Short shows up when calling gh at --help:

$ ./bin/gh at --help
# BETA: Feature subject to change

Download and verify artifact attestations.


USAGE
  gh attestation [subcommand] [flags]

ALIASES
  at

AVAILABLE COMMANDS
  download:    (BETA) Download an artifact's Sigstore bundle(s) for offline use
  verify:      (BETA) Verify an artifact's integrity using attestations

INHERITED FLAGS
  --help   Show help for command

LEARN MORE
  Use `gh <command> <subcommand> --help` for more information about a command.
  Read the manual at https://cli.github.com/manual

[trevrosen]

Thanks for handling this @andyfeller !

[phillmv]

I've proposed a tweak to the language being suggested here to delineate the feature's beta status.

[andyfeller]

Updated beta designation

1. No longer showing up in Short command descriptions
2. Uses new language

andyfeller@Andys-MBP:cli/cli ‹andyfeller/attestation-beta-usage*›$ ./bin/gh attestation --help
# NOTE: This feature is currently in beta, and subject to change.

Download and verify artifact attestations.


USAGE
  gh attestation [subcommand] [flags]

ALIASES
  at

AVAILABLE COMMANDS
  download:    Download an artifact's Sigstore bundle(s) for offline use
  verify:      Verify an artifact's integrity using attestations

INHERITED FLAGS
  --help   Show help for command

LEARN MORE
  Use `gh <command> <subcommand> --help` for more information about a command.
  Read the manual at https://cli.github.com/manual

andyfeller@Andys-MBP:cli/cli ‹andyfeller/attestation-beta-usage*›$ ./bin/gh attestation download --help
# 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:
* a file path to an artifact, or
* a container image URI (e.g. `oci://<image-uri>`)

(Note that if you provide an OCI URL, you must already be authenticated with
its container registry.)
...

andyfeller@Andys-MBP:cli/cli ‹andyfeller/attestation-beta-usage*›$ ./bin/gh attestation verify --help  
# 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.

The command requires either:
* a file path to an artifact, or
* a container image URI (e.g. `oci://<image-uri>`)