Skip to content

docs(cache-server): document direct download URL lifetime, token audience and the unverified-token guard - #7

Merged
LouisHaftmann merged 2 commits into
masterfrom
docs/cache-server-direct-download-token-validation
Oct 28, 2026
Merged

LouisHaftmann merged 2 commits into
masterfrom
docs/cache-server-direct-download-token-validation

Conversation

@LouisHaftmann

Copy link
Copy Markdown
Contributor

📝 Summary

falcondev-oss/github-actions-cache-server#309 stops the server from handing signed storage URLs to unverified tokens and adds two settings. The cache-server docs didn't cover any of it, so anyone running ENABLE_DIRECT_DOWNLOADS=true with SKIP_TOKEN_VALIDATION=true would hit a startup error with no docs to explain it.

This documents the new env vars in the Getting Started reference:

 #### ENABLE_DIRECT_DOWNLOADS
+  ::: danger  refused together with SKIP_TOKEN_VALIDATION (breaking for setups that ran both)
+#### DIRECT_DOWNLOAD_URL_TTL_SECONDS   1-3600, default 600, Helm config.directDownloadUrlTtlSeconds
 #### ACTIONS_TOKEN_JWKS_URL
+#### ACTIONS_TOKEN_AUDIENCE            optional comma-separated aud values
 #### SKIP_TOKEN_VALIDATION
+  cannot be combined with ENABLE_DIRECT_DOWNLOADS
+#### UNSAFE_ALLOW_DIRECT_DOWNLOADS_WITHOUT_TOKEN_VALIDATION   default false, local testing only

The exp requirement and the read/write permission bit flags aren't documented, because these docs don't describe token validation at the claim level.

✅ Verification

  • pnpm build in packages/gha-cache-server: build complete. The rendered page has the anchors #direct-download-url-ttl-seconds, #actions-token-audience and #unsafe-allow-direct-downloads-without-token-validation, and the links in the new copy point to them.
  • prettier --check passes.

🔍 Reviews

Review Found Fixed
bug 1 1

The fix dropped an ACTIONS_TOKEN_AUDIENCE example (https://github.com/my-org). That's the OIDC ID token aud, which may not match the runner runtime token the server checks.

💥 Merge danger

Door: two-way

Blast Radius: docs

⚠️ Needs attention

  • Don't merge until #309 ships in a release. It merged on 2026-10-28, but the latest release (v9.10.0) doesn't include it yet, so the docs would describe behavior users don't have.

🤖 Generated with Claude Code

LouisHaftmann and others added 2 commits October 28, 2026 08:50
…and the unverified-token guard

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@LouisHaftmann
LouisHaftmann merged commit a038ad8 into master Oct 28, 2026
@LouisHaftmann
LouisHaftmann deleted the docs/cache-server-direct-download-token-validation branch October 28, 2026 07:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant