GitHub Actions Cache Config Generator

Ecosystem preset:

Choose the package manager or build cache that owns the dependency files.

Cache implementation:

Use setup-action cache for normal package managers; use manual cache for custom paths or build outputs.

Dependency file path(s):

Use monorepo paths or globs when multiple packages should share one cache key.

{{ setupCacheLabel }}:

Cache path(s):

Cache package-manager download stores and build caches, not secrets or generated credentials.

Cache key prefix:

Keep this short and tied to the ecosystem or package manager.

Restore key policy:

Prefix restore keys are useful for dependency caches; strict mode only restores exact hashes.

Output scope:

Choose whether you want a paste-in steps block or a minimal runnable job.

Fix cache inputs

{{ error }}

Review before committing

{{ warning }}

Workflow name:

This appears in the GitHub Actions run list.

Job id:

Use a stable id if branch protection or required checks reference this job.

Runner label:

Examples: ubuntu-latest, windows-latest, macos-latest, or self-hosted labels.

Runtime version:

Leave as the preset sample or use your project version.

Setup action ref:

Examples: actions/setup-node@v6, actions/setup-python@v6, actions/setup-java@v5.

Cache action ref:

The current official cache action major is used in the sample default.

Install command:

Use the deterministic install command that refreshes dependencies on cache misses or partial restores.

Working directory:

Example: frontend or packages/api.

Branch key expression:

The default expression keeps branch-specific keys while restore keys fall back wider.

Enable cross-OS archive:

Leave off unless you have verified GNU tar and zstd on self-hosted Windows runners.

Self-hosted runner:

Turn on when your workflow runs outside GitHub-hosted runners.

Skip install on exact hit:

Use only when exact cache hits make dependency installation unnecessary.

Read-only contents permission:

Recommended for ordinary checkout and setup steps.

{{ yamlOutputDisplay }}

Item	Value	Why it matters	Copy
{{ row.item }}	`{{ row.value }}`	{{ row.note }}

Check	Status	Detail	Copy
{{ row.check }}	{{ row.status }}	{{ row.detail }}

Embed:

Customize

Include current inputs

Size

Advanced

Width

Height

Aspect ratio

Max height

Collapsible embed

Allow fullscreen

Referrer policy

Sandbox tokens

Dependency installation can dominate a continuous integration run when every job downloads the same packages again. GitHub Actions caching reduces that repeat work by saving package-manager stores or build caches after one run and restoring them in later runs when the cache key still matches. The cache only helps when the saved paths, key, and restore rules match the project layout.

Lockfiles are the usual anchor for dependency caches because they describe the resolved dependency set. A key based on package-lock.json, pnpm-lock.yaml, poetry.lock, composer.lock, go.sum, or a similar dependency file should change when dependencies change. It should not change just because unrelated source files were edited.

GitHub Actions supports two common cache styles. Setup actions can manage common package-manager caches through their own inputs, which keeps normal Node, Python, Go, Java, Ruby, or .NET jobs shorter. Manual actions/cache steps give more control over paths, restore-key prefixes, cross-operating-system archives, and split restore/save behavior.

Restore keys are useful, but they should be read as fallbacks rather than proof that the restored dependencies are current. A broad prefix may bring back an older compatible cache when the exact lockfile hash misses. Most dependency jobs should still run the install command after a partial restore so the package manager can reconcile the restored store with the lockfile.

GitHub Actions cache configuration choices
Choice	Best fit	Risk to check
Setup-action cache	Common package managers with supported setup-action inputs.	May not expose the same cache-hit control as a manual cache step.
Manual cache step	Custom directories, unusual ecosystems, or explicit key plans.	The wrong path can restore stale files or make jobs slower.
Split restore/save	Jobs that need separate restore, install, and conditional save actions.	The save key must match the restore strategy.
Strict key only	Builds where stale dependency stores are worse than cache misses.	More misses after small lockfile changes.

Cache paths also have a security boundary. Dependency caches should not include secrets, tokens, private keys, environment files, or credential directories because cached files can be restored in later workflow runs.

How to Use This Tool:

Build the snippet from the dependency ecosystem first, then review the key plan and warnings before copying the YAML into a workflow.

Choose Ecosystem preset, such as Node.js npm, Python Poetry, PHP Composer, Go modules, Ruby Bundler, Rust Cargo, .NET NuGet, Java Maven, Java Gradle, or Custom cache. The preset loads typical dependency files, cache paths, setup action refs, key prefixes, runtime versions, and install commands.
Select Cache implementation. Use setup-action cache when the preset supports it and you want the setup action to own restore/save behavior. Use manual actions/cache or split restore/save when the workflow needs explicit cache paths.
Review Dependency file path(s). These paths feed the generated hashFiles(...) expression, so monorepos should include every lockfile that should invalidate the cache.
Set the setup-action cache input or the manual Cache path(s). Remove node_modules, secret-looking paths, and unrelated generated files unless you deliberately need them.
Choose Restore key policy and Output scope. A steps block fits an existing job. A minimal workflow job includes trigger, permissions, runner, checkout, cache, and install pieces.
Use Advanced for workflow name, job id, runner label, runtime version, setup and cache action refs, working directory, branch key expression, cross-OS archive, self-hosted runner review, install-skip behavior, and contents read permission.
Check Cache YAML, Key Plan, and Review Checks. Resolve any Blocked row before copying the generated YAML.

Interpreting Results:

Cache YAML is the paste-ready output, but Key Plan is the safer place to check intent. Confirm the primary key, dependency file list, restore keys, cache owner, output scope, and cache paths before adding the snippet to a real repository.

OK review rows mean the selected inputs are internally consistent. They do not prove that the repository's package manager, runner image, or install command is correct.
Review rows call out choices that may still be valid, such as strict restore policy, broad restore keys, self-hosted runner requirements, install skipping, or node_modules paths.
Blocked rows identify inputs that should not ship, including sensitive-looking cache paths, missing manual cache paths, or missing setup-action cache inputs.
Test the YAML on a branch and inspect the Actions log for exact cache hits, partial restores, and save behavior before relying on the cache for main-branch speedups.

Technical Details:

A GitHub Actions dependency cache is identified by a key and restored into the paths named by the workflow. The primary key is the exact match. Restore keys are prefix fallbacks searched when the primary key misses, usually from most specific to broadest. The broadest prefix should still be narrow enough to avoid unrelated caches.

Dependency paths and cache paths do different jobs. Dependency paths are hashed into the key so lockfile changes invalidate stale entries. Cache paths are directories or package-manager stores restored into the runner and saved after a successful job. Setup-action caches often manage package-manager stores directly, while manual cache steps name the paths explicitly.

Transformation Core:

Cache snippet transformation rules
Input	Generated effect	Review point
Ecosystem preset	Loads default setup action, dependency file paths, cache paths, install command, runtime version, and key prefix.	Confirm the preset matches the repository's actual package manager.
Dependency files	Feed a `hashFiles(...)` expression in the primary key.	Monorepos need every relevant lockfile path.
Restore policy	Emits exact-only, ecosystem-prefix, or branch-plus-ecosystem fallback keys.	Broader fallbacks increase hit chances but may restore older dependency stores.
Cache mode	Chooses setup-action inputs, manual `actions/cache`, or split restore/save subactions.	Manual and split modes require explicit cache paths.
Output scope	Emits either a steps fragment or a minimal workflow job with trigger and permissions.	Paste the fragment at the matching level in the workflow file.

The generated key shape is intentionally readable:

${{ runner.os }}-<key-prefix>-<optional-branch>-${{ hashFiles('<lockfile>') }}

The runner operating system keeps Linux, Windows, and macOS caches separate by default. The key prefix separates ecosystems. The lockfile hash invalidates the cache when dependencies change. When branch restore policy is selected, the branch expression is inserted before the lockfile hash so branch-specific caches can be tried before broader fallbacks.

Mode and Review Rules:

Review rules for GitHub Actions cache snippets
Rule	Why it matters
Manual and split modes need at least one cache path.	Without a path, the cache action has nothing to restore or save.
Sensitive-looking paths are blocked.	Secrets, tokens, SSH keys, environment files, and credential folders should not enter dependency caches.
Self-hosted runners using `actions/cache@v5` receive a runner-version review note.	The current cache action runtime requires a recent Actions Runner.
Cross-OS archives are treated as an advanced choice.	Runner tooling such as tar and zstd must be compatible before cross-OS restores are trusted.
Skipping install on cache hit is marked for review.	Partial restores can still need the package manager to reconcile dependencies with the lockfile.

Worked Examples:

Node.js npm monorepo

Choose Node.js npm, keep setup-action cache, and enter dependency paths such as apps/web/package-lock.json and packages/ui/package-lock.json. Key Plan should show the setup action as cache owner and multiple dependency paths feeding the lockfile hash.

Composer with manual cache

Choose PHP Composer. The preset moves to manual cache output because Composer does not use one of the setup-action cache inputs here. The YAML should include an actions/cache@v5 step with a Composer cache path and a key based on composer.lock.

Sensitive path recovery

If a manual cache path includes a directory such as .env or .ssh, Review Checks blocks YAML output. Remove the sensitive path, keep only the package-manager store or build cache, then check that the YAML reappears.

Self-hosted split restore/save

For a self-hosted runner, use split restore/save only after checking runner version and cache tooling. Keep the runner review note visible until the Actions log confirms restore, install, and save behavior on that runner.

FAQ:

Should I cache node_modules?

Usually no. The review checks mark node_modules for review because package-manager stores are generally more portable than installed project directories.

Why did setup-action cache switch to manual cache?

Some presets do not have a supported setup-action cache input in this generator. In that case, manual actions/cache output is used so cache paths can be stated directly.

Can I skip install when the cache hits?

You can enable that option for manual or split modes, but treat it carefully. Partial restore keys may bring back an older store, and the install command may still need to run.

What should I fix when YAML does not generate?

Open Review Checks and resolve Blocked rows first. Common causes are missing manual cache paths, missing setup cache input, or sensitive-looking paths.

Does the generated YAML guarantee a cache hit?

No. It creates a cache plan from the selected inputs. GitHub Actions still decides hits from existing cache entries, branch and repository scope, key matching, and cache service availability.

Glossary:

Cache key: The string GitHub Actions uses to identify a cache entry.
Restore key: A fallback prefix searched when the exact primary key does not match.
Dependency file: A lockfile or dependency metadata file hashed into the cache key.
Cache path: The directory or package-manager store restored from and saved to the cache.
Setup-action cache: A cache managed through a language setup action's own inputs.
Split restore/save: A workflow shape that uses separate cache restore and cache save actions around the install step.

References:

Dependency caching reference, GitHub Docs.
actions/cache README, GitHub.
actions/setup-node README, GitHub.