GitHub Actions Cache Config Generator

Ecosystem preset:

Changing the preset replaces ecosystem-owned sample fields; your other workflow choices stay intact.

Cache implementation:

Presets without supported setup caching resolve safely to manual actions/cache output.

Dependency file path(s):

Use repository-relative paths or globs. Multiple lines support monorepos.

Cache path(s):

One cache path or glob per line.

{{ selectedPreset.cacheLabel }}:

Cache key prefix:

Use letters, numbers, dots, underscores, or hyphens.

Restore key policy:

Restore keys are ordered from most specific to broadest.

Output scope:

A job includes triggers, contents permission, runner, checkout, cache, and install steps.

Fix cache inputs

{{ issue.message }}

Workflow name:

Used only for Minimal workflow job output.

Job id:

Use a stable machine-readable job key.

Runner label:

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

Runtime version:

Passed to the selected setup action when it declares a version input.

Setup action ref:

Used only when setup-action caching is supported and selected.

Cache action ref:

Used for manual cache and split restore/save output.

Install command:

Emitted after cache restore. Multi-line commands use a YAML block.

Working directory:

Leave blank for repository root.

Branch key expression:

Used only by Branch then ecosystem fallback.

Cross-OS archive:

Manual cache only; Windows self-hosted runners need GNU tar and zstd.

Self-hosted runner:

Adds runner-version and archive-tool checks to the ledger.

Skip install on exact hit:

The safe default still runs install after partial restore-key matches.

Read-only contents permission:

Applies only to Minimal workflow job output.

{{ values.yaml_text }}

The chart renderer is unavailable. The same plan counts remain available in the ledger.

Setting	Current value	Review note	Copy
{{ row.label }}	{{ row.value }}	{{ row.note }}

A dependency cache is shared state that crosses workflow runs. It can shorten installation when the restored files match the current dependency plan, but an overly broad key can return stale content and an unsafe path can expose material that should never leave one job.

Most dependency caches need three ingredients: the directories worth reusing, an exact key that changes with the operating system and dependency files, and optional restore prefixes for compatible older entries. The install command normally still runs after a partial restore so the package manager can reconcile cached downloads with the current lockfile.

GitHub Actions caching approaches
Approach	Useful for	Tradeoff
Setup-action cache	Supported package managers with conventional lockfiles and cache stores.	The setup action owns key and restore behavior.
Manual cache	Custom paths, explicit keys, restore prefixes, and cross-OS archives.	The workflow author owns path safety and key design.
Split restore/save	Jobs that need separate restore, install, and conditional save steps.	More YAML and another condition to review.
Exact key only	Workloads where stale fallback data is worse than a cache miss.	Lockfile changes create more misses.

Lockfiles are strong cache-key inputs because they change when resolved dependencies change. Source files usually should not drive a dependency-store key, and generated dependency directories such as node_modules are often less portable than the package manager's download store.

Cache matching is not a validity check. An exact key match identifies the requested cache entry; a restore-key match returns the newest compatible prefix match. Neither result proves that a build is correct, so tests and package-manager integrity checks remain part of the workflow.

Credentials, tokens, environment files, SSH keys, and keychain data do not belong in cache paths. Cache access follows repository and branch rules, and workflows handling untrusted contributions need the same careful review as any other shared build artifact.

How to Use This Tool:

Start from the package ecosystem, then review the generated key and paths as security-sensitive workflow input.

Choose an Ecosystem preset. It loads representative dependency files, cache paths or setup inputs, runtime versions, action references, and install commands.
Select Setup-action cache, Manual actions/cache step, or Split restore/save steps. A preset without supported setup caching resolves to manual output and reports that change.
Confirm every dependency path and cache path against the repository layout. Use one line per path or glob and remove any credential, secret, environment, SSH, or keychain path.
Choose a restore policy. Use exact dependency hash only for strict isolation, ecosystem fallbacks for reusable package stores, or branch then ecosystem fallback when branch-local reuse is important.
Generate a steps block for an existing job or a minimal workflow job. In Advanced settings, review the runner, action references, install command, working directory, and permissions that affect the chosen output.
Read the generated YAML, primary key, ordered restore keys, and review warnings. Resolve warnings before committing, then run the workflow on a cache miss and a later cache hit.

Interpreting Results:

Ready means the generated values passed local validation and no repo-authored warning rule fired. It does not confirm that paths exist, dependency files match a glob, action versions satisfy organizational policy, or the target runner supports them.

The displayed primary key is exact for manual and split modes. Setup-action mode reports that key ownership remains with the selected setup action.
Restore keys are searched in order from specific to broad. A partial restore is not an exact cache hit.
cache-hit == 'true' indicates an exact primary-key match for manual cache output. Partial restores should still run the install step.
A zero-warning result still needs repository review for trust boundaries, path scope, runner compatibility, and workflow correctness.

Technical Details:

GitHub Actions cache lookup combines a user key with cache version and branch scope. For manual output, dependency-file hashes make an exact key change when the selected files change. Restore prefixes deliberately remove some specificity so a compatible older entry can be used after an exact miss.

Transformation Core:

Cache configuration transformation stages
Stage	Generated behavior
Preset resolution	Load ecosystem-specific lockfile paths, cache targets or setup inputs, runtime, action reference, and install command.
Mode resolution	Keep setup mode only when the preset defines a supported setup cache; otherwise emit manual caching.
Key assembly	Combine the key prefix, `runner.os`, optional branch expression, and `hashFiles(...)` result for manual and split modes.
Restore plan	Generate zero to three ordered prefixes according to strict, ecosystem, or branch policy.
YAML composition	Add checkout, the selected cache path, and the install step; a minimal job also adds triggers, runner, and optional read-only contents permission.

Manual and split keys use the following readable shape: prefix-${{ runner.os }}-[optional branch]-${{ hashFiles('dependency files') }}. Multiple dependency files become arguments in the same hashFiles expression. Repeated path lines are removed case-insensitively before generation.

Rule Core:

GitHub Actions cache generation rules
Selection	Exact result
Setup-action cache	Emit the ecosystem setup action with runtime, cache input, and dependency path, followed by the install command.
Manual cache	Emit one `actions/cache` step with paths, exact key, optional restore prefixes, and optional cross-OS archive flag.
Split restore/save	Emit restore, install, and save actions. Save runs with `always()` when the restore was not an exact hit.
Ecosystem fallback	Restore with `prefix-runner.os-`, then `prefix-`.
Branch fallback	Restore with branch-specific, operating-system, then ecosystem prefixes.
Strict policy	Emit no restore keys; only the exact dependency hash can match.

Key prefixes accept 1 to 64 letters, numbers, dots, underscores, or hyphens. Dependency and cache path blocks allow up to 1,200 characters each. The branch policy accepts one simple GitHub context expression, and action references must have an owner/name and ref.

The presets currently emit actions/checkout@v7, use actions/cache@v5 for manual caching, and select current setup-action majors recorded by the page. Action runtime and runner requirements can change, so review these references before committing generated YAML.

Security Notes:

Cache contents may be available to later workflow runs within GitHub's cache access rules. Do not use a dependency cache as secret storage or as a substitute for artifact provenance.

Generation stops when cache paths resemble environment files, credential stores, secret or token paths, SSH keys, or keychains.
Review workflows triggered from forks or other low-trust sources before allowing cache writes.
Cross-OS archive is meaningful only for manual or split cache output; setup-action cache ignores that option.
actions/cache@v5 requires a compatible Actions runner. Self-hosted Windows cross-OS use also requires appropriate GNU tar and zstd tooling.

Worked Examples:

Node npm monorepo

Choose Node.js npm with setup-action caching and list each package lockfile under Dependency file paths. The generated setup step passes those paths to the setup action and runs npm ci afterward. Confirm the lockfile globs resolve in the repository and remember that the setup cache stores npm package data rather than node_modules.

Manual cache with a partial restore

A manual PHP Composer cache with ecosystem fallbacks first searches the exact operating-system and lockfile hash, then broader operating-system and ecosystem prefixes. If a fallback restores an older cache, cache-hit is not true, so the Composer install step still reconciles the store with composer.lock.

References:

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