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>

boxofyellow · 2026-07-10T19:25:36Z

  if (!isSuccessStatusCode(response.statusCode)) {
+    // Only surface the receiver's body for a `cache read denied:` policy denial
+    // so callers can dispatch on it; keep the generic message otherwise.
+    const errorMessage = response.error?.message


it seems odd to me that only have this "fix up the error" message info in the read path. It seams like the write path benefit from it. And a write read only setup seems far more helpful than a write only one in my eyes.

We already have a block for CacheWriteDeniedError, this is just adding it for the read path whenever the scope is write-only or none and reads are denied

I think some of my confusion that we have the error fixing up code in both packages/cache/src/internal/cacheHttpClient.ts and packages/cache/src/cache.ts for the read case, while for write we only have it in packages/cache/src/cache.ts (it also does not seen to call out that likely your scope is blocking you. I don't know if there are other cases in the write path that could yield a 403)

Oh, the write path's reserveCache method already returns a response of statusCode + error to clients, but read's getCacheEntry only throws a plain string Error. I didn't want clients to have to update to a new response structure, so we just throw with the cache read denied: prefix and cache.ts then inspects it and throws it as a CacheReadDeniedError

And we do call it out, with the message cache read denied: token has no readable scopes

boxofyellow · 2026-07-10T19:33:11Z

+        enableCrossOsArchive
+      })
+    } catch (error) {
+      // The GHES v1 artifact cache service returns HTTP 403 with a


Why is the error fixing up logic here and in getCacheEntry?

I think I responded to this in #2447 (comment) 😄

boxofyellow · 2026-07-10T19:41:04Z

+      if (errorMessage.includes(CACHE_READ_DENIED_PREFIX)) {
+        throw new CacheReadDeniedError(errorMessage)
+      }
+      throw error


Right below we we don't throw on a miss, we return undefined when we can't find it the cache, the equivalent to a 404. Do we want to be throwing on 403?

Yeah, this will just route as to the outer catch the same way it did before I added a catch here, and we want to be able to throw our CacheReadDeniedError and rethrow other errors we may get

…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.

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

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

Copilot AI reviewed Jul 1, 2026

View reviewed changes

Comment thread packages/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

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

Copilot AI reviewed Jul 6, 2026

View reviewed changes

Comment thread packages/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 thread packages/cache/src/internal/config.ts Outdated

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

77bc4ba

philip-gai dismissed jasongin’s stale review via 77bc4ba July 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 3e6533e July 10, 2026 20:34

Uh oh!

Conversation

philip-gai commented Jul 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Read-denied warning

ACTIONS_CACHE_MODE skip

Companion changes

Notes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Review details

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Review details

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

boxofyellow Jul 10, 2026

Choose a reason for hiding this comment

Uh oh!

philip-gai Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

boxofyellow Jul 10, 2026

Choose a reason for hiding this comment

Uh oh!

philip-gai Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

boxofyellow Jul 10, 2026

Choose a reason for hiding this comment

Uh oh!

philip-gai Jul 10, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

boxofyellow Jul 10, 2026

Choose a reason for hiding this comment

Uh oh!

philip-gai Jul 10, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

philip-gai commented Jul 1, 2026 •

edited

Loading

philip-gai Jul 10, 2026 •

edited

Loading

philip-gai Jul 10, 2026 •

edited

Loading