Artifacts, Dependency Caching, Logs, Test Reports, Retention, and Workflow Data: Configuration, Design Choices, and Tradeoffs

1. Start with the lifecycle question, not the YAML keyword

Ask whether the data is required for correctness, regenerable, run-scoped evidence, or published distribution. That immediately eliminates common mistakes: a cache cannot be the only copy of a build; a run artifact should not become a permanent dependency registry; logs should not carry large binary output.

2. Cache versus artifact versus package/release asset

3. Cache key granularity: correctness first, reuse second

A useful key normally includes the dimensions that make restored data compatible: operating system or architecture when relevant, toolchain/runtime major version, and a content hash of the lockfile or dependency manifest. Include too little and stale/incompatible content can contaminate builds. Include too much—such as the commit SHA—and every run misses, turning the cache into expensive storage with no acceleration.

# Balanced: OS + runtime generation + dependency content
key: deps-${{ runner.os }}-py3-${{ hashFiles('requirements.lock') }}
restore-keys: |
  deps-${{ runner.os }}-py3-

# Usually too broad for correctness:
# key: deps

# Usually too specific for reuse:
# key: deps-${{ github.sha }}

Restore keys are an explicit compatibility claim. If an older prefix-matched cache can safely seed downloads, use it. If restored bytes must match exactly, omit broad fallback and accept the miss.

4. Cache trust policy must follow trigger trust

Current GitHub cache protections reduce writes from low-trust trigger types into the default-branch scope, and pull-request caches are scoped to the PR merge ref. Still, a workflow should not execute cached scripts blindly. Prefer caching package-manager download stores or compile intermediates whose correctness is verified by manifests/build steps, not authorization tokens or opaque executable bootstrap code.

For privileged deployment workflows, a strong pattern is to restore only caches populated by trusted build triggers—or avoid cache consumption for security-sensitive material entirely.

5. Artifact naming and retention should answer “what run produced this?”

Names should be deterministic enough to understand and unique enough to avoid ambiguity: linux-amd64-test-report-${run_id} is easier to operate than artifact. Include matrix dimensions when several jobs upload similar outputs. Do not put secrets, customer identifiers, or private branch descriptions into names because names themselves become metadata.

Retention should be derived from the operational need: short-lived debugging output, longer-lived release-candidate evidence, or audit-required test records. If an audit policy requires evidence longer than Actions retention permits, export that evidence to an approved system of record rather than pretending a 90-day workflow artifact is permanent.

6. Compression and file semantics are performance choices

Text compresses well but costs CPU at higher compression levels. Already-compressed binaries often waste CPU when recompressed. Current upload-artifact v7 also supports direct single-file upload with archive: false. If Unix permissions/case semantics matter, bundle them deliberately before artifact upload because normal zipped artifact extraction does not preserve executable bits as a source-control/archive format would.

7. Human evidence and machine evidence should reinforce each other

Do not force humans to parse megabytes of logs for a test count, and do not make machines scrape Markdown summaries. Publish both when the workflow serves both audiences.

8. Worked scenarios

9. Storage and cost policy: optimize the cause, not only the quota

Cache thrashing often means the key space is too fragmented or the repository is caching expensive but low-value directories. Artifact growth often means every run stores redundant binaries or debug data for too long. Before buying more storage, inspect cache count/size/last access and artifact retention/usefulness. Increase limits only when the workload justifies it.

Current cache defaults are a 7-day inactivity retention and 10 GB repository limit; customizable cache settings are opt-in and can raise retention/size on eligible accounts. Because these product limits can evolve, production runbooks should point operators to current settings/API instead of hard-coding a permanent capacity assumption.

10. Supply-chain rule: stored CI data is input when consumed later

The moment another job or later workflow restores a cache or downloads an artifact, stored output becomes input. Apply the same questions you would to a dependency: who produced it, from which SHA/event/actor, under what permissions, and can you verify its expected digest/schema? Artifact storage does not convert untrusted output into trusted code.

11. Lesson summary

Choose the surface from the data lifecycle. Cache keys express compatibility and trust. Artifacts express run-scoped evidence and transfer. Packages/releases express publication. Summaries and annotations serve humans; structured reports serve machines. Retention, compression, naming, cost, and sensitivity must follow the operational purpose.

Knowledge check

Further reading — current official GitHub sources

• GitHub Docs — Workflow artifacts concepts
• GitHub Docs — Store and share data with workflow artifacts
• GitHub Docs — Dependency caching reference
• GitHub Docs — Managing caches
• GitHub Docs — Removing workflow artifacts and retention
• GitHub Docs — Workflow commands, annotations, and job summaries
• GitHub Docs — Repository Actions settings and retention
• GitHub REST — Actions artifacts
• GitHub REST — Actions cache
• GitHub REST — Actions permissions / retention
• GitHub CLI — gh cache list
• GitHub CLI — gh run download
• GitHub CLI — gh run view
• Official action — actions/upload-artifact
• Official action — actions/download-artifact
• Official action — actions/cache