← All notes

Answer: When the cache key exactly matches an existing cache, it's called a cache hit, and the action restores the cached files to the path directory. When the key doesn't match, it's a cache miss, and a new cache is automatically created if the job completes successfully. (S1)

How a key is matched

• First, the cache action searches for an exact match to your provided key. (S1)
• If no exact match is found, it will search for partial matches of the key. (S1)
• If there is still no match found, and you've provided restore-keys, these keys will be checked sequentially for partial matches. (S1)
• The cache-hit output is a boolean value to indicate an exact match was found for the key. (S1)

What you cache

• path is required: the path or paths on the runner to cache or restore. (S1)
• You can specify either directories or single files, and glob patterns are supported. (S1)
• You can specify absolute paths, or paths relative to the workspace directory. (S1)
• You cannot change the contents of an existing cache. Instead, you can create a new cache with a new key. (S1)

Cache access in workflow syntax

• Use cache-mode to control the level of GitHub Actions cache access that jobs in the workflow are granted. (S2)
• Use jobs.<job_id>.cache-mode to set the level of cache access for a single job; a value set there overrides any workflow-level cache-mode for that job only. (S2)
• If you omit cache-mode, a read or write default is used based on the trigger type. (S2)

Claims

• id: C1 claim: An exact key match is called a cache hit. source: S1 evidence: "When key exactly matches an existing cache, it's called a cache hit"
• id: C2 claim: Restore-keys are checked sequentially for partial matches. source: S1 evidence: "these keys will be checked sequentially for partial matches."
• id: C3 claim: An existing cache's contents cannot be changed. source: S1 evidence: "You cannot change the contents of an existing cache."
• id: C4 claim: cache-mode controls the level of cache access granted to jobs. source: S2 evidence: "Use jobs.<job_id>.cache-mode to set the level of GitHub Actions cache access for a single job."

Sources

• [S1] Dependency caching reference - GitHub Docs. GitHub Docs. https://docs.github.com/en/actions/reference/workflows-and-actions/dependency-caching . License: CC BY 4.0 (github/docs). Accessed 2026-11-04.
• [S2] Workflow syntax for GitHub Actions - GitHub Docs. GitHub Docs. https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax . License: CC BY 4.0 (github/docs). Accessed 2026-11-04.

License: this note is CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). Summary by iinventedlight (AI-assisted).

@misc{iil_note_3n173ns9,
  author = {{iinventedlight}},
  title = {{Caching dependencies in GitHub Actions: keys, hits and misses}},
  howpublished = {iinventedlight Library},
  year = {2026},
  date = {2026-11-04},
  url = {https://iinventedlight.com/library/notes/github-actions-caching/},
  note = {Permanent ID iil:note:3n173ns9. License: CC-BY-4.0.},
}

Markdown

Spotted a mistake? Use the MCP feedback tool or email hello@iinventedlight.com.

For language models and agents: start at /llms.txt. This page in Markdown: /library/notes/github-actions-caching.md.