feat(cache): add cache-mode client behavior (read-denied warning + ACTIONS_CACHE_MODE skip) by philip-gai · Pull Request #2447 · actions/toolkit

philip-gai · 2026-07-01T18:33:18Z

Description

This PR adds client-side cache-mode behavior to @actions/cache. It combines two related pieces of work:

Surface the service-side read-denied policy as a non-fatal warning.
Honor a new ACTIONS_CACHE_MODE environment variable to skip cache operations the effective mode does not permit.

Cache-mode values are none | read | write | write-only (hyphenated). It is a partial lattice, not linear: readable modes = {read, write}, writable modes = {write, write-only}, none = neither. The ACTIONS_CACHE_MODE env var is provided by the Actions runner, and is gated on the service side. When it is unset or unrecognized, behavior is identical to today (regression-safe).

Read-denied warning

When the cache service denies a download because the token has no readable scopes, the run should continue with a clear warning instead of a confusing failure.

Added CacheReadDeniedError and the shared cache read denied: prefix constant.
On the v2 restore path, the denial arrives as a wrapped 403; the restore dispatch detects the prefix and surfaces it as a core.warning, then returns a cache miss.
Matches the existing write-denied handling (cache write denied:) for consistency.

ACTIONS_CACHE_MODE skip

Skip operations the effective cache-mode does not permit, before any tar or network work.

Skip restore when the mode is not readable (none, write-only).
Skip save when the mode is not writable (none, read).
Restore skip returns a cache miss (undefined); save skip returns the existing not-saved sentinel (-1). Neither throws.
Exactly one core.info line per skip; extra detail (paths, key) is behind ACTIONS_STEP_DEBUG.
Unset or unrecognized modes are permissive, so behavior is unchanged.

Rationale for skipping restore on write-only: write-only tokens have no read scope, so a restore would be denied service-side and trip the read-denied warning. Skipping client-side avoids the wasted round-trip and gives a clearer message.

Companion changes

actions/runner exports ACTIONS_CACHE_MODE into the step environment.

Notes

packages/cache/RELEASES.md updated under the 6.2.0 entry.
Test coverage: full cache suite passing, including the read-denied dispatch and a cache-mode truth table (none/read/write/write-only plus unset and unknown regression cases).

https://github.com/github/actions-persistence/issues/1168

Mirror the existing cache write-denied handling on the restore path. When the receiver refuses a download URL because the run's token has no readable cache scopes, it returns a twirp PermissionDenied (HTTP 403). The twirp client wraps that 403 in a generic Error, so the stable 'cache read denied:' prefix is embedded in the message rather than at the start. - Add CACHE_READ_DENIED_PREFIX and CacheReadDeniedError - Dispatch on the prefix in the restoreCacheV2 catch block (V2 only), log a policy-specific warning, and report a cache miss so the run continues - Add a test mirroring the write-denied coverage

Re-throw CacheReadDeniedError from an inner try/catch around GetCacheEntryDownloadURL and dispatch on typedError.name in the outer catch, matching how saveCacheV2 handles CacheWriteDeniedError.

Extend the read-denied handling to Cache Service v1 so GHES (which forces v1 via _apis/artifactcache) is covered when read-scope enforcement ships there. - Surface the receiver's error body message from getCacheEntry instead of a generic status-code error, so the cache read denied: prefix reaches callers - Re-throw CacheReadDeniedError from restoreCacheV1 and dispatch on it in the outer catch, mirroring restoreCacheV2 and the write-denied v1 handling - Add a v1 read-denied test

Copilot

Pull request overview

This PR improves cache restore resilience by detecting policy-driven cache read denials (insufficient read permissions) and surfacing them as a clear core.warning while treating the restore as a cache miss so workflows continue.

Changes:

Added read-denial detection via CACHE_READ_DENIED_PREFIX and a dedicated CacheReadDeniedError for targeted handling.
Updated both cache restore implementations (v1 REST + v2 Twirp/gRPC) to reclassify read-denied failures into a single warning and continue as a miss.
Adjusted v1 getCacheEntry to selectively surface the receiver’s denial message and added tests + release/version bumps.

Show a summary per file

File	Description
packages/cache/src/internal/cacheHttpClient.ts	Surfaces receiver error message only for `cache read denied:` so restore paths can reclassify it.
packages/cache/src/cache.ts	Adds read-denied prefix + error type and handles read-denied restores as warning + cache miss for both v1/v2.
packages/cache/tests/restoreCache.test.ts	Adds v1 tests asserting warning behavior and cache-miss semantics for read denial.
packages/cache/tests/restoreCacheV2.test.ts	Adds v2 test asserting warning behavior and cache-miss semantics for wrapped read-denied errors.
packages/cache/tests/cacheHttpClient.test.ts	Adds tests ensuring `getCacheEntry` only surfaces body for read-denied cases.
packages/cache/RELEASES.md	Documents the 6.2.0 behavior change.
packages/cache/package.json	Bumps `@actions/cache` version to 6.2.0.
packages/cache/package-lock.json	Updates lockfile version metadata to 6.2.0.

Review details

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Files not reviewed (1)

packages/cache/package-lock.json: Generated file

Files reviewed: 7/8 changed files
Comments generated: 1
Review effort level: Low

… unknown modes

Copilot

Review details

Files not reviewed (1)

packages/cache/package-lock.json: Generated file

Files reviewed: 11/12 changed files
Comments generated: 1
Review effort level: Low

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

…denied handling Address PR review feedback: - Merge the duplicate restore/save skip test.each blocks into single blocks parametrized over ACTIONS_CACHE_SERVICE_V2. - Drop the redundant CacheReadDeniedError catch arms; the typed error is not an HttpClientError so it already falls through to a non-fatal warning. - Clarify why read-denied classification happens both in getCacheEntry and cache.ts (dependency-free internal module cannot import the typed error).

Mirror the read-denied simplification on the save path. CacheWriteDeniedError is not an HttpClientError and its name does not match the ReserveCacheError arm, so it falls through to the same non-fatal warning. Logging behavior is unchanged (warns, never fails the run) and the exported type is still thrown internally for consumers and tests. Also refresh stale doc wording.

The two restoreCache tests exercised the identical warning + cache-miss path now that read-denied is no longer reclassified in the catch, so merge them into one. The read-denied prefix detection that actually branches on the message is covered by getCacheEntry tests in cacheHttpClient.test.ts.

boxofyellow

Looks good to me.

#2451) Backport of the read-denied and ACTIONS_CACHE_MODE cache-mode gating from the ESM v6.2.0 line (#2447) to the CommonJS v5 line, released as 5.2.0. Mirrors the earlier write-denied backport (#2435, 5.1.0). - Detect the `cache read denied:` prefix on download failures (v2 twirp path and v1 `_apis/artifactcache` path) and surface it as a core.warning without failing the run. - Honor ACTIONS_CACHE_MODE: skip restore when the effective cache-mode does not permit reads (none, write-only) and skip save when it does not permit writes (none, read), logging a single non-fatal core.info line. Unset or unrecognized modes are unchanged. - Add read-denied and cache-mode tests; bump to 5.2.0 with RELEASES entry. Copilot-Session: e96deec1-716e-4e14-acdf-a230139420a2 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Trusted release actions must not accidentally restore a poisoned shared GitHub cache. Set `ACTIONS_CACHE_MODE: none` in `release.yml` and each reusable workflow it calls so clients that support the variable skip cache reads and writes. Each reusable workflow needs its own setting because workflow-level environment variables do not propagate to called workflows. The shared binary-build workflow uses the same cache-disabled setting when invoked by CI. This is a cooperative client-side default, not token revocation or server-enforced denial. Older or independent clients, or code calling the cache API directly, can still access the service. The `@actions/cache` library's [6.2.0 change](actions/toolkit#2447) skips operations before contacting the cache backend; that is separate from its handling of server-denied requests. The release graph uses `setup-uv@v10.0.1` and `setup-python@v7.0.0`, whose pinned [setup-uv](https://github.com/astral-sh/setup-uv/blob/20cfd1bf945f4377ade1205e4dbc17946fc9a30d/package-lock.json) and [setup-python](https://github.com/actions/setup-python/blob/5fda3b95a4ea91299a34e894583c3862153e4b97/package-lock.json) dependencies include `@actions/cache@6.2.0`. Both honor this variable. The separate `actions/cache@v6.1.0` action still bundles `@actions/cache@6.1.0` and does not honor it; the release graph does not invoke that action directly. Stacked on astral-sh#761, which keeps the action-specific opt-outs, removes the docs Rust cache, and explicitly disables maturin's sccache integration. `release-prepare.yml`, same-run artifacts, and Depot's own cache are unchanged. Co-authored-by: Zanie Blue <contact@zanie.dev>

philip-gai · 2026-07-01T18:33:18Z

Description

This PR adds client-side cache-mode behavior to @actions/cache. It combines two related pieces of work:

Surface the service-side read-denied policy as a non-fatal warning.
Honor a new ACTIONS_CACHE_MODE environment variable to skip cache operations the effective mode does not permit.

Cache-mode values are none | read | write | write-only (hyphenated). It is a partial lattice, not linear: readable modes = {read, write}, writable modes = {write, write-only}, none = neither. The ACTIONS_CACHE_MODE env var is provided by the Actions runner, and is gated on the service side. When it is unset or unrecognized, behavior is identical to today (regression-safe).

Read-denied warning

When the cache service denies a download because the token has no readable scopes, the run should continue with a clear warning instead of a confusing failure.

Added CacheReadDeniedError and the shared cache read denied: prefix constant.
On the v2 restore path, the denial arrives as a wrapped 403; the restore dispatch detects the prefix and surfaces it as a core.warning, then returns a cache miss.
Matches the existing write-denied handling (cache write denied:) for consistency.

ACTIONS_CACHE_MODE skip

Skip operations the effective cache-mode does not permit, before any tar or network work.

Skip restore when the mode is not readable (none, write-only).
Skip save when the mode is not writable (none, read).
Restore skip returns a cache miss (undefined); save skip returns the existing not-saved sentinel (-1). Neither throws.
Exactly one core.info line per skip; extra detail (paths, key) is behind ACTIONS_STEP_DEBUG.
Unset or unrecognized modes are permissive, so behavior is unchanged.

Rationale for skipping restore on write-only: write-only tokens have no read scope, so a restore would be denied service-side and trip the read-denied warning. Skipping client-side avoids the wasted round-trip and gives a clearer message.

Companion changes

actions/runner exports ACTIONS_CACHE_MODE into the step environment.

Notes

packages/cache/RELEASES.md updated under the 6.2.0 entry.
Test coverage: full cache suite passing, including the read-denied dispatch and a cache-mode truth table (none/read/write/write-only plus unset and unknown regression cases).

https://github.com/github/actions-persistence/issues/1168

Mirror the existing cache write-denied handling on the restore path. When the receiver refuses a download URL because the run's token has no readable cache scopes, it returns a twirp PermissionDenied (HTTP 403). The twirp client wraps that 403 in a generic Error, so the stable 'cache read denied:' prefix is embedded in the message rather than at the start. - Add CACHE_READ_DENIED_PREFIX and CacheReadDeniedError - Dispatch on the prefix in the restoreCacheV2 catch block (V2 only), log a policy-specific warning, and report a cache miss so the run continues - Add a test mirroring the write-denied coverage

Re-throw CacheReadDeniedError from an inner try/catch around GetCacheEntryDownloadURL and dispatch on typedError.name in the outer catch, matching how saveCacheV2 handles CacheWriteDeniedError.

Extend the read-denied handling to Cache Service v1 so GHES (which forces v1 via _apis/artifactcache) is covered when read-scope enforcement ships there. - Surface the receiver's error body message from getCacheEntry instead of a generic status-code error, so the cache read denied: prefix reaches callers - Re-throw CacheReadDeniedError from restoreCacheV1 and dispatch on it in the outer catch, mirroring restoreCacheV2 and the write-denied v1 handling - Add a v1 read-denied test

Copilot

Pull request overview

This PR improves cache restore resilience by detecting policy-driven cache read denials (insufficient read permissions) and surfacing them as a clear core.warning while treating the restore as a cache miss so workflows continue.

Changes:

Added read-denial detection via CACHE_READ_DENIED_PREFIX and a dedicated CacheReadDeniedError for targeted handling.
Updated both cache restore implementations (v1 REST + v2 Twirp/gRPC) to reclassify read-denied failures into a single warning and continue as a miss.
Adjusted v1 getCacheEntry to selectively surface the receiver’s denial message and added tests + release/version bumps.

Show a summary per file

File	Description
packages/cache/src/internal/cacheHttpClient.ts	Surfaces receiver error message only for `cache read denied:` so restore paths can reclassify it.
packages/cache/src/cache.ts	Adds read-denied prefix + error type and handles read-denied restores as warning + cache miss for both v1/v2.
packages/cache/tests/restoreCache.test.ts	Adds v1 tests asserting warning behavior and cache-miss semantics for read denial.
packages/cache/tests/restoreCacheV2.test.ts	Adds v2 test asserting warning behavior and cache-miss semantics for wrapped read-denied errors.
packages/cache/tests/cacheHttpClient.test.ts	Adds tests ensuring `getCacheEntry` only surfaces body for read-denied cases.
packages/cache/RELEASES.md	Documents the 6.2.0 behavior change.
packages/cache/package.json	Bumps `@actions/cache` version to 6.2.0.
packages/cache/package-lock.json	Updates lockfile version metadata to 6.2.0.

Review details

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Files not reviewed (1)

packages/cache/package-lock.json: Generated file

Files reviewed: 7/8 changed files
Comments generated: 1
Review effort level: Low

… unknown modes

Copilot

Review details

Files not reviewed (1)

packages/cache/package-lock.json: Generated file

Files reviewed: 11/12 changed files
Comments generated: 1
Review effort level: Low

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

…denied handling Address PR review feedback: - Merge the duplicate restore/save skip test.each blocks into single blocks parametrized over ACTIONS_CACHE_SERVICE_V2. - Drop the redundant CacheReadDeniedError catch arms; the typed error is not an HttpClientError so it already falls through to a non-fatal warning. - Clarify why read-denied classification happens both in getCacheEntry and cache.ts (dependency-free internal module cannot import the typed error).

Mirror the read-denied simplification on the save path. CacheWriteDeniedError is not an HttpClientError and its name does not match the ReserveCacheError arm, so it falls through to the same non-fatal warning. Logging behavior is unchanged (warns, never fails the run) and the exported type is still thrown internally for consumers and tests. Also refresh stale doc wording.

The two restoreCache tests exercised the identical warning + cache-miss path now that read-denied is no longer reclassified in the catch, so merge them into one. The read-denied prefix detection that actually branches on the message is covered by getCacheEntry tests in cacheHttpClient.test.ts.

boxofyellow

Looks good to me.

#2451) Backport of the read-denied and ACTIONS_CACHE_MODE cache-mode gating from the ESM v6.2.0 line (#2447) to the CommonJS v5 line, released as 5.2.0. Mirrors the earlier write-denied backport (#2435, 5.1.0). - Detect the `cache read denied:` prefix on download failures (v2 twirp path and v1 `_apis/artifactcache` path) and surface it as a core.warning without failing the run. - Honor ACTIONS_CACHE_MODE: skip restore when the effective cache-mode does not permit reads (none, write-only) and skip save when it does not permit writes (none, read), logging a single non-fatal core.info line. Unset or unrecognized modes are unchanged. - Add read-denied and cache-mode tests; bump to 5.2.0 with RELEASES entry. Copilot-Session: e96deec1-716e-4e14-acdf-a230139420a2 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Trusted release actions must not accidentally restore a poisoned shared GitHub cache. Set `ACTIONS_CACHE_MODE: none` in `release.yml` and each reusable workflow it calls so clients that support the variable skip cache reads and writes. Each reusable workflow needs its own setting because workflow-level environment variables do not propagate to called workflows. The shared binary-build workflow uses the same cache-disabled setting when invoked by CI. This is a cooperative client-side default, not token revocation or server-enforced denial. Older or independent clients, or code calling the cache API directly, can still access the service. The `@actions/cache` library's [6.2.0 change](actions/toolkit#2447) skips operations before contacting the cache backend; that is separate from its handling of server-denied requests. The release graph uses `setup-uv@v10.0.1` and `setup-python@v7.0.0`, whose pinned [setup-uv](https://github.com/astral-sh/setup-uv/blob/20cfd1bf945f4377ade1205e4dbc17946fc9a30d/package-lock.json) and [setup-python](https://github.com/actions/setup-python/blob/5fda3b95a4ea91299a34e894583c3862153e4b97/package-lock.json) dependencies include `@actions/cache@6.2.0`. Both honor this variable. The separate `actions/cache@v6.1.0` action still bundles `@actions/cache@6.1.0` and does not honor it; the release graph does not invoke that action directly. Stacked on astral-sh#761, which keeps the action-specific opt-outs, removes the docs Rust cache, and explicitly disables maturin's sccache integration. `release-prepare.yml`, same-run artifacts, and Depot's own cache are unchanged. Co-authored-by: Zanie Blue <contact@zanie.dev>

philip-gai · 2026-07-01T18:33:18Z

Description

This PR adds client-side cache-mode behavior to @actions/cache. It combines two related pieces of work:

Surface the service-side read-denied policy as a non-fatal warning.
Honor a new ACTIONS_CACHE_MODE environment variable to skip cache operations the effective mode does not permit.

Cache-mode values are none | read | write | write-only (hyphenated). It is a partial lattice, not linear: readable modes = {read, write}, writable modes = {write, write-only}, none = neither. The ACTIONS_CACHE_MODE env var is provided by the Actions runner, and is gated on the service side. When it is unset or unrecognized, behavior is identical to today (regression-safe).

Read-denied warning

When the cache service denies a download because the token has no readable scopes, the run should continue with a clear warning instead of a confusing failure.

Added CacheReadDeniedError and the shared cache read denied: prefix constant.
On the v2 restore path, the denial arrives as a wrapped 403; the restore dispatch detects the prefix and surfaces it as a core.warning, then returns a cache miss.
Matches the existing write-denied handling (cache write denied:) for consistency.

ACTIONS_CACHE_MODE skip

Skip operations the effective cache-mode does not permit, before any tar or network work.

Skip restore when the mode is not readable (none, write-only).
Skip save when the mode is not writable (none, read).
Restore skip returns a cache miss (undefined); save skip returns the existing not-saved sentinel (-1). Neither throws.
Exactly one core.info line per skip; extra detail (paths, key) is behind ACTIONS_STEP_DEBUG.
Unset or unrecognized modes are permissive, so behavior is unchanged.

Rationale for skipping restore on write-only: write-only tokens have no read scope, so a restore would be denied service-side and trip the read-denied warning. Skipping client-side avoids the wasted round-trip and gives a clearer message.

Companion changes

actions/runner exports ACTIONS_CACHE_MODE into the step environment.

Notes

packages/cache/RELEASES.md updated under the 6.2.0 entry.
Test coverage: full cache suite passing, including the read-denied dispatch and a cache-mode truth table (none/read/write/write-only plus unset and unknown regression cases).

https://github.com/github/actions-persistence/issues/1168

Mirror the existing cache write-denied handling on the restore path. When the receiver refuses a download URL because the run's token has no readable cache scopes, it returns a twirp PermissionDenied (HTTP 403). The twirp client wraps that 403 in a generic Error, so the stable 'cache read denied:' prefix is embedded in the message rather than at the start. - Add CACHE_READ_DENIED_PREFIX and CacheReadDeniedError - Dispatch on the prefix in the restoreCacheV2 catch block (V2 only), log a policy-specific warning, and report a cache miss so the run continues - Add a test mirroring the write-denied coverage

Re-throw CacheReadDeniedError from an inner try/catch around GetCacheEntryDownloadURL and dispatch on typedError.name in the outer catch, matching how saveCacheV2 handles CacheWriteDeniedError.

Extend the read-denied handling to Cache Service v1 so GHES (which forces v1 via _apis/artifactcache) is covered when read-scope enforcement ships there. - Surface the receiver's error body message from getCacheEntry instead of a generic status-code error, so the cache read denied: prefix reaches callers - Re-throw CacheReadDeniedError from restoreCacheV1 and dispatch on it in the outer catch, mirroring restoreCacheV2 and the write-denied v1 handling - Add a v1 read-denied test

Copilot

Pull request overview

This PR improves cache restore resilience by detecting policy-driven cache read denials (insufficient read permissions) and surfacing them as a clear core.warning while treating the restore as a cache miss so workflows continue.

Changes:

Added read-denial detection via CACHE_READ_DENIED_PREFIX and a dedicated CacheReadDeniedError for targeted handling.
Updated both cache restore implementations (v1 REST + v2 Twirp/gRPC) to reclassify read-denied failures into a single warning and continue as a miss.
Adjusted v1 getCacheEntry to selectively surface the receiver’s denial message and added tests + release/version bumps.

Show a summary per file

File	Description
packages/cache/src/internal/cacheHttpClient.ts	Surfaces receiver error message only for `cache read denied:` so restore paths can reclassify it.
packages/cache/src/cache.ts	Adds read-denied prefix + error type and handles read-denied restores as warning + cache miss for both v1/v2.
packages/cache/tests/restoreCache.test.ts	Adds v1 tests asserting warning behavior and cache-miss semantics for read denial.
packages/cache/tests/restoreCacheV2.test.ts	Adds v2 test asserting warning behavior and cache-miss semantics for wrapped read-denied errors.
packages/cache/tests/cacheHttpClient.test.ts	Adds tests ensuring `getCacheEntry` only surfaces body for read-denied cases.
packages/cache/RELEASES.md	Documents the 6.2.0 behavior change.
packages/cache/package.json	Bumps `@actions/cache` version to 6.2.0.
packages/cache/package-lock.json	Updates lockfile version metadata to 6.2.0.

Review details

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Files not reviewed (1)

packages/cache/package-lock.json: Generated file

Files reviewed: 7/8 changed files
Comments generated: 1
Review effort level: Low

… unknown modes

Copilot

Review details

Files not reviewed (1)

packages/cache/package-lock.json: Generated file

Files reviewed: 11/12 changed files
Comments generated: 1
Review effort level: Low

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

…denied handling Address PR review feedback: - Merge the duplicate restore/save skip test.each blocks into single blocks parametrized over ACTIONS_CACHE_SERVICE_V2. - Drop the redundant CacheReadDeniedError catch arms; the typed error is not an HttpClientError so it already falls through to a non-fatal warning. - Clarify why read-denied classification happens both in getCacheEntry and cache.ts (dependency-free internal module cannot import the typed error).

Mirror the read-denied simplification on the save path. CacheWriteDeniedError is not an HttpClientError and its name does not match the ReserveCacheError arm, so it falls through to the same non-fatal warning. Logging behavior is unchanged (warns, never fails the run) and the exported type is still thrown internally for consumers and tests. Also refresh stale doc wording.

The two restoreCache tests exercised the identical warning + cache-miss path now that read-denied is no longer reclassified in the catch, so merge them into one. The read-denied prefix detection that actually branches on the message is covered by getCacheEntry tests in cacheHttpClient.test.ts.

boxofyellow

Looks good to me.

#2451) Backport of the read-denied and ACTIONS_CACHE_MODE cache-mode gating from the ESM v6.2.0 line (#2447) to the CommonJS v5 line, released as 5.2.0. Mirrors the earlier write-denied backport (#2435, 5.1.0). - Detect the `cache read denied:` prefix on download failures (v2 twirp path and v1 `_apis/artifactcache` path) and surface it as a core.warning without failing the run. - Honor ACTIONS_CACHE_MODE: skip restore when the effective cache-mode does not permit reads (none, write-only) and skip save when it does not permit writes (none, read), logging a single non-fatal core.info line. Unset or unrecognized modes are unchanged. - Add read-denied and cache-mode tests; bump to 5.2.0 with RELEASES entry. Copilot-Session: e96deec1-716e-4e14-acdf-a230139420a2 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Trusted release actions must not accidentally restore a poisoned shared GitHub cache. Set `ACTIONS_CACHE_MODE: none` in `release.yml` and each reusable workflow it calls so clients that support the variable skip cache reads and writes. Each reusable workflow needs its own setting because workflow-level environment variables do not propagate to called workflows. The shared binary-build workflow uses the same cache-disabled setting when invoked by CI. This is a cooperative client-side default, not token revocation or server-enforced denial. Older or independent clients, or code calling the cache API directly, can still access the service. The `@actions/cache` library's [6.2.0 change](actions/toolkit#2447) skips operations before contacting the cache backend; that is separate from its handling of server-denied requests. The release graph uses `setup-uv@v10.0.1` and `setup-python@v7.0.0`, whose pinned [setup-uv](https://github.com/astral-sh/setup-uv/blob/20cfd1bf945f4377ade1205e4dbc17946fc9a30d/package-lock.json) and [setup-python](https://github.com/actions/setup-python/blob/5fda3b95a4ea91299a34e894583c3862153e4b97/package-lock.json) dependencies include `@actions/cache@6.2.0`. Both honor this variable. The separate `actions/cache@v6.1.0` action still bundles `@actions/cache@6.1.0` and does not honor it; the release graph does not invoke that action directly. Stacked on astral-sh#761, which keeps the action-specific opt-outs, removes the docs Rust cache, and explicitly disables maturin's sccache integration. `release-prepare.yml`, same-run artifacts, and Depot's own cache are unchanged. Co-authored-by: Zanie Blue <contact@zanie.dev>

philip-gai · 2026-07-01T18:33:18Z

Description

This PR adds client-side cache-mode behavior to @actions/cache. It combines two related pieces of work:

Surface the service-side read-denied policy as a non-fatal warning.
Honor a new ACTIONS_CACHE_MODE environment variable to skip cache operations the effective mode does not permit.

Cache-mode values are none | read | write | write-only (hyphenated). It is a partial lattice, not linear: readable modes = {read, write}, writable modes = {write, write-only}, none = neither. The ACTIONS_CACHE_MODE env var is provided by the Actions runner, and is gated on the service side. When it is unset or unrecognized, behavior is identical to today (regression-safe).

Read-denied warning

When the cache service denies a download because the token has no readable scopes, the run should continue with a clear warning instead of a confusing failure.

Added CacheReadDeniedError and the shared cache read denied: prefix constant.
On the v2 restore path, the denial arrives as a wrapped 403; the restore dispatch detects the prefix and surfaces it as a core.warning, then returns a cache miss.
Matches the existing write-denied handling (cache write denied:) for consistency.

ACTIONS_CACHE_MODE skip

Skip operations the effective cache-mode does not permit, before any tar or network work.

Skip restore when the mode is not readable (none, write-only).
Skip save when the mode is not writable (none, read).
Restore skip returns a cache miss (undefined); save skip returns the existing not-saved sentinel (-1). Neither throws.
Exactly one core.info line per skip; extra detail (paths, key) is behind ACTIONS_STEP_DEBUG.
Unset or unrecognized modes are permissive, so behavior is unchanged.

Rationale for skipping restore on write-only: write-only tokens have no read scope, so a restore would be denied service-side and trip the read-denied warning. Skipping client-side avoids the wasted round-trip and gives a clearer message.

Companion changes

actions/runner exports ACTIONS_CACHE_MODE into the step environment.

Notes

packages/cache/RELEASES.md updated under the 6.2.0 entry.
Test coverage: full cache suite passing, including the read-denied dispatch and a cache-mode truth table (none/read/write/write-only plus unset and unknown regression cases).

https://github.com/github/actions-persistence/issues/1168

Mirror the existing cache write-denied handling on the restore path. When the receiver refuses a download URL because the run's token has no readable cache scopes, it returns a twirp PermissionDenied (HTTP 403). The twirp client wraps that 403 in a generic Error, so the stable 'cache read denied:' prefix is embedded in the message rather than at the start. - Add CACHE_READ_DENIED_PREFIX and CacheReadDeniedError - Dispatch on the prefix in the restoreCacheV2 catch block (V2 only), log a policy-specific warning, and report a cache miss so the run continues - Add a test mirroring the write-denied coverage

Re-throw CacheReadDeniedError from an inner try/catch around GetCacheEntryDownloadURL and dispatch on typedError.name in the outer catch, matching how saveCacheV2 handles CacheWriteDeniedError.

Extend the read-denied handling to Cache Service v1 so GHES (which forces v1 via _apis/artifactcache) is covered when read-scope enforcement ships there. - Surface the receiver's error body message from getCacheEntry instead of a generic status-code error, so the cache read denied: prefix reaches callers - Re-throw CacheReadDeniedError from restoreCacheV1 and dispatch on it in the outer catch, mirroring restoreCacheV2 and the write-denied v1 handling - Add a v1 read-denied test

Copilot

Pull request overview

This PR improves cache restore resilience by detecting policy-driven cache read denials (insufficient read permissions) and surfacing them as a clear core.warning while treating the restore as a cache miss so workflows continue.

Changes:

Added read-denial detection via CACHE_READ_DENIED_PREFIX and a dedicated CacheReadDeniedError for targeted handling.
Updated both cache restore implementations (v1 REST + v2 Twirp/gRPC) to reclassify read-denied failures into a single warning and continue as a miss.
Adjusted v1 getCacheEntry to selectively surface the receiver’s denial message and added tests + release/version bumps.

Show a summary per file

File	Description
packages/cache/src/internal/cacheHttpClient.ts	Surfaces receiver error message only for `cache read denied:` so restore paths can reclassify it.
packages/cache/src/cache.ts	Adds read-denied prefix + error type and handles read-denied restores as warning + cache miss for both v1/v2.
packages/cache/tests/restoreCache.test.ts	Adds v1 tests asserting warning behavior and cache-miss semantics for read denial.
packages/cache/tests/restoreCacheV2.test.ts	Adds v2 test asserting warning behavior and cache-miss semantics for wrapped read-denied errors.
packages/cache/tests/cacheHttpClient.test.ts	Adds tests ensuring `getCacheEntry` only surfaces body for read-denied cases.
packages/cache/RELEASES.md	Documents the 6.2.0 behavior change.
packages/cache/package.json	Bumps `@actions/cache` version to 6.2.0.
packages/cache/package-lock.json	Updates lockfile version metadata to 6.2.0.

Review details

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Files not reviewed (1)

packages/cache/package-lock.json: Generated file

Files reviewed: 7/8 changed files
Comments generated: 1
Review effort level: Low

… unknown modes

Copilot

Review details

Files not reviewed (1)

packages/cache/package-lock.json: Generated file

Files reviewed: 11/12 changed files
Comments generated: 1
Review effort level: Low

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

…denied handling Address PR review feedback: - Merge the duplicate restore/save skip test.each blocks into single blocks parametrized over ACTIONS_CACHE_SERVICE_V2. - Drop the redundant CacheReadDeniedError catch arms; the typed error is not an HttpClientError so it already falls through to a non-fatal warning. - Clarify why read-denied classification happens both in getCacheEntry and cache.ts (dependency-free internal module cannot import the typed error).

Mirror the read-denied simplification on the save path. CacheWriteDeniedError is not an HttpClientError and its name does not match the ReserveCacheError arm, so it falls through to the same non-fatal warning. Logging behavior is unchanged (warns, never fails the run) and the exported type is still thrown internally for consumers and tests. Also refresh stale doc wording.

The two restoreCache tests exercised the identical warning + cache-miss path now that read-denied is no longer reclassified in the catch, so merge them into one. The read-denied prefix detection that actually branches on the message is covered by getCacheEntry tests in cacheHttpClient.test.ts.

boxofyellow

Looks good to me.

#2451) Backport of the read-denied and ACTIONS_CACHE_MODE cache-mode gating from the ESM v6.2.0 line (#2447) to the CommonJS v5 line, released as 5.2.0. Mirrors the earlier write-denied backport (#2435, 5.1.0). - Detect the `cache read denied:` prefix on download failures (v2 twirp path and v1 `_apis/artifactcache` path) and surface it as a core.warning without failing the run. - Honor ACTIONS_CACHE_MODE: skip restore when the effective cache-mode does not permit reads (none, write-only) and skip save when it does not permit writes (none, read), logging a single non-fatal core.info line. Unset or unrecognized modes are unchanged. - Add read-denied and cache-mode tests; bump to 5.2.0 with RELEASES entry. Copilot-Session: e96deec1-716e-4e14-acdf-a230139420a2 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Trusted release actions must not accidentally restore a poisoned shared GitHub cache. Set `ACTIONS_CACHE_MODE: none` in `release.yml` and each reusable workflow it calls so clients that support the variable skip cache reads and writes. Each reusable workflow needs its own setting because workflow-level environment variables do not propagate to called workflows. The shared binary-build workflow uses the same cache-disabled setting when invoked by CI. This is a cooperative client-side default, not token revocation or server-enforced denial. Older or independent clients, or code calling the cache API directly, can still access the service. The `@actions/cache` library's [6.2.0 change](actions/toolkit#2447) skips operations before contacting the cache backend; that is separate from its handling of server-denied requests. The release graph uses `setup-uv@v10.0.1` and `setup-python@v7.0.0`, whose pinned [setup-uv](https://github.com/astral-sh/setup-uv/blob/20cfd1bf945f4377ade1205e4dbc17946fc9a30d/package-lock.json) and [setup-python](https://github.com/actions/setup-python/blob/5fda3b95a4ea91299a34e894583c3862153e4b97/package-lock.json) dependencies include `@actions/cache@6.2.0`. Both honor this variable. The separate `actions/cache@v6.1.0` action still bundles `@actions/cache@6.1.0` and does not honor it; the release graph does not invoke that action directly. Stacked on astral-sh#761, which keeps the action-specific opt-outs, removes the docs Rust cache, and explicitly disables maturin's sccache integration. `release-prepare.yml`, same-run artifacts, and Depot's own cache are unchanged. Co-authored-by: Zanie Blue <contact@zanie.dev>

philip-gai · 2026-07-01T18:33:18Z

Description

This PR adds client-side cache-mode behavior to @actions/cache. It combines two related pieces of work:

Surface the service-side read-denied policy as a non-fatal warning.
Honor a new ACTIONS_CACHE_MODE environment variable to skip cache operations the effective mode does not permit.

Cache-mode values are none | read | write | write-only (hyphenated). It is a partial lattice, not linear: readable modes = {read, write}, writable modes = {write, write-only}, none = neither. The ACTIONS_CACHE_MODE env var is provided by the Actions runner, and is gated on the service side. When it is unset or unrecognized, behavior is identical to today (regression-safe).

Read-denied warning

When the cache service denies a download because the token has no readable scopes, the run should continue with a clear warning instead of a confusing failure.

Added CacheReadDeniedError and the shared cache read denied: prefix constant.
On the v2 restore path, the denial arrives as a wrapped 403; the restore dispatch detects the prefix and surfaces it as a core.warning, then returns a cache miss.
Matches the existing write-denied handling (cache write denied:) for consistency.

ACTIONS_CACHE_MODE skip

Skip operations the effective cache-mode does not permit, before any tar or network work.

Skip restore when the mode is not readable (none, write-only).
Skip save when the mode is not writable (none, read).
Restore skip returns a cache miss (undefined); save skip returns the existing not-saved sentinel (-1). Neither throws.
Exactly one core.info line per skip; extra detail (paths, key) is behind ACTIONS_STEP_DEBUG.
Unset or unrecognized modes are permissive, so behavior is unchanged.

Rationale for skipping restore on write-only: write-only tokens have no read scope, so a restore would be denied service-side and trip the read-denied warning. Skipping client-side avoids the wasted round-trip and gives a clearer message.

Companion changes

actions/runner exports ACTIONS_CACHE_MODE into the step environment.

Notes

packages/cache/RELEASES.md updated under the 6.2.0 entry.
Test coverage: full cache suite passing, including the read-denied dispatch and a cache-mode truth table (none/read/write/write-only plus unset and unknown regression cases).

https://github.com/github/actions-persistence/issues/1168

Mirror the existing cache write-denied handling on the restore path. When the receiver refuses a download URL because the run's token has no readable cache scopes, it returns a twirp PermissionDenied (HTTP 403). The twirp client wraps that 403 in a generic Error, so the stable 'cache read denied:' prefix is embedded in the message rather than at the start. - Add CACHE_READ_DENIED_PREFIX and CacheReadDeniedError - Dispatch on the prefix in the restoreCacheV2 catch block (V2 only), log a policy-specific warning, and report a cache miss so the run continues - Add a test mirroring the write-denied coverage

Re-throw CacheReadDeniedError from an inner try/catch around GetCacheEntryDownloadURL and dispatch on typedError.name in the outer catch, matching how saveCacheV2 handles CacheWriteDeniedError.

Extend the read-denied handling to Cache Service v1 so GHES (which forces v1 via _apis/artifactcache) is covered when read-scope enforcement ships there. - Surface the receiver's error body message from getCacheEntry instead of a generic status-code error, so the cache read denied: prefix reaches callers - Re-throw CacheReadDeniedError from restoreCacheV1 and dispatch on it in the outer catch, mirroring restoreCacheV2 and the write-denied v1 handling - Add a v1 read-denied test

Copilot

Pull request overview

This PR improves cache restore resilience by detecting policy-driven cache read denials (insufficient read permissions) and surfacing them as a clear core.warning while treating the restore as a cache miss so workflows continue.

Changes:

Added read-denial detection via CACHE_READ_DENIED_PREFIX and a dedicated CacheReadDeniedError for targeted handling.
Updated both cache restore implementations (v1 REST + v2 Twirp/gRPC) to reclassify read-denied failures into a single warning and continue as a miss.
Adjusted v1 getCacheEntry to selectively surface the receiver’s denial message and added tests + release/version bumps.

Show a summary per file

File	Description
packages/cache/src/internal/cacheHttpClient.ts	Surfaces receiver error message only for `cache read denied:` so restore paths can reclassify it.
packages/cache/src/cache.ts	Adds read-denied prefix + error type and handles read-denied restores as warning + cache miss for both v1/v2.
packages/cache/tests/restoreCache.test.ts	Adds v1 tests asserting warning behavior and cache-miss semantics for read denial.
packages/cache/tests/restoreCacheV2.test.ts	Adds v2 test asserting warning behavior and cache-miss semantics for wrapped read-denied errors.
packages/cache/tests/cacheHttpClient.test.ts	Adds tests ensuring `getCacheEntry` only surfaces body for read-denied cases.
packages/cache/RELEASES.md	Documents the 6.2.0 behavior change.
packages/cache/package.json	Bumps `@actions/cache` version to 6.2.0.
packages/cache/package-lock.json	Updates lockfile version metadata to 6.2.0.

Review details

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Files not reviewed (1)

packages/cache/package-lock.json: Generated file

Files reviewed: 7/8 changed files
Comments generated: 1
Review effort level: Low

… unknown modes

Copilot

Review details

Files not reviewed (1)

packages/cache/package-lock.json: Generated file

Files reviewed: 11/12 changed files
Comments generated: 1
Review effort level: Low

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

…denied handling Address PR review feedback: - Merge the duplicate restore/save skip test.each blocks into single blocks parametrized over ACTIONS_CACHE_SERVICE_V2. - Drop the redundant CacheReadDeniedError catch arms; the typed error is not an HttpClientError so it already falls through to a non-fatal warning. - Clarify why read-denied classification happens both in getCacheEntry and cache.ts (dependency-free internal module cannot import the typed error).

Mirror the read-denied simplification on the save path. CacheWriteDeniedError is not an HttpClientError and its name does not match the ReserveCacheError arm, so it falls through to the same non-fatal warning. Logging behavior is unchanged (warns, never fails the run) and the exported type is still thrown internally for consumers and tests. Also refresh stale doc wording.

The two restoreCache tests exercised the identical warning + cache-miss path now that read-denied is no longer reclassified in the catch, so merge them into one. The read-denied prefix detection that actually branches on the message is covered by getCacheEntry tests in cacheHttpClient.test.ts.

boxofyellow

Looks good to me.

#2451) Backport of the read-denied and ACTIONS_CACHE_MODE cache-mode gating from the ESM v6.2.0 line (#2447) to the CommonJS v5 line, released as 5.2.0. Mirrors the earlier write-denied backport (#2435, 5.1.0). - Detect the `cache read denied:` prefix on download failures (v2 twirp path and v1 `_apis/artifactcache` path) and surface it as a core.warning without failing the run. - Honor ACTIONS_CACHE_MODE: skip restore when the effective cache-mode does not permit reads (none, write-only) and skip save when it does not permit writes (none, read), logging a single non-fatal core.info line. Unset or unrecognized modes are unchanged. - Add read-denied and cache-mode tests; bump to 5.2.0 with RELEASES entry. Copilot-Session: e96deec1-716e-4e14-acdf-a230139420a2 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Trusted release actions must not accidentally restore a poisoned shared GitHub cache. Set `ACTIONS_CACHE_MODE: none` in `release.yml` and each reusable workflow it calls so clients that support the variable skip cache reads and writes. Each reusable workflow needs its own setting because workflow-level environment variables do not propagate to called workflows. The shared binary-build workflow uses the same cache-disabled setting when invoked by CI. This is a cooperative client-side default, not token revocation or server-enforced denial. Older or independent clients, or code calling the cache API directly, can still access the service. The `@actions/cache` library's [6.2.0 change](actions/toolkit#2447) skips operations before contacting the cache backend; that is separate from its handling of server-denied requests. The release graph uses `setup-uv@v10.0.1` and `setup-python@v7.0.0`, whose pinned [setup-uv](https://github.com/astral-sh/setup-uv/blob/20cfd1bf945f4377ade1205e4dbc17946fc9a30d/package-lock.json) and [setup-python](https://github.com/actions/setup-python/blob/5fda3b95a4ea91299a34e894583c3862153e4b97/package-lock.json) dependencies include `@actions/cache@6.2.0`. Both honor this variable. The separate `actions/cache@v6.1.0` action still bundles `@actions/cache@6.1.0` and does not honor it; the release graph does not invoke that action directly. Stacked on astral-sh#761, which keeps the action-specific opt-outs, removes the docs Rust cache, and explicitly disables maturin's sccache integration. `release-prepare.yml`, same-run artifacts, and Depot's own cache are unchanged. Co-authored-by: Zanie Blue <contact@zanie.dev>

philip-gai · 2026-07-01T18:33:18Z

Description

This PR adds client-side cache-mode behavior to @actions/cache. It combines two related pieces of work:

Surface the service-side read-denied policy as a non-fatal warning.
Honor a new ACTIONS_CACHE_MODE environment variable to skip cache operations the effective mode does not permit.

Cache-mode values are none | read | write | write-only (hyphenated). It is a partial lattice, not linear: readable modes = {read, write}, writable modes = {write, write-only}, none = neither. The ACTIONS_CACHE_MODE env var is provided by the Actions runner, and is gated on the service side. When it is unset or unrecognized, behavior is identical to today (regression-safe).

Read-denied warning

When the cache service denies a download because the token has no readable scopes, the run should continue with a clear warning instead of a confusing failure.

Added CacheReadDeniedError and the shared cache read denied: prefix constant.
On the v2 restore path, the denial arrives as a wrapped 403; the restore dispatch detects the prefix and surfaces it as a core.warning, then returns a cache miss.
Matches the existing write-denied handling (cache write denied:) for consistency.

ACTIONS_CACHE_MODE skip

Skip operations the effective cache-mode does not permit, before any tar or network work.

Skip restore when the mode is not readable (none, write-only).
Skip save when the mode is not writable (none, read).
Restore skip returns a cache miss (undefined); save skip returns the existing not-saved sentinel (-1). Neither throws.
Exactly one core.info line per skip; extra detail (paths, key) is behind ACTIONS_STEP_DEBUG.
Unset or unrecognized modes are permissive, so behavior is unchanged.

Rationale for skipping restore on write-only: write-only tokens have no read scope, so a restore would be denied service-side and trip the read-denied warning. Skipping client-side avoids the wasted round-trip and gives a clearer message.

Companion changes

actions/runner exports ACTIONS_CACHE_MODE into the step environment.

Notes

packages/cache/RELEASES.md updated under the 6.2.0 entry.
Test coverage: full cache suite passing, including the read-denied dispatch and a cache-mode truth table (none/read/write/write-only plus unset and unknown regression cases).

https://github.com/github/actions-persistence/issues/1168

Mirror the existing cache write-denied handling on the restore path. When the receiver refuses a download URL because the run's token has no readable cache scopes, it returns a twirp PermissionDenied (HTTP 403). The twirp client wraps that 403 in a generic Error, so the stable 'cache read denied:' prefix is embedded in the message rather than at the start. - Add CACHE_READ_DENIED_PREFIX and CacheReadDeniedError - Dispatch on the prefix in the restoreCacheV2 catch block (V2 only), log a policy-specific warning, and report a cache miss so the run continues - Add a test mirroring the write-denied coverage

Re-throw CacheReadDeniedError from an inner try/catch around GetCacheEntryDownloadURL and dispatch on typedError.name in the outer catch, matching how saveCacheV2 handles CacheWriteDeniedError.

Extend the read-denied handling to Cache Service v1 so GHES (which forces v1 via _apis/artifactcache) is covered when read-scope enforcement ships there. - Surface the receiver's error body message from getCacheEntry instead of a generic status-code error, so the cache read denied: prefix reaches callers - Re-throw CacheReadDeniedError from restoreCacheV1 and dispatch on it in the outer catch, mirroring restoreCacheV2 and the write-denied v1 handling - Add a v1 read-denied test

Copilot

Pull request overview

This PR improves cache restore resilience by detecting policy-driven cache read denials (insufficient read permissions) and surfacing them as a clear core.warning while treating the restore as a cache miss so workflows continue.

Changes:

Added read-denial detection via CACHE_READ_DENIED_PREFIX and a dedicated CacheReadDeniedError for targeted handling.
Updated both cache restore implementations (v1 REST + v2 Twirp/gRPC) to reclassify read-denied failures into a single warning and continue as a miss.
Adjusted v1 getCacheEntry to selectively surface the receiver’s denial message and added tests + release/version bumps.

Show a summary per file

File	Description
packages/cache/src/internal/cacheHttpClient.ts	Surfaces receiver error message only for `cache read denied:` so restore paths can reclassify it.
packages/cache/src/cache.ts	Adds read-denied prefix + error type and handles read-denied restores as warning + cache miss for both v1/v2.
packages/cache/tests/restoreCache.test.ts	Adds v1 tests asserting warning behavior and cache-miss semantics for read denial.
packages/cache/tests/restoreCacheV2.test.ts	Adds v2 test asserting warning behavior and cache-miss semantics for wrapped read-denied errors.
packages/cache/tests/cacheHttpClient.test.ts	Adds tests ensuring `getCacheEntry` only surfaces body for read-denied cases.
packages/cache/RELEASES.md	Documents the 6.2.0 behavior change.
packages/cache/package.json	Bumps `@actions/cache` version to 6.2.0.
packages/cache/package-lock.json	Updates lockfile version metadata to 6.2.0.

Review details

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Files not reviewed (1)

packages/cache/package-lock.json: Generated file

Files reviewed: 7/8 changed files
Comments generated: 1
Review effort level: Low

… unknown modes

Copilot

Review details

Files not reviewed (1)

packages/cache/package-lock.json: Generated file

Files reviewed: 11/12 changed files
Comments generated: 1
Review effort level: Low

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

…denied handling Address PR review feedback: - Merge the duplicate restore/save skip test.each blocks into single blocks parametrized over ACTIONS_CACHE_SERVICE_V2. - Drop the redundant CacheReadDeniedError catch arms; the typed error is not an HttpClientError so it already falls through to a non-fatal warning. - Clarify why read-denied classification happens both in getCacheEntry and cache.ts (dependency-free internal module cannot import the typed error).

Mirror the read-denied simplification on the save path. CacheWriteDeniedError is not an HttpClientError and its name does not match the ReserveCacheError arm, so it falls through to the same non-fatal warning. Logging behavior is unchanged (warns, never fails the run) and the exported type is still thrown internally for consumers and tests. Also refresh stale doc wording.

The two restoreCache tests exercised the identical warning + cache-miss path now that read-denied is no longer reclassified in the catch, so merge them into one. The read-denied prefix detection that actually branches on the message is covered by getCacheEntry tests in cacheHttpClient.test.ts.

boxofyellow

Looks good to me.

#2451) Backport of the read-denied and ACTIONS_CACHE_MODE cache-mode gating from the ESM v6.2.0 line (#2447) to the CommonJS v5 line, released as 5.2.0. Mirrors the earlier write-denied backport (#2435, 5.1.0). - Detect the `cache read denied:` prefix on download failures (v2 twirp path and v1 `_apis/artifactcache` path) and surface it as a core.warning without failing the run. - Honor ACTIONS_CACHE_MODE: skip restore when the effective cache-mode does not permit reads (none, write-only) and skip save when it does not permit writes (none, read), logging a single non-fatal core.info line. Unset or unrecognized modes are unchanged. - Add read-denied and cache-mode tests; bump to 5.2.0 with RELEASES entry. Copilot-Session: e96deec1-716e-4e14-acdf-a230139420a2 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Trusted release actions must not accidentally restore a poisoned shared GitHub cache. Set `ACTIONS_CACHE_MODE: none` in `release.yml` and each reusable workflow it calls so clients that support the variable skip cache reads and writes. Each reusable workflow needs its own setting because workflow-level environment variables do not propagate to called workflows. The shared binary-build workflow uses the same cache-disabled setting when invoked by CI. This is a cooperative client-side default, not token revocation or server-enforced denial. Older or independent clients, or code calling the cache API directly, can still access the service. The `@actions/cache` library's [6.2.0 change](actions/toolkit#2447) skips operations before contacting the cache backend; that is separate from its handling of server-denied requests. The release graph uses `setup-uv@v10.0.1` and `setup-python@v7.0.0`, whose pinned [setup-uv](https://github.com/astral-sh/setup-uv/blob/20cfd1bf945f4377ade1205e4dbc17946fc9a30d/package-lock.json) and [setup-python](https://github.com/actions/setup-python/blob/5fda3b95a4ea91299a34e894583c3862153e4b97/package-lock.json) dependencies include `@actions/cache@6.2.0`. Both honor this variable. The separate `actions/cache@v6.1.0` action still bundles `@actions/cache@6.1.0` and does not honor it; the release graph does not invoke that action directly. Stacked on astral-sh#761, which keeps the action-specific opt-outs, removes the docs Rust cache, and explicitly disables maturin's sccache integration. `release-prepare.yml`, same-run artifacts, and Depot's own cache are unchanged. Co-authored-by: Zanie Blue <contact@zanie.dev>

philip-gai · 2026-07-01T18:33:18Z

Description

This PR adds client-side cache-mode behavior to @actions/cache. It combines two related pieces of work:

Surface the service-side read-denied policy as a non-fatal warning.
Honor a new ACTIONS_CACHE_MODE environment variable to skip cache operations the effective mode does not permit.

Cache-mode values are none | read | write | write-only (hyphenated). It is a partial lattice, not linear: readable modes = {read, write}, writable modes = {write, write-only}, none = neither. The ACTIONS_CACHE_MODE env var is provided by the Actions runner, and is gated on the service side. When it is unset or unrecognized, behavior is identical to today (regression-safe).

Read-denied warning

When the cache service denies a download because the token has no readable scopes, the run should continue with a clear warning instead of a confusing failure.

Added CacheReadDeniedError and the shared cache read denied: prefix constant.
On the v2 restore path, the denial arrives as a wrapped 403; the restore dispatch detects the prefix and surfaces it as a core.warning, then returns a cache miss.
Matches the existing write-denied handling (cache write denied:) for consistency.

ACTIONS_CACHE_MODE skip

Skip operations the effective cache-mode does not permit, before any tar or network work.

Skip restore when the mode is not readable (none, write-only).
Skip save when the mode is not writable (none, read).
Restore skip returns a cache miss (undefined); save skip returns the existing not-saved sentinel (-1). Neither throws.
Exactly one core.info line per skip; extra detail (paths, key) is behind ACTIONS_STEP_DEBUG.
Unset or unrecognized modes are permissive, so behavior is unchanged.

Rationale for skipping restore on write-only: write-only tokens have no read scope, so a restore would be denied service-side and trip the read-denied warning. Skipping client-side avoids the wasted round-trip and gives a clearer message.

Companion changes

actions/runner exports ACTIONS_CACHE_MODE into the step environment.

Notes

packages/cache/RELEASES.md updated under the 6.2.0 entry.
Test coverage: full cache suite passing, including the read-denied dispatch and a cache-mode truth table (none/read/write/write-only plus unset and unknown regression cases).

https://github.com/github/actions-persistence/issues/1168

Mirror the existing cache write-denied handling on the restore path. When the receiver refuses a download URL because the run's token has no readable cache scopes, it returns a twirp PermissionDenied (HTTP 403). The twirp client wraps that 403 in a generic Error, so the stable 'cache read denied:' prefix is embedded in the message rather than at the start. - Add CACHE_READ_DENIED_PREFIX and CacheReadDeniedError - Dispatch on the prefix in the restoreCacheV2 catch block (V2 only), log a policy-specific warning, and report a cache miss so the run continues - Add a test mirroring the write-denied coverage

Re-throw CacheReadDeniedError from an inner try/catch around GetCacheEntryDownloadURL and dispatch on typedError.name in the outer catch, matching how saveCacheV2 handles CacheWriteDeniedError.

Extend the read-denied handling to Cache Service v1 so GHES (which forces v1 via _apis/artifactcache) is covered when read-scope enforcement ships there. - Surface the receiver's error body message from getCacheEntry instead of a generic status-code error, so the cache read denied: prefix reaches callers - Re-throw CacheReadDeniedError from restoreCacheV1 and dispatch on it in the outer catch, mirroring restoreCacheV2 and the write-denied v1 handling - Add a v1 read-denied test

Copilot

Pull request overview

This PR improves cache restore resilience by detecting policy-driven cache read denials (insufficient read permissions) and surfacing them as a clear core.warning while treating the restore as a cache miss so workflows continue.

Changes:

Added read-denial detection via CACHE_READ_DENIED_PREFIX and a dedicated CacheReadDeniedError for targeted handling.
Updated both cache restore implementations (v1 REST + v2 Twirp/gRPC) to reclassify read-denied failures into a single warning and continue as a miss.
Adjusted v1 getCacheEntry to selectively surface the receiver’s denial message and added tests + release/version bumps.

Show a summary per file

File	Description
packages/cache/src/internal/cacheHttpClient.ts	Surfaces receiver error message only for `cache read denied:` so restore paths can reclassify it.
packages/cache/src/cache.ts	Adds read-denied prefix + error type and handles read-denied restores as warning + cache miss for both v1/v2.
packages/cache/tests/restoreCache.test.ts	Adds v1 tests asserting warning behavior and cache-miss semantics for read denial.
packages/cache/tests/restoreCacheV2.test.ts	Adds v2 test asserting warning behavior and cache-miss semantics for wrapped read-denied errors.
packages/cache/tests/cacheHttpClient.test.ts	Adds tests ensuring `getCacheEntry` only surfaces body for read-denied cases.
packages/cache/RELEASES.md	Documents the 6.2.0 behavior change.
packages/cache/package.json	Bumps `@actions/cache` version to 6.2.0.
packages/cache/package-lock.json	Updates lockfile version metadata to 6.2.0.

Review details

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Files not reviewed (1)

packages/cache/package-lock.json: Generated file

Files reviewed: 7/8 changed files
Comments generated: 1
Review effort level: Low

… unknown modes

Copilot

Review details

Files not reviewed (1)

packages/cache/package-lock.json: Generated file

Files reviewed: 11/12 changed files
Comments generated: 1
Review effort level: Low

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

…denied handling Address PR review feedback: - Merge the duplicate restore/save skip test.each blocks into single blocks parametrized over ACTIONS_CACHE_SERVICE_V2. - Drop the redundant CacheReadDeniedError catch arms; the typed error is not an HttpClientError so it already falls through to a non-fatal warning. - Clarify why read-denied classification happens both in getCacheEntry and cache.ts (dependency-free internal module cannot import the typed error).

Mirror the read-denied simplification on the save path. CacheWriteDeniedError is not an HttpClientError and its name does not match the ReserveCacheError arm, so it falls through to the same non-fatal warning. Logging behavior is unchanged (warns, never fails the run) and the exported type is still thrown internally for consumers and tests. Also refresh stale doc wording.

The two restoreCache tests exercised the identical warning + cache-miss path now that read-denied is no longer reclassified in the catch, so merge them into one. The read-denied prefix detection that actually branches on the message is covered by getCacheEntry tests in cacheHttpClient.test.ts.

boxofyellow

Looks good to me.

#2451) Backport of the read-denied and ACTIONS_CACHE_MODE cache-mode gating from the ESM v6.2.0 line (#2447) to the CommonJS v5 line, released as 5.2.0. Mirrors the earlier write-denied backport (#2435, 5.1.0). - Detect the `cache read denied:` prefix on download failures (v2 twirp path and v1 `_apis/artifactcache` path) and surface it as a core.warning without failing the run. - Honor ACTIONS_CACHE_MODE: skip restore when the effective cache-mode does not permit reads (none, write-only) and skip save when it does not permit writes (none, read), logging a single non-fatal core.info line. Unset or unrecognized modes are unchanged. - Add read-denied and cache-mode tests; bump to 5.2.0 with RELEASES entry. Copilot-Session: e96deec1-716e-4e14-acdf-a230139420a2 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Trusted release actions must not accidentally restore a poisoned shared GitHub cache. Set `ACTIONS_CACHE_MODE: none` in `release.yml` and each reusable workflow it calls so clients that support the variable skip cache reads and writes. Each reusable workflow needs its own setting because workflow-level environment variables do not propagate to called workflows. The shared binary-build workflow uses the same cache-disabled setting when invoked by CI. This is a cooperative client-side default, not token revocation or server-enforced denial. Older or independent clients, or code calling the cache API directly, can still access the service. The `@actions/cache` library's [6.2.0 change](actions/toolkit#2447) skips operations before contacting the cache backend; that is separate from its handling of server-denied requests. The release graph uses `setup-uv@v10.0.1` and `setup-python@v7.0.0`, whose pinned [setup-uv](https://github.com/astral-sh/setup-uv/blob/20cfd1bf945f4377ade1205e4dbc17946fc9a30d/package-lock.json) and [setup-python](https://github.com/actions/setup-python/blob/5fda3b95a4ea91299a34e894583c3862153e4b97/package-lock.json) dependencies include `@actions/cache@6.2.0`. Both honor this variable. The separate `actions/cache@v6.1.0` action still bundles `@actions/cache@6.1.0` and does not honor it; the release graph does not invoke that action directly. Stacked on astral-sh#761, which keeps the action-specific opt-outs, removes the docs Rust cache, and explicitly disables maturin's sccache integration. `release-prepare.yml`, same-run artifacts, and Depot's own cache are unchanged. Co-authored-by: Zanie Blue <contact@zanie.dev>

philip-gai · 2026-07-01T18:33:18Z

Description

This PR adds client-side cache-mode behavior to @actions/cache. It combines two related pieces of work:

Surface the service-side read-denied policy as a non-fatal warning.
Honor a new ACTIONS_CACHE_MODE environment variable to skip cache operations the effective mode does not permit.

Cache-mode values are none | read | write | write-only (hyphenated). It is a partial lattice, not linear: readable modes = {read, write}, writable modes = {write, write-only}, none = neither. The ACTIONS_CACHE_MODE env var is provided by the Actions runner, and is gated on the service side. When it is unset or unrecognized, behavior is identical to today (regression-safe).

Read-denied warning

When the cache service denies a download because the token has no readable scopes, the run should continue with a clear warning instead of a confusing failure.

Added CacheReadDeniedError and the shared cache read denied: prefix constant.
On the v2 restore path, the denial arrives as a wrapped 403; the restore dispatch detects the prefix and surfaces it as a core.warning, then returns a cache miss.
Matches the existing write-denied handling (cache write denied:) for consistency.

ACTIONS_CACHE_MODE skip

Skip operations the effective cache-mode does not permit, before any tar or network work.

Skip restore when the mode is not readable (none, write-only).
Skip save when the mode is not writable (none, read).
Restore skip returns a cache miss (undefined); save skip returns the existing not-saved sentinel (-1). Neither throws.
Exactly one core.info line per skip; extra detail (paths, key) is behind ACTIONS_STEP_DEBUG.
Unset or unrecognized modes are permissive, so behavior is unchanged.

Rationale for skipping restore on write-only: write-only tokens have no read scope, so a restore would be denied service-side and trip the read-denied warning. Skipping client-side avoids the wasted round-trip and gives a clearer message.

Companion changes

actions/runner exports ACTIONS_CACHE_MODE into the step environment.

Notes

packages/cache/RELEASES.md updated under the 6.2.0 entry.
Test coverage: full cache suite passing, including the read-denied dispatch and a cache-mode truth table (none/read/write/write-only plus unset and unknown regression cases).

https://github.com/github/actions-persistence/issues/1168

Mirror the existing cache write-denied handling on the restore path. When the receiver refuses a download URL because the run's token has no readable cache scopes, it returns a twirp PermissionDenied (HTTP 403). The twirp client wraps that 403 in a generic Error, so the stable 'cache read denied:' prefix is embedded in the message rather than at the start. - Add CACHE_READ_DENIED_PREFIX and CacheReadDeniedError - Dispatch on the prefix in the restoreCacheV2 catch block (V2 only), log a policy-specific warning, and report a cache miss so the run continues - Add a test mirroring the write-denied coverage

Re-throw CacheReadDeniedError from an inner try/catch around GetCacheEntryDownloadURL and dispatch on typedError.name in the outer catch, matching how saveCacheV2 handles CacheWriteDeniedError.

Extend the read-denied handling to Cache Service v1 so GHES (which forces v1 via _apis/artifactcache) is covered when read-scope enforcement ships there. - Surface the receiver's error body message from getCacheEntry instead of a generic status-code error, so the cache read denied: prefix reaches callers - Re-throw CacheReadDeniedError from restoreCacheV1 and dispatch on it in the outer catch, mirroring restoreCacheV2 and the write-denied v1 handling - Add a v1 read-denied test

Copilot

Pull request overview

This PR improves cache restore resilience by detecting policy-driven cache read denials (insufficient read permissions) and surfacing them as a clear core.warning while treating the restore as a cache miss so workflows continue.

Changes:

Added read-denial detection via CACHE_READ_DENIED_PREFIX and a dedicated CacheReadDeniedError for targeted handling.
Updated both cache restore implementations (v1 REST + v2 Twirp/gRPC) to reclassify read-denied failures into a single warning and continue as a miss.
Adjusted v1 getCacheEntry to selectively surface the receiver’s denial message and added tests + release/version bumps.

Show a summary per file

File	Description
packages/cache/src/internal/cacheHttpClient.ts	Surfaces receiver error message only for `cache read denied:` so restore paths can reclassify it.
packages/cache/src/cache.ts	Adds read-denied prefix + error type and handles read-denied restores as warning + cache miss for both v1/v2.
packages/cache/tests/restoreCache.test.ts	Adds v1 tests asserting warning behavior and cache-miss semantics for read denial.
packages/cache/tests/restoreCacheV2.test.ts	Adds v2 test asserting warning behavior and cache-miss semantics for wrapped read-denied errors.
packages/cache/tests/cacheHttpClient.test.ts	Adds tests ensuring `getCacheEntry` only surfaces body for read-denied cases.
packages/cache/RELEASES.md	Documents the 6.2.0 behavior change.
packages/cache/package.json	Bumps `@actions/cache` version to 6.2.0.
packages/cache/package-lock.json	Updates lockfile version metadata to 6.2.0.

Review details

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Files not reviewed (1)

packages/cache/package-lock.json: Generated file

Files reviewed: 7/8 changed files
Comments generated: 1
Review effort level: Low

… unknown modes

Copilot

Review details

Files not reviewed (1)

packages/cache/package-lock.json: Generated file

Files reviewed: 11/12 changed files
Comments generated: 1
Review effort level: Low

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

…denied handling Address PR review feedback: - Merge the duplicate restore/save skip test.each blocks into single blocks parametrized over ACTIONS_CACHE_SERVICE_V2. - Drop the redundant CacheReadDeniedError catch arms; the typed error is not an HttpClientError so it already falls through to a non-fatal warning. - Clarify why read-denied classification happens both in getCacheEntry and cache.ts (dependency-free internal module cannot import the typed error).

Mirror the read-denied simplification on the save path. CacheWriteDeniedError is not an HttpClientError and its name does not match the ReserveCacheError arm, so it falls through to the same non-fatal warning. Logging behavior is unchanged (warns, never fails the run) and the exported type is still thrown internally for consumers and tests. Also refresh stale doc wording.

The two restoreCache tests exercised the identical warning + cache-miss path now that read-denied is no longer reclassified in the catch, so merge them into one. The read-denied prefix detection that actually branches on the message is covered by getCacheEntry tests in cacheHttpClient.test.ts.

boxofyellow

Looks good to me.

#2451) Backport of the read-denied and ACTIONS_CACHE_MODE cache-mode gating from the ESM v6.2.0 line (#2447) to the CommonJS v5 line, released as 5.2.0. Mirrors the earlier write-denied backport (#2435, 5.1.0). - Detect the `cache read denied:` prefix on download failures (v2 twirp path and v1 `_apis/artifactcache` path) and surface it as a core.warning without failing the run. - Honor ACTIONS_CACHE_MODE: skip restore when the effective cache-mode does not permit reads (none, write-only) and skip save when it does not permit writes (none, read), logging a single non-fatal core.info line. Unset or unrecognized modes are unchanged. - Add read-denied and cache-mode tests; bump to 5.2.0 with RELEASES entry. Copilot-Session: e96deec1-716e-4e14-acdf-a230139420a2 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Trusted release actions must not accidentally restore a poisoned shared GitHub cache. Set `ACTIONS_CACHE_MODE: none` in `release.yml` and each reusable workflow it calls so clients that support the variable skip cache reads and writes. Each reusable workflow needs its own setting because workflow-level environment variables do not propagate to called workflows. The shared binary-build workflow uses the same cache-disabled setting when invoked by CI. This is a cooperative client-side default, not token revocation or server-enforced denial. Older or independent clients, or code calling the cache API directly, can still access the service. The `@actions/cache` library's [6.2.0 change](actions/toolkit#2447) skips operations before contacting the cache backend; that is separate from its handling of server-denied requests. The release graph uses `setup-uv@v10.0.1` and `setup-python@v7.0.0`, whose pinned [setup-uv](https://github.com/astral-sh/setup-uv/blob/20cfd1bf945f4377ade1205e4dbc17946fc9a30d/package-lock.json) and [setup-python](https://github.com/actions/setup-python/blob/5fda3b95a4ea91299a34e894583c3862153e4b97/package-lock.json) dependencies include `@actions/cache@6.2.0`. Both honor this variable. The separate `actions/cache@v6.1.0` action still bundles `@actions/cache@6.1.0` and does not honor it; the release graph does not invoke that action directly. Stacked on astral-sh#761, which keeps the action-specific opt-outs, removes the docs Rust cache, and explicitly disables maturin's sccache integration. `release-prepare.yml`, same-run artifacts, and Depot's own cache are unchanged. Co-authored-by: Zanie Blue <contact@zanie.dev>

philip-gai added 7 commits July 1, 2026 12:24

chore(cache): trim comments, bump to 6.2.0, add RELEASES entry
4262e25

refactor(cache): dispatch read-denied by error name to mirror write path
4fe17c4
Re-throw CacheReadDeniedError from an inner try/catch around GetCacheEntryDownloadURL and dispatch on typedError.name in the outer catch, matching how saveCacheV2 handles CacheWriteDeniedError.

refactor(cache): only surface receiver body for read-denied on v1
0555e65

test(cache): assert getCacheEntry only surfaces body for read-denied
47f4147

test(cache): cover non-read-denied getCacheEntry passthrough on v1
3452118

philip-gai requested a review from Copilot July 1, 2026 18:42

Copilotstarted reviewing on behalf of philip-gai July 1, 2026 18:43 View session

CopilotAI reviewed Jul 1, 2026
View reviewed changes

Comment threadpackages/cache/src/cache.ts Outdated

philip-gai added 2 commits July 1, 2026 15:23

refactor(cache): share read-denied prefix via constants to avoid drift
b504f4f

feat(cache): skip restore/save per ACTIONS_CACHE_MODE
22b0367

philip-gai mentioned this pull request Jul 2, 2026
feat: expose effective cache-mode to steps via ACTIONS_CACHE_MODE actions/runner#4538
Merged

philip-gai changed the title ~~Handle cache read error due to insufficient read permissions~~feat(cache): add cache-mode client behavior (read-denied warning + ACTIONS_CACHE_MODE skip)Jul 2, 2026

test(cache): expand ACTIONS_CACHE_MODE skip coverage across v1/v2 and…
15fe834
… unknown modes

philip-gai requested a review from Copilot July 6, 2026 14:29

Copilotstarted reviewing on behalf of philip-gai July 6, 2026 14:30 View session

CopilotAI reviewed Jul 6, 2026
View reviewed changes

Comment threadpackages/cache/src/cache.ts Outdated

fix copilot pr feedback
a4b1891
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

philip-gai marked this pull request as ready for review July 8, 2026 14:58

philip-gai requested a review from a team as a code owner July 8, 2026 14:58

jasongin previously approved these changes Jul 9, 2026
View reviewed changes

Comment threadpackages/cache/src/internal/config.ts Outdated

docs(cache): remove internal reference from cache-mode comment
77bc4ba

philip-gai dismissed jasongin’s stale review via 77bc4baJuly 10, 2026 14:10

jasongin previously approved these changes Jul 10, 2026
View reviewed changes

boxofyellow reviewed Jul 10, 2026
View reviewed changes

philip-gai added 2 commits July 10, 2026 15:34

philip-gai dismissed jasongin’s stale review via 3e6533eJuly 10, 2026 20:34

boxofyellow approved these changes Jul 13, 2026
View reviewed changes

philip-gai merged commit ffdc20e into mainJul 13, 2026
25 of 27 checks passed

philip-gai deleted the philip-gai/cache-read-denied-warning branch July 13, 2026 15:03

This was referenced Jul 13, 2026
feat: adopt @actions/cache 6.2.0 (cache-mode skip + read-denied warning) actions/cache#1781
Merged
feat: backport cache read-denied + ACTIONS_CACHE_MODE handling (5.2.0) #2451
Merged

philip-gai mentioned this pull request Jul 15, 2026
chore(deps): bump @actions/cache to 6.2.0 actions/setup-java#1128
Merged
3 tasks

zaniebot mentioned this pull request Aug 17, 2026
Disable cache-aware actions throughout release workflows astral-sh/uv-dev#763
Closed

astral-automations-botBot mentioned this pull request Aug 18, 2026
Disable cache-aware actions throughout release workflows astral-sh/uv#21196
Merged