GitHub has introduced cache-mode for GitHub Actions, giving workflows and individual jobs more precise control over dependency cache access. The feature is generally available on github.com for all GitHub plans as of September 10, 2026.
Instead of relying only on the cache behavior associated with a workflow trigger, teams can now choose whether a workflow may restore caches, save caches, do both, or access the cache at all. That makes it possible to apply narrower permissions to jobs that do not need full cache access and to place explicit limits on reusable workflows.
What changed in GitHub Actions caching
The new setting supports four cache access modes:
read: The workflow or job may restore caches but cannot save new cache entries.write: The workflow or job may restore and save caches.write-only: The workflow or job may save caches but cannot restore them.none: The workflow or job cannot access the Actions cache.
GitHub allows the setting at workflow or job level. A job-level setting takes precedence over a workflow-level setting, so teams can establish a broad default and then give individual jobs a narrower or different access level where necessary.
Workflow files are YAML files stored in the repository’s .github/workflows directory. The supplied documentation confirms the setting’s behavior and its use with calling jobs, but does not provide a complete standalone example covering every supported workflow-level and job-level placement. Teams should therefore check the workflow syntax documentation when applying the setting in a particular file.
Omitting the setting preserves trigger-based defaults
Existing workflows do not automatically receive unrestricted cache access when cache-mode is omitted. In that case, cache access continues to follow a default based on the workflow trigger.
The announcement identifies read access as the default for lower-trust events such as pull_request_target, while trusted events such as push use a write-capable default. The available documentation does not provide a complete event-by-event table, so these examples should not be treated as a universal list of defaults.
Explicit configuration can override the default for a particular context. That flexibility is useful, but it also means that granting write or write-only access to a lower-trust workflow can reintroduce cache-poisoning risk. GitHub adds a warning when a declared mode grants write access in an applicable lower-trust context.
Reusable workflows inherit cache limits
The feature also matters for organizations that centralize CI logic in reusable workflows. A caller can impose an explicit cache limit on the calling job, and that limit constrains what the called workflow may request. A limit inherited from the caller workflow can also restrict the reusable workflow.
For example, a caller that needs to keep a reusable workflow at read access must set cache-mode: read on the calling job, according to the reusable-workflow documentation. The important control remains with the caller: a called workflow cannot obtain broader cache access than the caller explicitly permits.
If a called workflow requests access beyond an explicit caller-imposed limit, GitHub rejects the run with a validation error before execution begins. The modes are capability-specific as well. Because read and write-only provide different, non-overlapping capabilities, a mismatch between those modes can also cause validation to fail.
This behavior gives platform teams a way to review reusable-workflow consumers independently from the implementation of the shared workflow. A reusable workflow may be designed to save or restore caches, but each caller can still determine whether that access is appropriate for its own repository and trigger context.
Why cache access should be treated as a security boundary
GitHub’s dependency-caching documentation warns that restored cache contents should be treated as untrusted input. Caches are shared according to the branch or tag used by the workflow run rather than the identity of the workflow or job. That sharing model makes it important to consider which workflows can write entries that another workflow might later restore.
GitHub also warns that poisoned caches can lead to code execution in trusted workflows and advises against storing secrets or other sensitive data in caches. The new modes do not eliminate that risk, but they provide a more granular way to reduce unnecessary write or restore capability.
In practice, a job that only needs dependencies already produced elsewhere may need read, not write. A job that builds and publishes a cache but should not consume existing cache contents may need write-only. A job with no cache requirement can use none. These choices should be based on the job’s actual behavior rather than applied uniformly without review.
What developers and administrators should do
- Inventory cache usage. Identify which workflows and jobs restore caches, save caches, do both, or do neither.
- Choose the narrowest mode. Use
read,write,write-only, ornoneaccording to the job’s real cache needs. - Review lower-trust triggers. Pay particular attention to explicit write-capable settings on events such as
pull_request_target. Do not assume that changing a default is risk-free. - Use job-level controls where workflows differ. A workflow-level setting can provide a baseline, while job-level settings can handle jobs with different cache requirements.
- Audit reusable-workflow callers. Confirm that the caller’s explicit limit is sufficient for the called workflow, but no broader than intended. Overly narrow or incompatible limits can prevent the run from starting.
- Keep sensitive material out of caches. Treat restored cache contents as untrusted and avoid placing secrets or other sensitive data in cache paths.
The feature is already available on github.com for all GitHub plans. The supplied sources do not establish a minimum runner, repository, workflow, or product version requirement. They also do not establish compatibility with GitHub Enterprise Server, so organizations using that product should not assume support based on this announcement alone.
Availability and remaining documentation limits
GitHub has documented the four access modes, workflow and job precedence, trigger-dependent defaults, and reusable-workflow restrictions. However, the available material does not describe a formal migration procedure for every existing workflow or specify the exact action-level logs produced when ordinary cache restores or saves are denied.
For most teams, the immediate task is a permission review rather than a wholesale redesign: identify jobs that do not need cache writes, apply explicit limits to reusable-workflow callers, and examine any write-capable configuration used with lower-trust events.
