Document that artifacts must be final before attesting (attest, then don't modify)

Open Beginner friendly
#541 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
1/5
Estimated time
1-3 hours
Newbie friendliness
87/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
github-actions, typescript

Research direction

Update the README after the input table with guidance that artifacts and checksum files must be final before attestation, using the proposed workflow example in the issue. Start by reviewing the existing README structure and wording around action inputs. Done means the README explains the ordering risk and shows attestation before upload; no behavior change is requested.

Written by the indexing model from the issue text.

Description

Summary

The README never says when to run the action relative to producing and uploading the artifact. Because the subject digest is computed from the file as it exists at that moment, any step that rewrites the artifact afterwards leaves a release whose bytes do not match its attestation. The attest step stays green; gh attestation verify fails for end users.

Nothing re-reads or re-checks the file after hashing, so there is no warning at build time. This is an ordering/dependency problem rather than a bug in the parser — most likely it just needs documenting.

Proposed addition

A short note in the README, e.g. after the input table:

### When to run this action

The subject digest is calculated from the artifact as it exists when this action
runs. Anything that rewrites the artifact afterwards — stripping, re-zipping,
re-signing, timestamp normalization, regenerating checksums — produces a file
whose digest no longer matches the attestation. The action still succeeds;
`gh attestation verify` will not.

Attest as the last thing before upload:

```yaml
- name: Build
  run: ./build.sh
- uses: actions/attest@v4      # artifact is final here
  with:
    subject-path: dist/app.tar.gz
- uses: actions/upload-artifact@v4
  with:
    path: dist/app.tar.gz
```

If a step must run after the artifact is final, attest against the result of that
step instead, or bump the digest and re-attest.

The same applies to the file passed to subject-checksums: generate it once the artifacts are final, and don't regenerate it afterwards.

Evidence

Reproduction on main — 400 MB artifact, in-place overwrite (r+) 60 ms into the run, no network needed:

digest recorded:      aea46490f69b60d82a2e6b537a71ca441eed8533079497fc23289f03290eec95
sha256(artifact A):   c4d70844022522bf116937adda94e1f08753ba85ceafbcb4f2bd5899beb50fe6
sha256(shipped file):099c3a4219b3d466f6009acc82499a1b5c606bcfc61a69cc3df7bfebb64e66ce
recorded == any file on disk: false

Through run() with mocked network, the same setup gives setFailed not called, the bundle written to bundle-path carrying the stale digest, and attestation-id set — i.e. a green step and a signed attestation for bytes that are no longer on disk.

The only signal is at verify time: no attestations found / 404, which reads like "not attested" rather than "artifact changed after signing".

Not asking for

No behaviour change. A pre/post stat comparison (size/mtime) that fails or re-hashes would catch the obvious cases, but a stale digest is not always detectable, so the ordering guidance is the part that actually helps.

Dominant language
TypeScript
Stars
187
Forks
65
Avg merge
3d 8h
Merged PRs (30d)
8

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from actions/attest

All issues in actions/attest

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.