Artifact Attestations, SBOMs, Build Provenance, Verification, and SLSA-Oriented Workflows: Configuration, Design Choices, and Tradeoffs

1. What should be the attestation subject?

Attest the thing a consumer actually receives and makes a trust decision about. If users download a tarball, the tarball digest should be the subject. If a deployment pulls an OCI image, the image digest should be the subject. Signing source files one by one is usually weaker operationally because the deployed package can still differ from those source inputs.

2. Provenance-only versus provenance + SBOM

Build provenance is the minimum evidence when the policy question is builder identity and source/build context. Add an SBOM when consumers must reason about dependencies, licenses, incident impact or component policy. Adding more predicates is not automatically better: each predicate needs a producer, schema, lifecycle and verification rule.

3. Verify at publish time, consumer time, or both?

Producer-side verification catches pipeline mistakes early: wrong subject path, missing attestation, or malformed SBOM. Consumer-side verification is the security boundary that detects substitution after publication. A producer cannot safely replace the consumer’s check because the distribution channel itself may be the thing under attack.

4. Trust policy: repository, workflow, ref, issuer and runner

The strongest policy is not “signature valid.” It states which authenticated identity is allowed to sign this kind of artifact. Current gh attestation verify lets you constrain repository/owner, signer workflow or signer repository, source ref/digest, OIDC issuer and whether self-hosted runners are acceptable.

gh attestation verify artifact.tar   --repo acme/widget   --signer-workflow acme/widget/.github/workflows/release.yml   --source-ref refs/heads/main   --deny-self-hosted-runners

A production policy may prefer a release tag or exact source digest rather than main. Branch trust can be appropriate if branch protections/rulesets and workflow ownership are strong; a source digest is stricter for one release but requires the deployment system to know the expected commit. Choose constraints from the release model, not by copying flags.

5. Central reusable builders and ownership

A central reusable workflow can reduce duplicated build logic and give consumers one reviewed builder identity. GitHub documentation currently describes reusable workflows plus artifact attestations as a way to help achieve SLSA v1 Build Level 3. With cross-repository reusable workflows, the signer is the reusable workflow repository/path; verification therefore needs --signer-repo or --signer-workflow.

6. GitHub feature boundaries versus SLSA

Current SLSA v1.2 still defines Build L1/L2/L3, while GitHub’s artifact-attestation docs specifically phrase their product guidance in SLSA v1.0 terms. A careful production claim should name the SLSA version and track evaluated, document which requirements are supplied by GitHub versus producer workflow design, and avoid implying application-security certification.

7. Worked decision: Atlas Relay release pipeline

Atlas Relay chooses a central reusable builder for release artifacts, pins/controls changes to that builder, requires provenance + SPDX SBOM predicates, and verifies both at deployment. Development/test artifacts are not attested because nobody consumes them across a trust boundary.

8. Minimal production policy template

artifact_policy:
  subject: "exact bytes or OCI digest"
  required_predicates:
    - "https://slsa.dev/provenance/v1"
    - "https://spdx.dev/Document/v2.3"
  signer:
    repository: "acme/build-platform"
    workflow: ".github/workflows/release.yml"
  source:
    allowed_refs: ["refs/heads/main", "refs/tags/v*"]
  runners:
    self_hosted_allowed: false
  verification_points:
    - publish
    - production_deploy
  exception:
    owner: "supply-chain-security"
    expires: "required"
    evidence: "required"

This YAML is a policy design fixture, not a GitHub-native policy file. Its value is forcing the organization to name trust assumptions explicitly before encoding them in a deployment system or policy engine.

Knowledge check

Summary

Choose subjects from what consumers actually install/run, predicates from policy questions, and verification points from trust-boundary crossings. Constrain authenticated builder identity as narrowly as your release model permits. GitHub supplies a strong attestation mechanism, but your workflow architecture, SBOM quality and consumer enforcement determine whether the evidence reduces risk. Next you will diagnose realistic ways those pieces fail.

Official references

• Artifact attestations — concepts
• Using artifact attestations
• Reusable workflows and SLSA Build Level 3
• gh attestation verify
• SLSA v1.2 Build requirements