Trace Coding Agent Builds Back to Their Workflow

Last reviewed: 2026-08-01

Direct answer

Treat every binary or container produced after a coding-agent change as a named, immutable subject. Record its digest, attach an attestation immediately after the build, and verify that attestation before the release process can promote the subject. The attestation should identify the builder and workflow, the inputs and resolved dependencies, the invocation, and the start and finish times. If any of those checks do not match the release policy, stop the promotion and preserve the failure details for investigation.

This distinction matters: a signature helps prove that an artifact has not changed and is associated with an expected identity, while provenance explains how the artifact was produced. GitHub’s artifact-attestation guidance describes attestations for binaries and container images, plus signed SBOM attestations and GitHub CLI verification. Sigstore’s overview explains how ephemeral signing keys, identity certificates, and a public transparency log support that integrity check. SLSA build provenance supplies the structured description of the builder, build definition, parameters, dependencies, and run metadata.

A practical happy path looks like this:

  1. The agent’s change is built by a known CI workflow, and the workflow records the resulting artifact digest.
  2. The workflow creates an attestation for that exact subject after the build completes.
  3. A release job verifies the attestation and checks the observed builder, workflow type, source revision, and dependencies against the release contract.
  4. Only a passing verification result is promoted. The operator writes a small, sanitized event record and links it to the build run.

The error path is equally important. A missing attestation, a digest mismatch, an unexpected builder, or an incomplete dependency list is a release stop, not a warning to ignore. Keep the artifact quarantined, record a reason code, and ask the owner to rerun the approved workflow or repair the provenance generation step. Do not silently rebuild and substitute a different subject.

Who this is for

This guide is for developers and platform engineers who let coding agents modify a repository and then produce binaries, packages, or container images. It is especially useful for teams that already have CI and a release gate but cannot quickly answer, “Which workflow built this exact file, from which revision, with which dependencies?”

It also helps security reviewers who need a repeatable contract rather than a screenshot of a successful job. Provenance does not replace code review, tests, or an approval decision. It gives those controls a stable object to inspect. For the human-change context around the artifact, pair this workflow with the site’s reviewable diff guidance and its change evidence packet .

Key takeaways

  • Verify the subject, not a moving label. A tag or filename can point at a different object later. Use the digest of the artifact that will actually be promoted.
  • Separate identity from explanation. Signing and transparency evidence help establish who signed an object and whether it changed; provenance records the builder, invocation, inputs, dependencies, and timing.
  • Make the builder part of the contract. A valid attestation from an unapproved workflow is still a release failure.
  • Treat external inputs as reviewable data. SLSA describes external parameters as inputs that must be included and verified downstream. Resolve repository references and fetched dependencies to concrete digests or revisions where the build system can record them.
  • Attest the SBOM when you have one. GitHub documents signed SBOM attestations for workflow artifacts, so the inventory can be checked against the same subject rather than treated as an unrelated file.
  • Keep verification evidence small and safe. Log identifiers, digests, decisions, and reason codes. Never copy environment variables, signing material, or raw agent prompts into the release record.
  • Test the rejection path. A gate that only proves success is not a gate. Exercise missing, stale, and wrong-builder attestations before relying on it for production.

Sources checked

The article uses three public references, each for a different part of the contract:

These references are complementary. GitHub shows an operational attestation path, Sigstore explains the signing and transparency layer, and SLSA gives the data contract that makes a provenance record useful to a verifier.

Contract details to verify

Before adding a release gate, write down the expected values and the fields that may vary. A useful contract has six parts.

Subject. Identify the exact binary, container image, or package by digest. For a container, keep the image name separate from its digest; the name tells the operator what to look up, while the digest binds the verification to one immutable subject.

Builder and build type. Record the approved CI platform and the workflow or build template that is allowed to produce the subject. SLSA’s builder and buildType concepts let a verifier distinguish an approved workflow from an ad hoc local build.

Inputs. Check the source revision, configuration values that affect the build, and resolved dependencies. SLSA calls out externalParameters and resolvedDependencies because an input that is merely named but not pinned is difficult to verify later. A repository branch name is not enough if the build can resolve it to different commits over time.

Run metadata. Retain an invocation identifier and start and finish timestamps. These fields let an operator correlate the attestation with the CI run without copying the entire job log into the release record.

Byproducts and inventory. If the workflow creates an SBOM or another report, attach it to the same subject and verify that the recorded digest describes the artifact the report covers. Do not accept an SBOM generated for a neighboring build.

Verification policy. Define what happens when a field is absent, unexpected, or unverifiable. For example, require the expected builder, reject unknown external parameters, and require a successful signature and transparency check. The policy should produce a clear pass or fail decision rather than a score that someone can interpret differently at release time.

A minimal, sanitized workflow shape can be expressed without embedding credentials:

steps:
  - name: Build artifact
    run: ./ci/build
  - name: Generate artifact attestation
    uses: actions/attest@v4
    with:
      subject-path: dist/application

The exact permissions and runner settings belong in the repository’s workflow policy. The important ordering is that the attestation step receives the artifact produced by the build step, not a path that can be replaced later. After that, a release job can use the documented GitHub CLI verification flow:

gh attestation verify dist/application -R ORG/REPO

The command’s success is only the first check. Compare the verified identity and provenance fields with the contract you wrote. If your release environment is offline, use the platform’s documented offline-verification path and retain the verification bundle as part of the release record.

For every attempt, keep a compact log that is useful to an operator and safe to share:

{
  "event": "artifact_verification",
  "workflow": "build-and-attest",
  "run_id": "run-42",
  "artifact_digest": "sha256:[DIGEST]",
  "source_revision": "commit:[HASH]",
  "builder_id": "ci-platform",
  "result": "pass",
  "reason_code": "verified",
  "verified_at": "2026-08-01T00:00:00Z"
}

Do not add raw environment values, unredacted command output, or agent prompts to this record. If an investigation needs more detail, point to a protected run record using the run identifier and access controls already used by the team.

Failure modes

The digest is different from the released object. This often happens when a mutable tag is rebuilt or when a release job downloads a fresh image instead of the exact build output. Stop, compare the subject digest in the attestation with the digest at the release boundary, and rerun verification against the intended object.

The attestation is missing or arrives late. A retry may finish the build but skip the attestation step, leaving an apparently healthy artifact with no provenance. Keep the subject quarantined and fix the workflow ordering. A release job should not create a replacement attestation for an unknown build after the fact.

The builder is valid but not approved. A developer may have produced a correctly signed local build, yet the release contract may require the protected CI builder. Treat the identity mismatch as a policy failure and rebuild through the approved workflow.

The source reference is broad or the dependency set is incomplete. A branch name, floating dependency, or omitted fetched file prevents a reviewer from reconstructing what the agent’s change actually used. Require the workflow to record concrete revisions or digests where possible, and reject provenance that omits a required input.

The SBOM describes another subject. An SBOM can be present and signed while pointing at a different digest. Verify the SBOM attestation’s subject before using it for release decisions; otherwise the inventory provides false confidence.

Online verification is unavailable. Network failure is not proof that an artifact is bad, but it is also not proof that it is good. Use the documented offline verification process when the release environment supports it. If the required evidence cannot be checked, hold the release and record verification_unavailable rather than converting the error to a pass.

Logs leak sensitive context. Agent runs can contain prompts, file contents, and environment data that do not belong in a release ledger. Keep the sanitized fields above and use a protected reference to the full run. This also makes the record easier to search and share during an incident.

FAQ

Is a signature alone enough? No. A signature can help establish integrity and signer identity, but it does not explain which workflow, inputs, or dependencies produced the object. Pair the signature with provenance and verify both against the release contract.

Do teams need to manage a long-lived signing key? Not necessarily. Sigstore documents an identity-based approach that uses ephemeral signing keys, a short-lived certificate, and a transparency log. The choice still needs an explicit identity and verification policy.

Should the agent itself sign the artifact? Put signing and attestation in the controlled build workflow rather than relying on an agent-provided claim. The workflow is the boundary that can record the actual subject, builder, inputs, and run metadata.

What should happen when a field is unknown? Decide before release day. For security-sensitive fields such as the subject digest, builder, and source revision, an unknown value should fail closed. For optional diagnostic fields, record the omission and decide whether the risk is acceptable.

Does provenance replace review of the agent’s change? No. Provenance answers how the shipped object was produced. Reviewers still need to inspect the change, tests, and release intent. Use the site’s rollback evidence guide to keep a recoverable record when an agent-generated change must be reversed.

Reader next step

Choose one non-production artifact produced by a coding-agent workflow. Write down the expected builder, workflow, source revision, artifact digest, and minimum dependency evidence. Add an attestation step immediately after the build, then run a release check that verifies the subject and compares those fields with the contract. Capture one passing log and deliberately test one rejection, such as an artifact with no attestation or an unexpected builder.

Once the pass and fail paths are both visible, make the verification result a required release condition. Keep the first policy narrow, review the records with the people who approve deployments, and expand it to additional artifact types only after the initial contract is reliable.