Artifacts, Retention, Cross-Job Data, and Workflow Result Management: Core Concepts and Mental Model

1. The practical problem: the runner disappears but evidence must remain

GitHub-hosted jobs execute on fresh, temporary machines. A build may produce a binary, test report, screenshot, crash dump or manifest that must outlive that runner. Chapter 5 taught job outputs for small structured values; Chapter 12 used artifacts to retain matrix-cell evidence. This chapter defines the full artifact lifecycle so the stored object can be traced back to the exact run and commit that produced it.

An artifact is not “whatever is in the workspace.” It is an explicit selection of paths uploaded to GitHub's artifact service. That selection, its sensitivity, its producing SHA and run, and its retention policy are all part of the data contract.

2. Causal model: filesystem → selection → artifact record → consumer

First, a job creates files on its runner. The upload action expands the configured paths, applies hidden-file policy, packages/compresses the selected content when archival mode is used, and creates a run-scoped artifact record. GitHub assigns an artifact ID and digest. A later job, user or API consumer selects that record, downloads it, verifies integrity, and interprets it in the context of the producing run/SHA. Eventually repository policy expires it or an authorized actor deletes it.

flowchart TD
  A[Runner job filesystem] --> B[Explicit selected paths]
  B --> C[Hidden-file + compression policy]
  C --> D[Upload action / artifact service]
  D --> E[Artifact ID + name + digest + size]
  E --> F[Producing run / job / SHA]
  E --> G[Later job / user / REST API]
  G --> H[Download + digest validation]
  H --> I[Consumer verification / use]
  E --> J[Retention expiry or explicit deletion]

The arrows are trust boundaries. The runner decides what files exist. The workflow decides which paths are eligible. The artifact service gives the upload a durable identity. The consumer must still verify that the identity belongs to the expected run and SHA; a valid digest of the wrong run is still the wrong input.

3. Name the artifact state before moving data

4. Name, ID and digest solve different problems

The name is convenient routing metadata. The artifact ID identifies one artifact record in the repository. The artifact digest records the SHA-256 digest of the artifact payload. For a production evidence packet, keep all three plus the producing run ID and head SHA.

- name: Upload evidence
  id: upload
  uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
  with:
    name: test-evidence-${{ github.run_id }}
    path: evidence/
    if-no-files-found: error
    retention-days: 7
    include-hidden-files: false

- name: Record artifact identity
  shell: bash
  run: |
    printf 'artifact_id=%s
' '${{ steps.upload.outputs.artifact-id }}'
    printf 'artifact_digest=%s
' '${{ steps.upload.outputs.artifact-digest }}'

5. Hidden-file behavior reduces accidents; it does not classify data for you

Current upload-artifact excludes dot-prefixed hidden files and files under dot-prefixed directories by default. This helps prevent accidental upload of files such as .env, but a sensitive file named credentials.txt is not hidden. Conversely, a harmless hidden report may be intentionally excluded unless you opt in.

When include-hidden-files: true is genuinely required, validate the selection and exclude sensitive patterns explicitly. Never rely on log masking to make a secret safe inside an artifact: masking only affects log rendering.

6. Retention is a policy ceiling, not a promise of forever

retention-days requests an expiry for a newly uploaded artifact, bounded by repository, organization and enterprise policy. GitHub's current public-repository range is 1–90 days; private repositories can be configured up to 400 days where higher-level policy allows it. Deleting the workflow run also deletes its artifacts.

Release records that must survive a compliance period should not silently depend on a default 90-day artifact. Choose the retention intentionally, copy durable evidence to an approved records system when required, and document the lifecycle.

7. Artifact, job output and cache are different transports

8. Read-only inspection before changing retention or names

Before editing a workflow, capture the current run and artifact records. The REST artifact object includes the artifact ID, name, size, digest, expiry state, timestamps and producing workflow-run identity including head SHA.

# Read-only: authenticated repository inspection
GH_REPO='OWNER/gha-artifact-lab'
ARTIFACT_ID='123456789'

gh api   -H 'X-GitHub-Api-Version: 2026-03-10'   "repos/$GH_REPO/actions/artifacts/$ARTIFACT_ID"   --jq '{id,name,size_in_bytes,digest,expired,created_at,expires_at,workflow_run}'

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.