Artifact Attestations, SBOM Provenance, Verification, and SLSA-Oriented Builds: Core Concepts and Mental Model

1. The practical problem: a file name does not tell you where its bytes came from

A release named app-1.4.0.zip can be copied, replaced or rebuilt. A SHA-256 checksum proves whether two byte sequences are identical, but a checksum by itself does not answer who built those bytes, from which repository revision, under which workflow, or whether the claimed build identity should be trusted.

Chapter 23 adds a cryptographically verifiable link between an artifact digest and a GitHub Actions build identity. The core question changes from “does this file have the checksum written next to it?” to “does this exact digest have a valid attestation issued for the repository/workflow/ref that my policy allows?”

2. Four terms that must stay separate

3. Define the state before signing anything

4. Mental model: subject bytes first, signed claim second, policy last

Read this graph top to bottom. The build creates bytes once. Their digest becomes the attestation subject. GitHub mints an OIDC identity for the eligible job; the attestation action uses that identity to obtain short-lived signing material and stores the resulting signed statement. A consumer later hashes the file again and validates both the cryptographic evidence and the expected builder identity.

flowchart TD
  A[Source repository + exact commit] --> B[Trusted workflow revision]
  B --> C[Build exact artifact bytes]
  C --> D[SHA-256 subject digest]
  B --> E[OIDC identity via id-token permission]
  D --> F[actions/attest]
  E --> F
  F --> G[Signed in-toto attestation]
  G --> H[GitHub attestation store + Sigstore evidence]
  C --> I[Artifact distribution channel]
  H --> J[Consumer verification]
  I --> J
  J --> K{Identity + predicate + digest match policy?}
  K -->|yes| L[Eligible for next control]
  K -->|no| M[Reject and preserve evidence]

5. How GitHub signs without a long-lived signing key in the workflow

GitHub artifact attestations use Sigstore. The workflow receives an OIDC identity only when the job has id-token: write. The attestation tooling exchanges that identity for short-lived signing material, creates the attestation, and associates it with the initiating repository. The job does not need a stored private signing key.

For public repositories, GitHub uses the Sigstore Public Good Instance and the evidence participates in a public transparency log. For private/internal repositories, GitHub uses its private Sigstore instance; that path requires GitHub Enterprise Cloud and does not use the public transparency log.

6. Current implementation baseline (verified 2026-09-10)

New workflows should use the consolidated actions/attest action. The current release used by this chapter is v4.2.2, pinned to full commit SHA 1e69f48acb82d1966a394da916b4c1698aa569d6. It supports three modes: default SLSA build provenance, SBOM attestation when sbom-path is supplied, and custom predicates.

permissions:
  contents: read
  id-token: write
  attestations: write
  artifact-metadata: write

steps:
  - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
  - name: Build exact subject
    run: ./scripts/build.sh
  - name: Attest build provenance
    uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2
    with:
      subject-path: dist/app.txt

7. What the verifier actually checks

gh attestation verify recomputes the subject digest and verifies the signed bundle. It also lets the consumer constrain actor identity. At minimum, verification is scoped by repository or owner. Stronger policy can additionally require the expected signer workflow, source repository/ref or signer/source digest.

This distinction matters because “the signature is valid” is weaker than “this artifact was signed by the workflow I intended.” The GitHub CLI documentation also warns that predicate content can contain workflow-controlled data. High-assurance policy should rely on cryptographically bound signer/certificate identity plus carefully selected claims, not blindly trust every field emitted by a compromised build.

gh attestation verify dist/app.txt   --repo EXAMPLE_ORG/gha-attestation-lab   --signer-workflow EXAMPLE_ORG/gha-attestation-lab/.github/workflows/attest.yml   --source-ref refs/heads/main

8. SBOM attestation answers a different question

A provenance attestation answers “where/how was this subject built?” An SBOM attestation carries a software inventory predicate such as SPDX or CycloneDX. The current actions/attest action accepts an SPDX or CycloneDX JSON file through sbom-path. The SBOM is still a claim about the subject; it does not itself run vulnerability analysis.

For a release-grade artifact, provenance and SBOM evidence complement each other. Generate them for the same exact subject bytes, then verify the provenance predicate and the SBOM predicate independently when your consumer policy requires both.

9. Artifact upload and attestation storage are different states

Attesting dist/app.txt does not magically publish that file as a release asset, package or Actions artifact. The attestation is stored by GitHub and tied to the subject digest, while the binary still needs its own distribution channel. Conversely, uploading a file as an Actions artifact does not automatically prove its provenance unless the workflow also creates/verifies an attestation.

Keep one-build semantics: build once, record digest, attest those bytes, and publish those same bytes. Rebuilding “the same version” later creates a new subject digest and therefore a different object.

10. SLSA-oriented does not mean “we are SLSA compliant”

SLSA is a framework for progressively stronger software-build integrity controls. Artifact attestations, immutable dependencies, isolated builders, protected reusable workflows and identity-constrained verification can contribute to SLSA-oriented architecture. GitHub documents patterns that can help organizations achieve stronger SLSA build levels.

This chapter deliberately avoids declaring compliance from one YAML file. A compliance claim depends on the complete build system, policy and threat model—not simply the presence of an attestation step.

11. Common wrong mental models

12. What Chapter 23 adds to the operating model

The operating model now has a cryptographic evidence layer between build completion and release/deployment authorization. A production consumer can demand the exact artifact digest plus a verifiable signer identity, source/ref and predicate type before the object becomes eligible for promotion.

13. Lesson summary

Build the artifact once, identify it by digest, create provenance/SBOM attestations with narrow signing permissions, store/distribute the artifact separately, and verify both cryptographic integrity and expected builder identity. Treat verification as an input to policy—not as a substitute for security review.

Knowledge check

Official references and version notes

• Artifact attestations concept — GitHub model for Sigstore-backed attestations, public/private signing roots and verification policy.
• Use artifact attestations — Current generation, permissions, binary/container and verification guidance.
• actions/attest v4.2.2 — Current consolidated GitHub action for provenance, SBOM and custom attestations.
• GitHub CLI attestation verify — Current identity, predicate, source-ref and signer-workflow verification controls.
• Verify attestations offline — Bundle and trusted-root workflow for disconnected verification.
• SLSA-oriented GitHub guidance — GitHub guidance connecting attestations and reusable workflows to stronger SLSA-oriented build controls.
• Workflow permissions — Current id-token, attestations, artifact-metadata and contents permission syntax.