gh-attestation

Download attestations for a local file associated with a specific repository

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

$ gh [[at|attestation]] download oci://[image_uri] [[-o|--owner]] [organization_name]

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

$ gh [[at|attestation]] verify [path/to/artifact.bin] [[-o|--owner]] [organization_name] --signer-workflow [owner]/[repo]/[path/to/workflow.yml]

$ gh [[at|attestation]] verify [path/to/artifact.bin] [[-o|--owner]] [organization_name] --format json

$ gh [[at|attestation]] verify [path/to/artifact.bin] [[-b|--bundle]] [path/to/bundle.jsonl] --custom-trusted-root [path/to/trusted_root.jsonl]

$ gh [[at|attestation]] trusted-root > [path/to/trusted_root.jsonl]

gh attestation command [flags]

Available Commands:
generate    Generate an attestation for a build
upload       Upload an attestation to a repository
verify       Verify an attestation against policies
download     Download an attestation from a repository
help         Help about any command

--repo
    The repository to operate on. Defaults to the current repository.

--branch
    The branch associated with the workflow run or artifact.

--workflow
    The workflow file to generate/upload an attestation for.

--ref
    The Git reference (e.g., tag, commit SHA) for the attestation subject.

--output
    Output path for the generated attestation file (for 'generate' command).

--bundle
    Path to a pre-generated attestation bundle file (for 'upload' and 'verify' commands).

--subject :
    Specifies an artifact subject and its digest for the attestation. Can be repeated.

--format
    Output format for the generated attestation (e.g., 'json', 'spdx', 'cyclonedx').

--predicate-type
    The type of predicate to generate or verify (e.g., 'slsa.provenance', 'cyclonedx', 'spdx').

--policy
    Path to a policy file for verification (for 'verify' command).

--artifact-path
    Path to the artifact whose attestation needs to be verified (for 'verify' command).

The `gh attestation` command is a vital tool for enhancing software supply chain security within the GitHub ecosystem. It enables developers to generate, upload, and verify cryptographic attestations for their software artifacts, particularly those built using GitHub Actions.

These attestations, often conforming to the SLSA (Supply Chain Levels for Software Artifacts) framework, provide an immutable record of an artifact's provenance – detailing how, when, and by whom it was built. This transparency is crucial for mitigating risks associated with supply chain attacks, ensuring the integrity and authenticity of software components.

The command allows users to generate attestations (e.g., SLSA Provenance), upload them to secure storage like GitHub's OCI registry alongside the artifacts, and subsequently verify these attestations against defined policies. By integrating `gh attestation` into CI/CD pipelines, organizations can establish a robust security posture, enabling consumers of their software to confidently trust its origin and integrity.

Attestation generation is most robust and automatic within GitHub Actions workflows, leveraging GitHub's built-in signing capabilities. Manual generation and upload can be more complex.

Defining effective verification policies requires a deep understanding of your supply chain and security requirements, and their implementation can be intricate.

The security and trustworthiness of attestations fundamentally rely on the integrity of the signing keys and the underlying cryptographic infrastructure.

`gh attestation` is heavily aligned with the SLSA (Supply Chain Levels for Software Artifacts) framework, a set of standards designed to enhance the integrity of software artifacts. It primarily supports generating SLSA Provenance attestations, which detail the source code, build process, and dependencies of a built artifact. This direct integration helps projects achieve higher SLSA levels by providing cryptographic proof of their build process.

While `gh attestation` can be used locally, its most common and powerful application is within GitHub Actions workflows. GitHub provides native actions and environments that streamline the generation and signing of attestations for artifacts produced in a workflow run. This automation ensures that every build automatically generates verifiable provenance, which can then be uploaded and later verified by consumers.

The `gh attestation` command emerged as a direct response to the increasing threat of software supply chain attacks and the industry's drive for greater transparency and trustworthiness in software development. Following initiatives like the SLSA (Supply Chain Levels for Software Artifacts) framework, GitHub invested heavily in providing tools to secure its ecosystem.

Introduced as a feature within the GitHub CLI, `gh attestation` provides a convenient, command-line interface for interacting with GitHub's attestation services, enabling developers to easily integrate provenance generation and verification into their CI/CD pipelines, particularly within GitHub Actions. Its development reflects a broader industry shift towards verifiable software artifacts.

gh(1), cosign(1), openssl(1)