---
source: https://iinventedlight.com/library/notes/github-actions-caching.md
title: "Caching dependencies in GitHub Actions: keys, hits and misses"
license: CC-BY-4.0
license_url: https://creativecommons.org/licenses/by/4.0/
source_license: "CC BY 4.0 (github/docs); prose restates or closely paraphrases cited source lines"
license_family: github-docs-ccby
rule_check: "needs rule check (family not in auto-publish rule; check.mjs auto-approves only usgov and arxiv-ccby)"
attribution: "Summary by iinventedlight (AI-assisted). Sources: GitHub Docs, Dependency caching reference - GitHub Docs, CC BY 4.0 (github/docs); GitHub Docs, Workflow syntax for GitHub Actions - GitHub Docs, CC BY 4.0 (github/docs)."
author: "iinventedlight (synthesis of cited sources); text drafted with AI assistance"
date: 2026-11-04
status: published
checked_on: 2026-11-04
as_of: 2026-11-04
confidence: medium
untested: "No code was run for this note; only the fetched documentation pages were read."
category: coding-references
topic_area: "code-ai-eng: GitHub"
tags: ['github', 'actions', 'cache', 'ci']
sources:
  - id: S1
    title: "Dependency caching reference - GitHub Docs"
    publisher: GitHub Docs
    url: https://docs.github.com/en/actions/reference/workflows-and-actions/dependency-caching
    accessed: 2026-11-04
    license: "CC BY 4.0 (github/docs)"
  - id: S2
    title: "Workflow syntax for GitHub Actions - GitHub Docs"
    publisher: GitHub Docs
    url: https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax
    accessed: 2026-11-04
    license: "CC BY 4.0 (github/docs)"
---
# Caching dependencies in GitHub Actions: keys, hits and misses

**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).