GitHub Actions cache: dependencies, keys, and cache hits

A warm workflow restores the dependency store from the GitHub Actions cache before the install step. The setup action's cache: input owns the path and key for common package managers; an explicit actions/cache step exposes path, key, and optional restore-keys for custom stores and build outputs. Most ecosystems have a first-class hook: cache: on actions/setup-node (npm, pnpm, yarn), actions/setup-python (pip, pipenv, poetry), actions/setup-go (the module and build caches), and actions/setup-java (maven, gradle). Set that input explicitly rather than relying on a default: actions/setup-node v5 began auto-caching when it detected a package manager, and v6 narrowed that to npm only (and only when package.json names npm in packageManager or devEngines.packageManager), so a pnpm or yarn repo that never sets cache: gets no cache at all. Cargo has no built-in hook, so key an actions/cache step on Cargo.lock yourself.1234

# Take the block for your ecosystem. Each one keys the cache on the lockfile,
# so an unchanged lockfile restores instead of reinstalling.
steps:
  - uses: actions/checkout@v7

  # Node (npm / pnpm / yarn): setup-node caches the package manager's store.
  # From setup-node v6, only npm is cached automatically (and only when
  # package.json names npm in "packageManager"). pnpm and yarn still need
  # this explicit cache: input.
  - uses: pnpm/action-setup@v6
    with:
      version: 10   # required unless package.json sets "packageManager"
  - uses: actions/setup-node@v6
    with:
      node-version: 22
      cache: pnpm                  # keyed on pnpm-lock.yaml
  - run: pnpm install --frozen-lockfile

  # Python: setup-python caches the pip download cache
  - uses: actions/setup-python@v6
    with:
      python-version: "3.13"
      cache: pip                   # keyed on requirements.txt

  # Go: setup-go caches the module + build cache, keyed on go.sum
  - uses: actions/setup-go@v6
    with:
      go-version: "1.24"
      cache: true

  # Java: setup-java caches the Gradle or Maven dependency store
  - uses: actions/setup-java@v5
    with:
      distribution: temurin
      java-version: "21"
      cache: gradle                # or: maven

  # Rust: no built-in hook. Cache the resolved registry and the build dir, keyed on
  # Cargo.lock. Copy actions/cache's Rust example and note the two traps.
  - uses: actions/cache@v6
    with:
      # Not the whole ~/.cargo/registry: registry/src and git/checkouts are unpacked
      # from the cached archives, so caching them stores the same bytes twice.
      path: |
        ~/.cargo/bin/
        ~/.cargo/registry/index/
        ~/.cargo/registry/cache/
        ~/.cargo/git/db/
        target/
      key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
      # NO restore-keys here, deliberately. A prefix fallback restores a target/ built
      # against a DIFFERENT Cargo.lock, then saves it again under the new key: the stale
      # artifacts never get evicted and the cache grows without bound. A cache miss on a
      # dependency change is the correct outcome.

Every run pays the full install cost, and it multiplies across every matrix leg and shard.

steps:
  - uses: actions/checkout@v7
  - uses: pnpm/action-setup@v6
    with:
      version: 10   # required unless package.json sets "packageManager"
  - uses: actions/setup-node@v6
    with:
      node-version: 22       # no cache: key, and setup-node never auto-caches
                             # pnpm, so nothing is restored
  - run: pnpm install        # re-downloads every dependency, every run

Django, Infisical, and Immich restore package-manager or browser caches before install and browser setup, so dependency downloads and Playwright installs are reused instead of repeated.

              with:
                  node-version: "22"
                  cache: "npm"
                  cache-dependency-path: backend/package-lock.json

      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v6
        with:
          python-version: ${{ matrix.python-version }}
          cache: 'pip'

      - name: Setup Node
        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
        with:
          node-version-file: '.nvmrc'
          cache: 'pnpm'

On Better Auth, StarSling agents closed two caching gaps: a turbo setting that silently disabled the local build cache so actions/cache had nothing to persist, and Playwright browsers reinstalling on every E2E run.

• Read the Better Auth customer story
  Customer story

  Merged 2026-02-13

  chore: fix turbo cache configuration in ci

  StarSling found that setting TURBO_CACHE to remote:rw disabled Turborepo's local cache, so .turbo was never written and the actions/cache save step had nothing to store; removing the override restored the local-plus-remote default so the build cache persists across runs.

  Read the Better Auth customer storyView PR #7950 in better-auth/better-auth (opens in new tab)
• Read the Better Auth customer story
  Customer story

  Merged 2026-02-20

  chore(ci): optimize Playwright browser installs in E2E

  StarSling added a composite setup-playwright action so E2E jobs reuse the Playwright browser install work instead of repeating it on every run.

  Read the Better Auth customer storyView PR #8073 in better-auth/better-auth (opens in new tab)

An exact key match is a cache hit. If the exact key misses, GitHub searches partial matches and then each restore-keys prefix in order within the cache scopes the run can access: the current branch and default branch, plus the pull request's base branch for a pull_request run. Put the runner OS, toolchain, and lockfile hash in the primary key so incompatible dependencies do not collide. Keep restore prefixes intentionally broad, and still run the install after a partial restore because that cache may not contain the current lockfile's complete dependency set. For an explicit actions/cache step, cache-hit is true only for an exact primary-key match, false for a partial restore, and empty when nothing was restored.

actions/setup-node derives its cache key from the package manager lockfile it finds at the repository root by default. In a workspace or monorepo, that may not be the lockfile that changed, or there may be several. Set cache-dependency-path to the real repo-relative lockfile path, such as pnpm-lock.yaml, packages/*/package-lock.json, or a multi-line list, so the key tracks the dependencies each job installs. actions/setup-python has the same input for requirements, pipenv, and poetry files outside the root.

Start with the cache action's log and the evaluated key. Repeated misses usually mean the lockfile hash or another key segment changes every run, the configured path is not the package manager's real store, or branch and cache-version scope prevent a match. Cache version includes the cached path and compression tool, so identical text keys can still name incompatible entries. Confirm a warm run restores the expected path, check cache-hit when you use actions/cache, and remember that a new entry is saved only after a cache miss and a successful job.

Reinstalling dependencies from scratch wastes minutes on every job, and the waste multiplies across every matrix leg and shard. The one caveat to size honestly: caching only helps runs whose lockfile is unchanged (most PRs, re-runs, and dependabot bumps aside), so measure your real cache-hit rate rather than assuming every run benefits. Building Docker images in the same pipeline? Layer caching is the container-side analog, covered in Docker builds in GitHub Actions.

Hand this prompt to your coding agent (Claude Code, Cursor, and the like) to audit and fix this practice in your own repo.

Inspect this repo's .github/workflows for dependency caching. For every job that installs packages (npm, pnpm, yarn, pip, cargo, go, gradle, maven), check whether a cache is configured: a `cache:` key on `actions/setup-node` / `setup-python` / `setup-go`, an explicit `actions/cache` step, or a language-specific cache action. Flag any install step (`pnpm install`, `pip install`, `cargo build`, etc.) that has no matching cache restoring its store, and confirm the cache key is derived from the lockfile so it actually hits. Add the right cache hook keyed on the lockfile, then show me the diff and open a PR rather than applying it blindly.

Ground these changes in the upstream docs before you edit: https://docs.github.com/en/actions/reference/workflows-and-actions/dependency-caching, https://github.com/actions/cache. If you cannot fetch them, say so rather than guessing, and cite what you used in the PR description.

If you do not know why a run is slow yet, start with the diagnostic guide. Let an agent find which of these applies: /ci-speedup. If your workflows are already optimized but still slow, see our guide to fast GitHub Actions and GitHub Actions runner alternatives. Building containers in CI? The Docker workflow guide covers layer caching end to end. Want to see how your configuration measures up before changing anything? CI Score grades workflow config against a pass/fail rubric of these practices. It is not a speed measurement. To find exploitable workflow paths before attackers do, ci-secure checks the ten critical GitHub Actions attack vectors and lets you choose which fixes to apply.

• GitHub Actions too slow
• Fast GitHub Actions
• GitHub Actions alternatives
• GitHub Actions pricing
• Self-hosted GitHub Actions runners
• Docker CI on GitHub Actions
• Install the free /ci-score skill to improve your GitHub Actions setup
• Install the /ci-secure skill to close critical attack vectors in GitHub Actions
• Browse GitHub Actions agent skills