LinuxCommandLibrary

gh-attestation

Generate software supply chain attestations

TLDR

Download attestations for a local file associated with a specific repository

$ gh [[at|attestation]] download [path/to/artifact.bin] [[-R|--repo]] [owner]/[repository]
copy

Download attestations for an OCI container image associated with an organization
$ gh [[at|attestation]] download oci://[image_uri] [[-o|--owner]] [organization_name]
copy

Verify a local artifact online against attestations from a specific repository
$ gh [[at|attestation]] verify [path/to/artifact.bin] [[-R|--repo]] [owner]/[repository]
copy

Verify an artifact, requiring it was signed by a specific reusable workflow for enhanced security
$ gh [[at|attestation]] verify [path/to/artifact.bin] [[-o|--owner]] [organization_name] --signer-workflow [owner]/[repository]/[path/to/workflow.yml]
copy

Verify an artifact and output the detailed verification results as JSON for use in policy engines
$ gh [[at|attestation]] verify [path/to/artifact.bin] [[-o|--owner]] [organization_name] --format json
copy

Perform a fully offline verification using a downloaded bundle and a custom trusted root file
$ gh [[at|attestation]] verify [path/to/artifact.bin] [[-b|--bundle]] [path/to/bundle.jsonl] --custom-trusted-root [path/to/trusted_root.jsonl]
copy

Save the trusted root of signing certificates to a file for offline verification
$ gh [[at|attestation]] trusted-root > [path/to/trusted_root.jsonl]
copy

SYNOPSIS

gh attestation verify <artifact-path> [flags]

PARAMETERS

--policy-file <file>
    Path to local JSON verification policy

--policy-repo <owner/repo>
    GitHub repo hosting the policy file

--source-repo <owner/repo>[:ref]
    Expected source repository and optional ref

--log-level <level>
    Set log verbosity (debug|info|warn|error)

--output, -o <format>
    Output format: table|json|tap

--json
    Emit JSON even with table output

DESCRIPTION

The gh attestation command, part of the GitHub CLI, enables verification of cryptographic attestations for software artifacts built via GitHub Actions. These attestations, based on in-toto and SLSA standards, prove an artifact's provenance—confirming it was produced by a specific workflow, repository, and ref.

Primarily used in supply chain security, it helps developers and users validate downloads against expected builds, detecting tampering or unauthorized origins. The core verify subcommand inspects Sigstore bundle attestations embedded in OCI images or standalone files, checking predicates like workflow details, materials, and parameters.

Supports policy-based verification via JSON schemas hosted on GitHub or local files, allowing customizable rules for digest matching, builder identity, and more. Outputs results in human-readable, JSON, or TAP formats for CI integration.

Ideal for securing binaries, container images, and packages in CI/CD pipelines, reducing risks from malicious substitutions.

CAVEATS

Requires GitHub CLI v2.20.0+; attestations must be generated by GitHub Actions with provenance enabled. Does not support custom environments or non-Sigstore bundles. Network access needed for remote policies.

EXAMPLE

gh attestation verify ./my-binary --policy-repo myorg/my-repo
Verifies binary against repo policy.

POLICY

Policies define rules in JSON/YAML, e.g., require specific builder.id or materials digests for trusted builds.

HISTORY

Introduced in GitHub CLI v2.20.0 (May 2023) alongside GitHub's artifact attestation feature, evolving from SLSA v1.0 support to full in-toto v0.1 compliance by v2.48.0.

SEE ALSO

gh(1), cosign(1), slsa-verifier(1)

Copied to clipboard