Artifacts and caching: passing files between jobs, and the cache that never hits

Artifacts vs cache: two different jobs

They look similar — both store files — but they solve opposite problems:

• Artifacts carry files out of a workflow: build outputs, test reports, coverage, logs — things a human or a later job downloads. Upload with actions/upload-artifact, fetch with actions/download-artifact. They are the only way to pass files between jobs, since each job runs on a fresh runner. Default retention is 90 days (configurable per-upload down to 1 day or set repo-wide), after which they are deleted.
• Cache speeds up future runs of the same work: dependency directories (~/.npm, node_modules, ~/.cargo), build intermediates. Use actions/cache. A cache entry is keyed and immutable once written — and it is best-effort, not guaranteed: under the eviction policy GitHub removes caches not accessed in 7 days, and once a repo’s caches exceed 10 GB total it evicts the least-recently-used entries to stay under the limit.

The mental rule: artifact = “I need this file later or for a human,” cache = “recomputing this is slow and the inputs rarely change.” Never use cache for build outputs you must not lose (it can be evicted at any time); never use artifacts as a speed cache (no key-based restore, and 90-day retention costs storage).

- uses: actions/upload-artifact@v4
  with:
    name: dist
    path: build/
    retention-days: 7      # shrink from the 90-day default for ephemeral builds

- uses: actions/cache@v4
  with:
    path: ~/.npm
    key: npm-${{ runner.os }}-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      npm-${{ runner.os }}-

The cache key is the whole design

A cache key has to do two contradictory things: invalidate when inputs change and hit when they don’t. The canonical pattern resolves it with two fields:

• key must include a content hash of the inputs — hashFiles('**/package-lock.json'). When the lockfile changes, the hash changes, the key changes, and the old cache is correctly not used. A key without a hash (key: npm from the Hook) never changes, so it either serves a stale cache forever or — because writes are immutable — locks in whatever was saved first.
• restore-keys is an ordered list of prefixes tried when the exact key misses. On a lockfile change the exact key won’t exist yet, but restore-keys: npm-${{ runner.os }}- matches the previous cache as a partial hit — so you start from last build’s node_modules and only install the delta, then save under the new exact key. This is what turns a cold cache into a warm one across dependency bumps.

The save semantics catch people: actions/cache saves automatically at job end only if the exact key did not already exist (a cache hit on the exact key means no save). Immutability means you cannot overwrite an entry — to “update” a cache you must change the key. And because of the 7-day-idle and 10 GB-LRU eviction, a rarely-run workflow’s cache may simply be gone, which is correct behavior, not a bug — the cache is an optimization that must tolerate misses.

Sizing and hygiene

Caches and artifacts both cost storage and both have limits that bite at scale. A single cache entry should be the dependency directory, not the whole workspace — caching node_modules plus ~/.npm plus the build output triples the size and pushes you toward the 10 GB LRU cliff faster, evicting other useful caches. Artifacts default to 90-day retention, which for per-PR build outputs is wasteful; drop retention-days to a week or less for ephemeral data, and reserve long retention for releases and audit logs. Compress before uploading large artifacts, and don’t upload node_modules as an artifact at all — that is what cache is for. The discipline is matching each store to its job: durable hand-off → artifact with deliberate retention; speed optimization with tolerated misses → cache with a content-hashed key.