Design: serving actions/cache from the Pitlane host
Status: implemented in v0.3 (internal/cache, internal/pool/actionscache.go). Sources checked on 2026-11-15 against actions/runner v2.338.2 (the version pinned in images/runner/Dockerfile) and @actions/cache 6.3.0 (actions/toolkit main).
Goal
actions/cache, and every action built on @actions/cache (setup-node, setup-python, setup-go, setup-java with cache:, pnpm/action-setup, ruby/setup-ruby, …), should restore and save at LAN/disk speed from the Pitlane host instead of GitHub's Azure-backed cache, without any workflow change, and without ever breaking a job: when anything is off, jobs use GitHub's cache as before.
How the cache protocol works today
Who tells the action where the cache is
GitHub sends the runner a job message whose SystemVssConnection endpoint carries the service URLs (CacheServerUrl, ResultsServiceUrl, …) and a job token. For every JavaScript action step, Runner.Worker (src/Runner.Worker/Handlers/NodeScriptActionHandler.cs) builds the step environment and, after copying the job's env: and the runner's own environment, sets:
| Variable | Value |
|---|---|
ACTIONS_RUNTIME_TOKEN | job-scoped JWT, sent as Authorization: Bearer |
ACTIONS_CACHE_URL | legacy cache service (v1), only when CacheServerUrl is in the message |
ACTIONS_RESULTS_URL | results service (results-receiver.actions.githubusercontent.com): cache v2 and artifacts v4 |
ACTIONS_CACHE_SERVICE_V2 | True when the job has the actions_uses_cache_service_v2 feature flag (all of github.com since 2025) |
ACTIONS_CACHE_MODE | new: read/write/write-only/none policy, enforced by the client |
It then runs externals/<node20|node24>/bin/node <action script>. Because the runner assigns these variables last, setting ACTIONS_CACHE_URL or ACTIONS_RESULTS_URL on the runner container (or in a workflow's env:) has no effect: the handler overwrites them.
What the client does (@actions/cache)
internal/config.ts:
getCacheServiceVersion(): isGhes() ? 'v1' : (ACTIONS_CACHE_SERVICE_V2 ? 'v2' : 'v1')
getCacheServiceURL(): v1 → ACTIONS_CACHE_URL || ACTIONS_RESULTS_URL ; v2 → ACTIONS_RESULTS_URL- v2 (github.com default): Twirp/JSON on
ACTIONS_RESULTS_URL+/twirp/github.actions.results.api.v1.CacheService/(GetCacheEntryDownloadURL,CreateCacheEntry,FinalizeCacheEntryUpload). The service returns signed Azure Blob URLs; the client uploads/downloads with the Azure SDK (block blobs) directly. The Twirp URL is built with an absolute path (new URL('/twirp/…', base)), so a path prefix in the base URL is lost. - v1 (legacy, still used by GHES and still shipped in the client): REST on
ACTIONS_CACHE_URL+_apis/artifactcache/:GET cache?keys=k1,k2&version=V→200 {cacheKey, scope, creationTime, archiveLocation}or204POST caches {key, version, cacheSize}→{cacheId}(409when it exists or is being written)PATCH caches/{id}withContent-Range: bytes a-b/*, parallel chunksPOST caches/{id} {size}commitsarchiveLocationis fetched with a plainGET(no auth header): it must be a self-authenticating URL. The base URL is concatenated as a string, so a path prefix survives.
version is a hash of the paths, compression method and OS flag, so it already separates incompatible archives. GitHub resolves a lookup like this (documented in "Caching dependencies", "Matching a cache key"): first in the current branch scope, exact key match, then prefix matches of key and of each restore-keys entry in order (newest first); then the same in the base branch (pull requests) and the default branch. Entries are immutable; a save of an existing key fails with "another job may be creating this cache" (a warning). Cache errors in restoreCache/saveCache are logged as warnings and never fail the step (only input validation errors do).
The job token carries the branch scopes in its ac claim, a JSON string like [{"Scope":"refs/heads/feature","Permission":3},{"Scope":"refs/heads/main","Permission":1}] (1 = read, 2 = write). BuildKit's type=gha exporter and Forgejo's server rely on the same claim.
What others do
| Project (license) | How jobs reach it | Notes |
|---|---|---|
| falcondev-oss/github-actions-cache-server (MIT) | forked runner image reading CUSTOM_ACTIONS_RESULTS_URL, or sed on Runner.Worker.dll renaming the UTF-16 literal ACTIONS_RESULTS_URL to a dummy name, then ACTIONS_RESULTS_URL set on the runner | v2 API. The patch also redirects artifacts v4 (same variable). Runner self-update silently restores the stock binary; needs --disableupdate. |
| RunsOn "Magic Cache" (commercial) | a runs-on/action step writes ACTIONS_CACHE_URL/ACTIONS_RESULTS_URL to $GITHUB_ENV, pointing at a sidecar on the VM | needs a workflow change; the sidecar forwards artifact calls to GitHub. |
| nektos/act, Gitea/Forgejo act_runner (MIT) | they are the runner, so they set ACTIONS_CACHE_URL themselves | v1 API server embedded in the runner (pkg/artifactcache). Not applicable to the official runner. |
| Blacksmith, WarpBuild, Ubicloud, Namespace (commercial) | own VM images and network; some intercept the results/cache hosts transparently | not reusable. |
Options for Pitlane
- Binary patch of
Runner.Worker.dll(falcondev). Works, but it is tied to the runner build (string literal layout), must be redone for every runner image (users can pick their own image), and renamingACTIONS_RESULTS_URLalso captures artifacts v4, so Pitlane would have to proxy the artifact Twirp calls to GitHub, where a proxy bug breaksupload-artifact(a hard failure, not a warning). Inside job containers (container:), only the handler's variables are passed, so the dummy name leaks in and the cache silently breaks there. - Environment overrides only. Impossible: the handler overwrites the variables (above).
- Transparent proxy / MITM of
results-receiver.actions.githubusercontent.com. Needs DNS or iptables tricks in every slot plus a CA trusted by Node (NODE_EXTRA_CA_CERTS) and by BuildKit; a job controls its slot's Docker daemon and network; artifacts and logs go through the same host. Far too invasive and fragile. - Node shim in the externals + v1 protocol (chosen). Pitlane already copies the runner image's
externals/into a per-slot volume (job containers need it at/__e). While copying, Pitlane replaces everyexternals/node*/bin/nodewith a copy of its own (static) binary, kept next to the real one (node.pitlane). Started asnode, Pitlane runs as a shim before anything else (internal/nodeshim): only when Pitlane injectedPITLANE_CACHE_URLinto the runner container, it setsACTIONS_CACHE_URLto Pitlane's server and removesACTIONS_CACHE_SERVICE_V2, thenexecves the real Node binary with the same arguments and the rest of the environment byte for byte. The client then speaks v1 to Pitlane.ACTIONS_RESULTS_URLis untouched: artifacts, OIDC, logs and job summaries keep going to GitHub.
Why option 4
- Fails safe at every layer. No
PITLANE_CACHE_URL(feature off, strict job, cache listener down, job container) → the shim is a plainexecve, jobs use GitHub's cache exactly as today. Pitlane's server down or failing → the client logs a warning and the job goes on (cache miss / save skipped). A future@actions/cachewithout v1 would ignoreACTIONS_CACHE_URLand fall back to v2, i.e. GitHub's cache. - No binary patch, any runner image. Nothing in
Runner.Workerchanges; it works with the official image or a custom one, and survives runner upgrades (the externals copy is redone for each image, the shim with it). - Artifacts never go through Pitlane.
- Job containers keep working. The shim is a static binary (no libc), so it runs in glibc and musl (
node*_alpine) job containers alike; it only needs the kernel. The runner does not passPITLANE_CACHE_URLinto job containers, so their actions use GitHub's cache (Pitlane's address is not reachable from the slot daemon's networks anyway). - v1 is simple (4 endpoints, ranges written straight to a file) and a path prefix survives in the base URL, which carries Pitlane's per-job credential and the repository.
Risks: GitHub removing v1 from the client (fallback to GitHub, see above); ACTIONS_CACHE_MODE keeps being enforced by the client, which reads it from the environment. BuildKit's type=gha cache (docker/build-push-action) receives the same variables and speaks v1 too; it is served by Pitlane only when BuildKit can reach the host (usually not: it runs in the slot daemon's own network); otherwise it fails like any unreachable gha cache. Pitlane already recommends the slot's local build cache instead.
Pitlane design
Server (internal/cache)
- Built into the Pitlane process, on its own listener (
--cache-listen, default:8091), separate from the UI (no session auth, no reverse proxy). - The runner reaches it at the slot network's gateway (the host) on that port:
PITLANE_CACHE_URL=http://<gateway>:8091/<token>/. When Pitlane itself runs in a container (Compose), a published port is not reachable from another bridge network (Docker's inter-network isolation), and joining the slot networks itself would hand jobs a direct path to Pitlane's UI and API. Pitlane starts insteadpitlane-cache-forward(its own image runningpitlane cache-forward, asnobody, no capabilities, read-only root), which joins the slot networks like the mirror and relays only the cache port to Pitlane's container by name. The shim appends$GITHUB_REPOSITORY/.
Node shim (internal/nodeshim)
- Detection:
os.Executable()(/proc/self/exe, sonodejs -> nodesymlinks resolve) has the base namenode. Pitlane itself is never installed under that name, so the normal command cannot enter shim mode. The check runs in the package'sinit; the package only imports the standard library, so the shim runs before the rest of Pitlane initialises (about 5 ms per Node start). execve, no fork: the real Node replaces the shim, so exit codes, signals, stdio and the process ID are the runner's own. A missingnode.pitlaneexits 127 with a message.- Install (
shimScript, in the container that copies the externals): Pitlane streams its running binary (/proc/self/exe, valid even after a self-update replaced the file) into that container. The script first runs it asnodein front of itself in a temporary directory (it must print Pitlane's version); if that fails, no runtime is touched. Each runtime is then switched withmv(real binary tonode.pitlane, shim tonode) and restored on any error; the runtimes share one copy (hard links). A failure leaves the stock Node: jobs use GitHub's cache. - Storage:
<data dir>/actions-cache/, one<id>.json(metadata) and one<id>.tgz(archive) per entry, uploads intmp/. The index is rebuilt by scanning at start; no database table, no migration. - Reservations must declare their size; unfinished uploads together stay within the size limit (32 per runner at most) and are dropped when their runner is revoked or after 24 hours.
- Lookup semantics as GitHub (scopes from the
acclaim, then exact key, key prefix, each restore key prefix, newest first). Entries are immutable, a reserve on an existing or pending key returns 409. - Size limit (setting, default 20 GB) with LRU eviction (last restore time). Each owner may use a share of it (default 50 %, at least one byte): reservations over the owner's remaining share are refused, and a commit that puts the owner over its share evicts its own least recently used entries (never the one just saved) before the global LRU runs. One owner thus cannot grow past its share at the others' expense; when several owners within their shares fill the cache together, the global LRU still evicts across owners. Plus a hook in the low-disk pruning (
internal/pool/disk.go): after idle slots' build caches and images, before per-owner cache volumes.
Isolation and authentication
- Per-job credential. For each non-strict runner, the pool registers the runner with the cache server and gets a token
<runner name>.<HMAC-SHA256(key, runner name, owner, repository restriction)>; the key is random, kept in the data directory (jobs cannot read it), and the runner name is random and used for one job only. The token is in the runner container's environment only. It is valid while the runner is registered:Releaserevokes it, and a runner adopted after a restart is re-registered from its container labels (owner, target), so tokens survive restarts. - Owner isolation (hard). The token maps to the target's GitHub owner (from Pitlane's own state, never from the job). The repository in the URL must belong to that owner, and for a repository target it must be that repository. Entries are stored per
owner/repo; a job can never read or write another owner's entries. - Repository and branch scoping (best effort, like GitHub). For an organization target, the repository comes from
GITHUB_REPOSITORY(set by the runner); the branch scopes come from the job token'sacclaim, which Pitlane decodes but cannot verify (GitHub does not publish the signing key). A malicious job could therefore read or write the cache of another repository or branch of the same owner. That is the same trust level as the rest of Pitlane's caches, which are shared per owner (toolcache,~/.cache, Docker layers, pnpm store) with no branch scoping at all. - Strict jobs get no Pitlane cache. No
PITLANE_CACHE_URLis injected; their actions use GitHub's cache, which GitHub isolates per repository and branch (including fork pull requests). - Cache scope
shareddoes not merge actions caches across owners: unlike the volumes, entries stay per repository, as on GitHub.
Settings and UI
actions_cache(default on),actions_cache_gb(default 20) andactions_cache_owner_pct(default 50: the share of the size one owner may use, reservations included; over it, the owner's own least recently used entries are evicted before the global LRU applies) in the settings table; Settings → Caches shows them with the current size, entry count and hit/miss counters since start.- Turning it off stops injecting
PITLANE_CACHE_URLfor new runners (the shim stays, inert) and keeps the stored entries until they are evicted or the directory is removed.
Tests
internal/cache: protocol handlers, matching rules, branch scopes, owner and repository isolation, tokens (revocation, identity binding, restarts), upload limits, LRU eviction, index reload.internal/nodeshim: environment transformation (names with-or., empty values,=and newlines in values, duplicates) and the shim exec (arguments,argv[0], exit code, environment byte for byte).internal/pool:TestShimScriptinstalls the built Pitlane binary over fake runtimes (idempotent, shared copy), and a missing or broken binary leaves them untouched.PITLANE_E2E=1 go test ./internal/cache -run Toolkitdrives the real@actions/cacheclient (6.3.0 by default;PITLANE_E2E_TOOLKIT=4.1.0or5.3.0for the versions bundled inactions/cache@v4/v5) through the shim, with the variables the runner sets on github.com (ACTIONS_CACHE_SERVICE_V2=True, GitHub URLs): 40 MB save in two chunks, restore byrestore-keys, miss.PITLANE_E2E_DOCKER=1 go test ./internal/pool -run PinnedRunnerinstalls the shim (the built Pitlane binary) into the externals of the runner image pinned inimages/runner/Dockerfile, starts each Node runtime through it with no shell in between (glibc ones in the runner image,*_alpinein an Alpine container, externals at/__e), checks that hyphenated inputs survive and thatACTIONS_CACHE_URLis rewritten only withPITLANE_CACHE_URL, and runs the real@actions/coregetBooleanInput('include-hidden-files')through it.
Lessons
- Never put a shell between the runner and Node. v0.2.0-rc.1 used a 6-line
shscript as the shim. POSIX shells only export variables whose names are valid identifiers, and the runner passes action inputs asINPUT_<NAME>with the name upper-cased but hyphens kept (INPUT_INCLUDE-HIDDEN-FILES,INPUT_FETCH-DEPTH).exec nodefromshsilently dropped every hyphenated input:actions/upload-artifact@v4failed withInput does not meet YAML 1.2 "Core Schema" specification: include-hidden-files, and the failed job then skippedactions/cache's post-step save. The unit test fed the shim only identifier-safe variables, so it passed. The shim must hand the environment over untouched except for the variables it means to change, and its tests must use the names the runner really produces. - A
NODE_OPTIONS=--requirepreload was rejected. It is inherited by every Node process of the job (run:steps, setup-node's Node, tools), is overwritten by a workflow's ownNODE_OPTIONS, and points at a file that does not exist in job containers or other images (Node then refuses to start). Replacing thenodebinary affects only the runner's JavaScript actions.