gh attestation verify

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

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>)
    • (note that if you provide an OCI URL, you must already be authenticated with its container registry)

In addition, the command requires either:

  • the --repo flag (e.g. --repo github/example).
  • 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 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 download command), provide a path to the --bundle flag.

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

The attestation's certificate's Subject Alternative Name (SAN) identifies the entity responsible for creating the attestation, which most of the time will be a GitHub Actions workflow file located inside your repository. By default, this command uses either the --repo or the --owner flag value to validate the SAN.

However, if you generate attestations with a reusable workflow then the SAN will identify the reusable workflow – which may or may not be located inside your --repo or --owner. In these situations, you can use the --cert-identity or --cert-identity-regex flags to specify the reusable workflow's URI.

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
--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.githubusercontent.com")
Issuer of the OIDC token
--custom-trusted-root <string>
Path to a custom trustedroot.json file to use for verification
--deny-self-hosted-runners
Fail verification for attestations generated on self-hosted runners
-d, --digest-alg <string> (default "sha256")
The algorithm used to compute a digest of the artifact: {sha256|sha512}
--format <string>
Output format: {json}
-q, --jq <expression>
Filter JSON output using a jq expression
-L, --limit <int> (default 30)
Maximum number of attestations to fetch
--no-public-good
Only verify attestations signed with GitHub's Sigstore instance
-o, --owner <string>
GitHub organization to scope attestation lookup by
--predicate-type <string>
Filter attestations by provided predicate type
-R, --repo <string>
Repository name in the format <owner>/<repo>
-t, --template <string>
Format JSON output using a Go template; see "gh help formatting"

Examples

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

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

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

See also