Repository: cli/cli
File: pkg/cmd/attestation/verify/verify.go (Go)

Code before:
			In order to verify an attestation, you must validate the identity of the Actions
			workflow that produced the attestation (a.k.a. the signer workflow). Given this
			identity, the verification process checks the signatures in the attestations,
			and confirms that the attestation refers to provided artifact.

			To specify the artifact, the command requires:
			* a file path to an artifact, or
			* a container image URI (e.g. %[1]soci://<image-uri>%[1]s)
			  * (note that if you provide an OCI URL, you must already be authenticated with
			its container registry)

			To fetch the attestation, and validate the identity of the signer, the command
			requires either:
			* the %[1]s--repo%[1]s flag (e.g. --repo github/example).
			* 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 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 (c.f. the %[1]sdownload%[1]s command),
			provide a path to the %[1]s--bundle%[1]s flag. Additionally, the command
			will only verify provenance attestations by default. To verify
			other types of attestations, use the %[1]s--predicate-type%[1]s flag.

			To see the full results that are generated upon successful verification, i.e.
			for use with a policy engine, provide the %[1]s--format=json%[1]s flag.

			The signer workflow's identity is validated against the Subject Alternative Name (SAN)
			within the attestation certificate. Often, the signer workflow is the
			same workflow that started the run and generated the attestation, and will be
			located inside your repository. For this reason, by default this command uses
			either the %[1]s--repo%[1]s or the %[1]s--owner%[1]s flag value to validate the SAN.

			However, sometimes the caller workflow is not the same workflow that
			performed the signing. If your attestation was generated via a reusable
			workflow, then that reusable workflow is the signer whose identity needs to be
			validated. In this situation, the signer workflow may or may not be located
			inside your %[1]s--repo%[1]s or %[1]s--owner%[1]s.

			When using reusable workflows, use the %[1]s--signer-repo%[1]s, %[1]s--signer-workflow%[1]s,
			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.
			`, "`"),
		Example: heredoc.Doc(`
			# Verify an artifact linked with a repository

Review comment (suggestion):
This help page is getting so wordy we'll soon have to provide a table of contents and some headers. Or link to a docs page.

Anyways here is a suggested rewording:

```
By default, the verify command will:
- only verify provenance attestations
- attempt to fetch relevant attestations via the GitHub API.

To verify other types of attestations, use the predicate-type flag.

To use your artifact's OCI registry instead of GitHub's API, use the --bundle-from-oci flag. For offline verification, using attestations stored on desk (c.f. the download command), provide a path to the --bundle flag.
```

Code after:
			In order to verify an attestation, you must validate the identity of the Actions
			workflow that produced the attestation (a.k.a. the signer workflow). Given this
			identity, the verification process checks the signatures in the attestations,
			and confirms that the attestation refers to provided artifact.

			To specify the artifact, the command requires:
			* a file path to an artifact, or
			* a container image URI (e.g. %[1]soci://<image-uri>%[1]s)
			  * (note that if you provide an OCI URL, you must already be authenticated with
			its container registry)

			To fetch the attestation, and validate the identity of the signer, the command
			requires either:
			* the %[1]s--repo%[1]s flag (e.g. --repo github/example).
			* 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 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:
			- only verify provenance attestations
			- attempt to fetch relevant attestations via the GitHub API.

			To verify other types of attestations, use the %[1]s--predicate-type%[1]s flag.

			To use your artifact's OCI registry instead of GitHub's API, use the
			%[1]s--bundle-from-oci%[1]s flag. For offline verification, using attestations
			stored on desk (c.f. the download 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.
			for use with a policy engine, provide the %[1]s--format=json%[1]s flag.

			The signer workflow's identity is validated against the Subject Alternative Name (SAN)
			within the attestation certificate. Often, the signer workflow is the
			same workflow that started the run and generated the attestation, and will be
			located inside your repository. For this reason, by default this command uses
			either the %[1]s--repo%[1]s or the %[1]s--owner%[1]s flag value to validate the SAN.

			However, sometimes the caller workflow is not the same workflow that
			performed the signing. If your attestation was generated via a reusable
			workflow, then that reusable workflow is the signer whose identity needs to be
			validated. In this situation, the signer workflow may or may not be located
			inside your %[1]s--repo%[1]s or %[1]s--owner%[1]s.

			When using reusable workflows, use the %[1]s--signer-repo%[1]s, %[1]s--signer-workflow%[1]s,
			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.