Artifacts, Retention, Cross-Job Data, and Workflow Result Management: Configuration, Design Patterns, and Trade-Offs

1. Start from the data contract

Every persisted value should answer: who produces it, who consumes it, how large it is, whether it must survive the job/run, whether it is authoritative evidence, and whether it may contain sensitive data. That contract determines the transport.

2. Artifact versus cache versus output

3. “Immutable” means identity changes when content changes

Current upload-artifact behavior does not append new files to an existing artifact record. A same-name upload fails by default. If overwrite: true is enabled, the action deletes the artifact with that name and creates a new one. That means a new ID/digest and a different lifecycle record.

For auditability, prefer unique names such as tests-${{ github.run_id }}-${{ matrix.os }} and preserve IDs. Use overwrite only when replacement semantics are genuinely desired and the old evidence is not required.

# Evidence-friendly
name: tests-${{ github.run_id }}-${{ matrix.os }}
overwrite: false

# Replacement semantics: old record is deleted, new record is created
overwrite: true

4. Short versus long retention is a governance decision

5. Compression affects latency and cost, not correctness

Upload-artifact supports compression levels 0–9, with 6 as the normal default. Highly compressible text benefits from higher compression; already-compressed binaries often waste CPU at high levels. Record non-default compression when performance comparisons matter, but do not treat compression as encryption.

6. Cross-run and cross-workflow downloads raise the trust bar

Downloading from the current workflow run can use the action's current-run context. Downloading from another run/repository requires an explicit token and run/repository identifiers. Treat the selected run as untrusted input until you prove its event, repository, head SHA and workflow trust.

- name: Download from an explicitly selected run
  uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
  with:
    name: verified-build
    github-token: ${{ github.token }}
    repository: ${{ github.repository }}
    run-id: ${{ inputs.source_run_id }}
    path: ${{ runner.temp }}/incoming
    digest-mismatch: error

7. Artifact digest and artifact attestation are complementary

The upload/download digest gives integrity for the GitHub artifact record. An artifact attestation is a signed provenance statement that ties a subject digest to build identity such as repository, workflow and commit claims. For releasable software, consumers must verify the attestation for it to provide security value. Chapter 23 covers attestations/SBOM provenance in depth.

8. Worked design scenario

A library tests Linux/Windows, publishes test reports, and creates a release tarball on tags. Use unique per-cell short-retention test artifacts, aggregate their evidence, then produce one release artifact with longer retention and an attestation. Do not reuse a dependency cache as release storage. The release pipeline should record exact source SHA, producing run, artifact ID/digest and attestation verification instructions.

Knowledge check

Official references and version notes

• GitHub Docs — Workflow artifacts — artifact purpose, cache distinction and attestation context.
• GitHub Docs — Store and share data with workflow artifacts — upload/download, retention, cross-job transfer and digest validation.
• GitHub REST API — Actions artifacts — artifact ID, size, digest, expiration, download and delete endpoints.
• actions/upload-artifact v7.0.1 — upload action pinned to 043fb46d1a93c77aae656e7c1c64a875d1fc6a0a.
• actions/download-artifact v8.0.1 — download action pinned to 3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c.
• GitHub Docs — Artifact attestations — signed provenance is separate from ordinary artifact storage/digest verification.