GH-ATTESTATION-VERIFY(1)

💅 GH-ATTESTATION-VERIFY — the manual, but make it make sense

okay so first things first: this whole thing lives in the GitHub CLI manual, and the page is literally called GH-ATTESTATION-VERIFY(1). that's the name, that's the vibe, we move 💖

---

✨ NAME ✨

gh-attestation-verify — verify an artifact's integrity using attestations. yes bestie, we're doing cryptography today 🧚

---

🦋 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. that's the whole assignment, and honestly? it ate. 🔥

💫 Understanding Verification

so an attestation is a claim (i.e. a provenance statement) made by an actor (i.e. a GitHub Actions workflow) regarding a subject (i.e. an artifact). think of it like a signed note that says "yeah, I made this, and here's the receipts" 🫶

to verify an attestation, you must provide an artifact and validate:

• the identity of the actor that produced the attestation
• the expected attestation predicate type (the nature of the claim)

by default, this command enforces the https://slsa.dev/provenance/v1 predicate type. to verify other attestation predicate types, use the --predicate-type flag. no cap ✨

the "actor identity" consists of:

• the repository or the repository owner the artifact is linked with
• the Actions workflow that produced the attestation (a.k.a the signer workflow)

this identity is then validated against the attestation's certificate's SourceRepository, SourceRepositoryOwner, and SubjectAlternativeName (SAN) fields, among others. iykyk 👑

it is up to you to decide how precisely you want to enforce this identity. your call, bestie.

at a minimum, this command requires either:

• the --owner flag (e.g. --owner github), or
• the --repo flag (e.g. --repo github/example)

the more precisely you specify the identity, the more control you will have over the security guarantees offered by the verification process 🔒

ideally, the path of the signer workflow is also validated using the --signer-workflow or --cert-identity flags.

⚠️ please note: 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, you must use either the --signer-workflow or the --signer-repo flag. don't skip this, fr fr 😭

for more options, see the other available flags. we got you 💅

🎀 Loading Artifacts And Attestations 🎀

to specify the artifact, this command requires:

• 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)

by default, this command will attempt to fetch relevant attestations via the GitHub API using the values provided to --owner or --repo.

to instead fetch attestations from your artifact's OCI registry, use the --bundle-from-oci flag. so convenient 🌈

for offline verification using attestations stored on disk (c.f. the download command) provide a path to the --bundle flag. offline era 💾✨

⭐ Additional Policy Enforcement ⭐

given the --format=json flag, upon successful verification this command will output a JSON array containing one entry per verified attestation.

this output can then be used for additional policy enforcement, i.e. by being piped into a policy engine. pipe it, queen 🫡

each object in the array contains two properties:

• an attestation object, which contains the bundle that was verified
• a verificationResult object, which is a parsed representation of the contents of the bundle that was verified.

within the verificationResult object you will find:

• signature.certificate, which is a parsed representation of the X.509 certificate embedded in the attestation,
• verifiedTimestamps, an array of objects denoting when the attestation was witnessed by a transparency log or a timestamp authority
• statement, which contains the subject array referencing artifacts, the predicateType field, and the predicate object which contains additional, often user-controllable, metadata

🚨 IMPORTANT: please note that only the signature.certificate and the verifiedTimestamps properties contain values that cannot be manipulated by the workflow that originated the attestation. everything else? kinda sus. 💀

when dealing with attestations created within GitHub Actions, the contents of signature.certificate are populated directly from the OpenID Connect token that GitHub has generated. the contents of the verifiedTimestamps array are populated from the signed timestamps originating from either a transparency log or a timestamp authority – and likewise cannot be forged by users. iconic behavior, honestly 👑

when designing policy enforcement using this output, special care must be taken when examining the contents of the statement.predicate property: should an attacker gain access to your workflow's execution context, they could then falsify the contents of the statement.predicate. not to be dramatic but 😭

to mitigate this attack vector, consider using a "trusted builder": when generating an artifact, have the build and attestation signing occur within a reusable workflow whose execution cannot be influenced by input provided through the caller workflow.

see above re: --signer-workflow. yeah, that one. 🎯

---

💖 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 SubjectAlternativeName matches the provided value exactly. no wiggle room ✨
• -i, --cert-identity-regex <string> — enforce that the certificate's SubjectAlternativeName matches the provided regex
• --cert-oidc-issuer <string> (default "https://token.actions.githubusercontent.com") — enforce that the issuer of the OIDC token matches the provided value
• --custom-trusted-root <string> — path to a trusted_root.jsonl file; likely for offline 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}
• --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 instance
• -o, --owner <string> — GitHub organization to scope attestation lookup by
• --predicate-type <string> (default "https://slsa.dev/provenance/v1") — enforce that verified attestations' predicate type matches the provided value
• -R, --repo <string> — repository name in the format /
• --signer-digest <string> — enforce that the digest associated with the signer workflow matches the provided value
• --signer-repo <string> — enforce that the workflow that signed the attestation's repository matches the provided value (/)
• --signer-workflow <string> — enforce that the workflow that signed the attestation matches the provided value ([host/]////)
• --source-digest <string> — enforce that the digest associated with the source repository matches the provided value
• --source-ref <string> — enforce that the git ref associated with the source repository matches the provided value
• -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

look at those examples go. absolutely slayed 💅🔥

---

🦋 SEE ALSO 🦋

• gh-attestation(1)

---

and that's the tea, bestie 🍵 this page is from GitHub CLI v2.102.0, dated Oct 2026 — go verify something and stay iconic 💜✨🎀