Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
GH-ATTESTATION-VERIFY(1)       GitHub CLI manual      GH-ATTESTATION-VERIFY(1)

NAME
       gh-attestation-verify  -	 Verify	an artifact's integrity	using attesta-
       tions

SYNOPSIS
       gh attestation verify  [<file-path>  |  oci://<image-uri>]  [--owner  |
       --repo] [flags]

DESCRIPTION
       Verify the integrity and	provenance of an artifact using	its associated
       cryptographically signed	attestations.

       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 ar-
       tifact, or * a container	image URI (e.g.	oci://<image-uri>)
	 * (note that if you provide an	OCI URL, you must already be authenti-
       cated with its container	registry)

       To fetch	the attestation, and validate the identity of the signer,  the
       command	requires  either:  * the --repo	flag (e.g. --repo github/exam-
       ple).  *	the --owner flag (e.g. --owner github),	or

       The --repo flag value must match	the name of the	GitHub repository that
       the artifact is linked with.

       The --owner 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 attesta-
       tions - 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.

       To  see	the  full results that are generated upon successful verifica-
       tion, i.e.  for use with	a policy  engine,  provide  the	 --format=json
       flag.

       The  signer workflow's identity is validated against the	Subject	Alter-
       native 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 rea-
       son, by default this command uses either	the --repo or the --owner 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 --repo or	--owner.

       When  using  reusable  workflows, use the --signer-repo,	--signer-work-
       flow, or	--cert-identity	flags to validate the signer workflow's	 iden-
       tity.

       For more	policy verification options, see the other available flags.

OPTIONS
       -b, --bundle <string>
	      Path to bundle on	disk, either a single bundle in	a JSON file or
	      a	JSON lines file	with multiple bundles

       --bundle-from-oci
	      When  verifying  an OCI image, fetch the attestation bundle from
	      the OCI registry instead of from GitHub

       --cert-identity <string>
	      Enforce that the certificate's subject alternative name  matches
	      the provided value exactly

       -i, --cert-identity-regex <string>
	      Enforce  that the	certificate's subject alternative name matches
	      the provided regex

       --cert-oidc-issuer <string> (default "https://token.actions.githubuser-
       content.com")
	      Issuer of	the OIDC token

       --custom-trusted-root <string>
	      Path to a	trusted_root.jsonl file; likely	for offline  verifica-
	      tion

       --deny-self-hosted-runners
	      Fail verification	for attestations generated on self-hosted run-
	      ners

       -d, --digest-alg	<string> (default "sha256")
	      The  algorithm  used  to	compute	 a  digest  of	the  artifact:
	      {sha256|sha512}

       --format	<string>
	      Output format: {json}

       --hostname <string>
	      Configure	host to	use

       -q, --jq	<expression>
	      Filter JSON output using a jq expression

       -L, --limit <int> (default 30)
	      Maximum number of	attestations to	fetch

       --no-public-good
	      Do not verify attestations signed	with Sigstore public good  in-
	      stance

       -o, --owner <string>
	      GitHub organization to scope attestation lookup by

       --predicate-type	<string> (default "https://slsa.dev/provenance/v1")
	      Filter attestations by provided predicate	type

       -R, --repo <string>
	      Repository name in the format /

       --signer-repo <string>
	      Repository  of  reusable workflow	that signed attestation	in the
	      format /

       --signer-workflow <string>
	      Workflow that signed attestation in the format [host/]////

       -t, --template <string>
	      Format JSON output using a Go template; see "gh help formatting"

EXIT CODES
       0: Successful execution

       1: Error

       2: Command canceled

       4: Authentication required

       NOTE: Specific commands may have	additional exit	codes.	Refer  to  the
       command's help for more information.

EXAMPLE
       # Verify	an artifact linked with	a repository
       $ gh attestation	verify example.bin --repo github/example

       # Verify	an artifact linked with	an organization
       $ gh attestation	verify example.bin --owner github

       # Verify	an artifact and	output the full	verification result
       $ gh attestation	verify example.bin --owner github --format json

       # Verify	an OCI image using attestations	stored on disk
       $ gh attestation	verify oci://<image-uri> --owner github	--bundle sha256:foo.jsonl

       # Verify	an artifact signed with	a reusable workflow
       $ gh attestation	verify example.bin --owner github --signer-repo	actions/example

SEE ALSO
       gh-attestation(1)

				   Apr 2025	      GH-ATTESTATION-VERIFY(1)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=gh-attestation-verify&sektion=1&manpath=FreeBSD+Ports+14.3.quarterly>

home | help