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 is often one of the slowest repeated parts of a continuous integration job. GitHub Actions caching reduces that waste by saving dependency stores or build outputs after one run and restoring them in later runs when the cache key still matches. The difficult part is not adding a cache step; it is choosing the right cache path, key, restore-key fallback, and setup action for the ecosystem.

A good cache key changes when dependencies change and stays stable when source files change without affecting the dependency store. That is why lockfiles matter. Files such as package-lock.json, pnpm-lock.yaml, poetry.lock, composer.lock, go.sum, and packages.lock.json are strong cache-key inputs because they describe dependency resolution rather than application code.

Diagram showing dependency files feeding a primary GitHub Actions cache key, then restore keys falling back to compatible cache entries.

There are two broad cache styles in GitHub Actions. Some setup actions, such as the Node, Python, Go, Java, Ruby, and .NET setup actions, can own cache restore and save behavior through their own inputs. Manual actions/cache steps give more control over paths, restore keys, cross-operating-system archives, and split restore/save flows. The shorter setup-action path is convenient when it matches the ecosystem; the manual path is better when you need custom directories or explicit save behavior.

Restore keys are a useful fallback, but they are also a common source of false confidence. A broad restore key can recover an older compatible cache when the exact dependency hash is missing. It should not be treated as proof that dependencies are current. Install commands should usually still run after a partial restore so the package manager can reconcile the restored files 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` behavior as a manual cache step.
Manual cache step	Custom cache paths, nonstandard ecosystems, or explicit restore-key plans.	Caching the wrong directory can make jobs slower or less portable.
Split restore/save	Jobs that need separate cache restore, install, and conditional save actions.	Save keys must match the restored primary key strategy.
Strict key only	Builds where stale dependency caches are worse than cache misses.	More misses and less speedup after small lockfile changes.

Cache configuration also has a security boundary. Dependency caches should not include secrets, tokens, private keys, environment files, or credential directories. Caches can be restored into future workflow runs, so a path that feels local during one job can become shared state later.

How to Use This Tool:

Build the snippet from the dependency ecosystem first, then tighten the cache key and review checks before copying the YAML.

Choose an Ecosystem preset such as Node.js npm, Python Poetry, Go modules, Composer, Maven, Gradle, NuGet, or Custom cache. The preset loads typical dependency files, cache paths, setup actions, and install commands.
Select Cache implementation. Use setup-action cache when the preset supports it; use manual actions/cache or split restore/save when you need explicit paths and restore behavior.
Review Dependency file paths. These paths feed the generated key through hashFiles(...), so monorepos should include the correct subdirectory lockfiles.
Set Cache paths for manual modes or the setup-action cache input for setup modes. Remove node_modules, secret-looking paths, and unrelated build output unless you deliberately need them.
Choose the 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 options for workflow name, job id, runner label, setup action ref, cache action ref, runtime version, working directory, branch expression, cross-OS archives, self-hosted runner review, and install-skip behavior.
Check Cache YAML, Key Plan, and Review Checks. If a review row is Blocked, fix the input before copying the generated YAML.

Interpreting Results:

The generated YAML is the copyable output, but the Key Plan explains whether the cache will behave the way you expect. Check the primary key, dependency file list, restore keys, and cache paths before pasting the snippet into a workflow.

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

Technical Details:

A GitHub Actions dependency cache is matched by key, scoped by branch and repository behavior, and restored to the paths named by the workflow. A primary key is the most specific identity for the cache. Restore keys are searched when the primary key misses, usually from most specific to broadest. The broadest restore key should still be narrow enough to avoid unrelated caches.

Cache paths and dependency paths are different. Dependency paths are hashed into the key so a lockfile change invalidates stale entries. Cache paths are the directories or package-manager stores restored into the runner. For Node projects, setup-node caches the package manager store and does not cache node_modules. Other ecosystems have similar distinctions between downloaded packages, build caches, and installed project directories.

Transformation Core:

Cache snippet transformation rules
Input	Generated effect	Review point
Ecosystem preset	Loads setup action, dependency file defaults, cache paths, install command, and key prefix.	Confirm the preset matches the actual package manager in the repository.
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 speed 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.

The generated key follows this readable shape in manual modes:

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

The runner operating system prevents Linux, Windows, and macOS caches from colliding by default. The key prefix separates unrelated ecosystems. The lockfile hash makes dependency updates create a new primary key. If the branch restore policy is selected, the branch expression is inserted before the lockfile hash so branch-specific caches can be tried before broader fallback keys.

Validation Rules:

Review rules for GitHub Actions cache snippets
Rule	Why it exists
Manual 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, and environment files should not be placed in dependency caches.
Self-hosted runners using `actions/cache@v5` get a runner-version review note.	The current cache action runtime requires recent runner support.
Skipping install on cache hit is marked for review.	Partial restores can still need the package manager to reconcile dependencies.

Worked Examples:

A Node.js npm monorepo can choose Node.js npm, setup-action cache, and dependency paths such as apps/web/package-lock.json and packages/ui/package-lock.json. The Key Plan should show setup-node as the cache owner and multiple dependency paths feeding the cache key.

A PHP project can choose PHP Composer and manual cache mode. The output should include an actions/cache@v5 step with a Composer cache path and a key based on composer.lock. If the cache path includes a secret-looking directory, the Review Checks tab blocks the output until the path is removed.

A self-hosted runner using split restore/save should keep the runner review row visible until the runner version, tar, and zstd behavior are confirmed. The generated YAML can still be a useful starting point, but the Actions log is the final proof of restore and save behavior.

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 is my setup-action choice switched to manual cache?

Some presets do not have a supported setup-action cache path in this generator. In that case the YAML uses manual actions/cache 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.

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.
Split restore/save: A workflow shape that uses separate cache restore and save actions around the install step.

References:

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