Attestation

Active contributors: Meredith Lancaster, Phill MV, ejahnGithub

Purpose

gh attestation is the CLI's interface to GitHub's SLSA build provenance and Sigstore-based verification. It can verify any artifact that has a published attestation, fetch attestations from a repo or registry, manage TUF trusted roots, and inspect attestation contents. The same code paths back gh release verify and gh release verify-asset.

Directory layout

pkg/cmd/attestation/
  attestation.go              # NewCmdAttestation
  verify/                     # gh attestation verify <artifact>
  download/                   # gh attestation download
  inspect/                    # gh attestation inspect
  trustedroot/                # gh attestation trusted-root (manage TUF roots)
  api/                        # GitHub attestation REST/GraphQL endpoints
  artifact/                   # OCI + filesystem artifact loaders
  auth/                       # token/issuer resolution
  io/                         # streaming helpers
  test/                       # shared test fixtures
  verification/
    embed/tuf-repo.github.com/  # offline-embedded TUF root (signed)
    bundle.go / verify.go ...   # core verifier implementation

This is one of the largest single command trees in cli/cli. It is owned by @cli/package-security per .github/CODEOWNERS, with a separate @cli/tuf-root-reviewers owner for the embedded TUF data.

Key abstractions

Symbol	File	Role
NewCmdAttestation	pkg/cmd/attestation/attestation.go	Subcommand registration.
Verifier	pkg/cmd/attestation/verification/verify.go	Coordinates Sigstore verification (cert chain, transparency log, policy).
Bundle	pkg/cmd/attestation/verification/bundle.go	Wraps sigstore-go bundles.
TrustedRoot	pkg/cmd/attestation/trustedroot/	Manages the TUF-signed Sigstore trust root.
ArtifactLoader	pkg/cmd/attestation/artifact/	Reads artifacts from disk or a container registry (uses google/go-containerregistry).
EmbeddedTUFRepo	pkg/cmd/attestation/verification/embed/tuf-repo.github.com/	The offline-usable TUF root committed into the repo.

How it works

gh attestation verify ./gh_2.99.0_linux_amd64.tar.gz -R cli/cli:

sequenceDiagram
    participant User
    participant CLI as gh attestation verify
    participant API as GitHub Attestations API
    participant TUF as Embedded TUF root
    participant Sigstore as sigstore-go

    User->>CLI: artifact + policy (-R, --signer-workflow, etc.)
    CLI->>API: GET /repos/cli/cli/attestations/sha256:<digest>
    API-->>CLI: attestation bundle(s)
    CLI->>TUF: load Sigstore trust roots
    CLI->>Sigstore: VerifyBundle(bundle, trust)
    Sigstore-->>CLI: verified statement
    CLI->>CLI: enforce policy (workflow path, repo, certificate identity)
    CLI-->>User: verification result

The CLI ships an embedded copy of the TUF root so gh attestation verify works fully offline (subject to a freshness check). Network refreshes happen via the --update-trusted-root flag and gh attestation trusted-root subcommands.

Integration points

• Used by gh release verify and gh release verify-asset (separate Cobra commands).
• Pulls in heavy Sigstore dependencies: sigstore/sigstore-go, sigstore/protobuf-specs, sigstore/rekor, sigstore/timestamp-authority, theupdateframework/go-tuf, digitorus/timestamp. See reference/dependencies.md.
• Uses google/go-containerregistry to fetch attestations attached to OCI artifacts.
• Embeds an in-toto attestation library (in-toto/attestation) for statement inspection.

Entry points for modification

• New artifact source: extend pkg/cmd/attestation/artifact/. The interface is small but plugged into every verify subcommand.
• New policy field: extend the policy struct in verification/policy.go and the CLI flag layer in verify/verify.go.
• TUF root rotation: changes to verification/embed/tuf-repo.github.com/ require approval from @cli/tuf-root-reviewers. The embedded files are signed; do not hand-edit them.

Key source files

File	Purpose
pkg/cmd/attestation/attestation.go	Subcommand registration.
pkg/cmd/attestation/verify/verify.go	The main gh attestation verify flow.
pkg/cmd/attestation/verification/verify.go	Sigstore verification core.
pkg/cmd/attestation/verification/bundle.go	Sigstore bundle wrapper.
pkg/cmd/attestation/trustedroot/trustedroot.go	TUF root management.
pkg/cmd/attestation/api/api.go	GitHub attestations API client.
pkg/cmd/attestation/artifact/artifact.go	Artifact loader.
pkg/cmd/attestation/inspect/inspect.go	Attestation viewer.
pkg/cmd/release/verify/verify.go	The release-side bridge.

Related pages

• Releases.
• API client.