Build Provenance and Artifact Signing

Trust the release path

A release inherits trust from source control, reviewers, dependencies, build workers, scripts, secrets, artifact storage, registries, and deployment systems. Protecting only the repository leaves other substitution paths open.

Map every transition where bytes or authority can change: commit, review, dependency retrieval, build, test, signing, upload, promotion, and deployment. Identify human and workload identities, mutable tags, external actions, runner images, caches, and secrets. A protected branch cannot prevent a compromised build worker from substituting an artifact. Prioritize controls at points that can affect many releases or bypass later verification.

Record how the artifact was built

Provenance should connect an artifact digest to source, builder identity, inputs, parameters, environment, and process. The assurance value depends on who generated the statement and whether the producer was isolated from the subject it describes.

Record the exact source revision, build definition, dependencies or materials, builder platform, invocation, timestamps, and output digest. A statement generated by an uncontrolled script on a developer laptop offers less assurance than one produced by a hardened build service with restricted identities. Define the threat being addressed and the required provenance policy. Completeness, authenticity, and non-forgeability are separate properties.

Sign identities and assertions carefully

A signature proves control of a signing identity over specific bytes or an assertion. It does not prove the content is safe. Protect keys, constrain signing authority, record transparency where appropriate, and define rotation and revocation.

Prefer automated, short-lived signing identities tied to an authorized workflow where the ecosystem supports them. For persistent keys, use protected storage, least privilege, multi-party controls for high-impact release authority, and monitored use. Bind signatures to immutable digests, not only mutable names or tags. Verifiers need trusted roots, identity constraints, validity rules, and revocation or incident procedures; collecting signatures without an enforcement decision adds ceremony rather than control.

Verify at the deployment boundary

Verify the exact artifact digest and required provenance policy before promotion or deployment. Fail safely when identity, signature, source, builder, or dependency conditions do not match. Log both acceptance and override decisions.

Enforcement belongs at a boundary the producer cannot bypass casually, such as registry admission, promotion, or deployment. Check that the signer is authorized for this project, the source repository and revision are expected, the builder meets policy, required tests or reviews occurred, and the artifact matches the attested digest. Overrides should be rare, time-bounded, independently approved, and visible, with compensating controls and a plan to restore normal verification.

Respond to broken trust

Suspected secret or build compromise requires scoping affected identities, artifacts, releases, consumers, and time. Pause unsafe promotion, preserve evidence, rotate authority, rebuild through a trusted path, and communicate third-party vulnerability exposure.

Determine the earliest plausible compromise, which workflows used the identity or runner, which artifacts were signed or published, and where they were deployed or downloaded. Do not “fix” a questionable release by signing the same unknown bytes again. Restore trusted infrastructure, correct source and dependencies, rebuild reproducibly where possible, issue new provenance, and revoke or mark affected releases. Consumers need precise digests, versions, actions, and uncertainty—not only notice that a key changed. If rebuilds differ, investigate the cause before promotion; nondeterminism may be benign, but it weakens the evidence needed to connect reviewed source to released bytes.