Artifact Attestations, SBOMs, Build Provenance, Verification, and SLSA-Oriented Workflows: Concepts, Architecture, and Mental Model

1. The problem: location and version labels are not artifact identity

Chapter 17 separated workflow artifacts from caches, Chapter 19 promoted immutable deployment inputs, Chapter 21 distributed packages by version/digest, and Chapter 24 treated credentials as trust boundaries. Chapter 25 asks the consumer-side question those chapters leave open: what evidence proves that these exact bytes were produced by a workflow I am willing to trust?

A file called atlas-1.0.0.tar, a release tag such as v1.0.0, or a container tag such as stable is a human-readable locator. Those names can be copied or, depending on the system, moved. A cryptographic digest such as SHA-256 is computed from the bytes themselves. If one byte changes, the digest changes. Provenance and attestations become meaningful only when the subject digest identifies the artifact a consumer actually received.

2. Mental model: bytes → digest → signed claim → policy decision

              flowchart TD
                S["Source commit + workflow"] -->|build on GitHub Actions| A["Artifact bytes"]
                A -->|SHA-256| D["Immutable subject digest"]
                O["Actions OIDC identity"] -->|repository/workflow/ref/event claims| T["GitHub / Sigstore attestation"]
                D -->|subject| T
                P["Provenance predicate"] -->|how/where build ran| T
                B["SBOM predicate"] -->|component inventory| T
                A -->|received bytes| V["Consumer verifier"]
                T -->|signature + certificate + timestamps| V
                R["Policy: repo + signer workflow + ref + runner + predicate"] --> V
                V -->|all constraints pass| G["Accept / deploy"]
                V -->|digest or identity/policy fails| X["Reject + investigate"]
            

The artifact bytes are first hashed. The digest is the attestation subject: the thing the claim is about. A predicate is the body of a claim—for example SLSA provenance describing the build or an SPDX/CycloneDX SBOM describing software components. The attestation also carries signing/identity evidence. On GitHub Actions, the certificate is derived from GitHub-issued OIDC identity; the workflow does not manage a reusable private signing key.

Verification has two independent questions. First, do the received bytes match the subject digest and does the cryptographic bundle verify against an accepted trust root? Second, does the authenticated builder identity satisfy your policy—right repository, signer workflow, ref, issuer and possibly runner type? Passing question one but skipping question two proves authenticity to an identity you may not actually trust.

3. Vocabulary: subject, predicate, issuer and verifier

4. GitHub artifact attestations and Actions identity

Current GitHub artifact attestations are implemented with Sigstore. For public repositories GitHub uses the Sigstore Public Good Instance; the Sigstore bundle is also recorded in a public transparency log. Private repositories on the eligible Enterprise Cloud path use GitHub’s Sigstore instance, which does not use the public transparency log and federates with GitHub Actions.

The authenticated certificate records identity derived from the Actions OIDC token, including repository/workflow context. This is why the workflow needs id-token: write while the attestation store needs attestations: write. Those permissions authorize issuance/storage; they do not mean a workflow can obtain GitHub’s signing private key.

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

5. Provenance and SBOM answer different questions

An SBOM can be attested against the same subject digest as provenance. That gives a consumer two independently typed claims: “these bytes came from this build identity” and “this inventory describes these bytes.” The producer is still responsible for generating an inventory that actually reflects the shipped result. An SBOM produced only from source manifests can miss resolved, vendored, generated or post-build components.

6. Read-only inspection before any lab mutation

Start with tooling and repository metadata. These commands neither create an attestation nor request an OIDC token. They prove which repository/host you are about to use and whether your installed GitHub CLI exposes the current attestation verification surface.

gh --version
gh auth status

gh api -H "X-GitHub-Api-Version: 2026-03-10" user --jq '{login,id}'
gh attestation verify --help | sed -n '1,120p'
gh attestation trusted-root --help | sed -n '1,100p'

Important verifier controls currently include --repo/--owner, --signer-workflow, --signer-repo, --source-ref, --source-digest, --cert-oidc-issuer, and --deny-self-hosted-runners. More constraints generally create a stronger statement of what you expected—not a stronger cryptographic algorithm.

7. SLSA: a broader model, not a GitHub badge

SLSA (Supply-chain Levels for Software Artifacts) is a broader specification maintained outside GitHub. The current SLSA specification is version 1.2 and its Build track still distinguishes Build L1 provenance existence, Build L2 hosted/authentic provenance, and Build L3 a hardened/isolated build platform. GitHub documentation currently describes artifact attestations by themselves as providing SLSA v1.0 Build Level 2 and describes a trusted reusable-workflow pattern as helping achieve Build Level 3.

Treat that GitHub statement as product guidance for a specific GitHub Actions architecture—not permission to label every repository “SLSA L3 certified.” A real claim must be evaluated against the applicable SLSA version/track requirements, the build platform, the producer’s workflow design, and consumer verification. SLSA is about supply-chain properties; it is not a guarantee that application code has no vulnerabilities.

8. Threat model: replay, substitution and wrong-builder trust

9. Why this matters in DevOps

CI/CD crosses administrative boundaries: source control builds software, package systems distribute it, and deployment systems consume it. Provenance gives the consumer a machine-verifiable bridge across those boundaries. Instead of trusting a filename or “the pipeline was green,” the deployment can ask whether the bytes have an accepted attestation and whether the authenticated workflow identity matches policy.

The highest-value change is cultural as much as cryptographic: producers publish evidence, but consumers verify it. GitHub itself warns that generating attestations alone provides no security benefit if no consumer verifies them.

Knowledge check

Summary

Artifact identity begins with bytes and digest. An attestation signs a typed claim about that subject; provenance explains the build, an SBOM inventories components, and the verifier validates both cryptography and expected builder identity. GitHub supplies an OIDC/Sigstore-backed implementation, while SLSA remains a broader supply-chain model whose levels must be evaluated carefully. Next you will build, attest, download, and verify a real disposable artifact.

Official references

• Artifact attestations — concepts
• Using artifact attestations
• GitHub CLI — gh attestation verify
• Repository attestations REST API
• SLSA v1.2 specification
• SLSA Build track basics