Sticky Disks

Sticky disks are in beta.

A sticky disk is a disk that Tenki keeps between jobs, identified by a key you choose. A job mounts it at a path and reads and writes files there like any other directory. When a job that is allowed to publish succeeds, what it wrote becomes the starting point for the next job that mounts the same key. The action mounts the disk when its step runs, without packing and restoring the cache as a tarball.

That makes sticky disks a good fit for caches that are expensive to rebuild and awkward to archive, such as dependency directories and compiler caches. Your jobs must still work with an empty cache. Keep anything you cannot rebuild in durable storage, and use workflow artifacts for build outputs you need to keep.

Use the LuxorLabs sticky disk action at @v1 in workflows to follow compatible v1 releases.

Sticky disks run on Linux runners. Sticky disks are enabled by default for workspaces; the Runners > Cache & Disks tab shows whether they are on and lists your sticky disks. Tenki support can change the setting for a workspace.

How it works

Each key holds a chain of immutable generations. When a job mounts a key, it gets its own writable view of the currently selected generation, so parallel jobs never edit one shared live filesystem. After a publishing job succeeds, Tenki verifies what it wrote and promotes it to a new generation, which later jobs start from.

Keys are scoped to your workspace, the repository, the region the job ran in, and the runner architecture. Two repositories using the key npm-cache get two separate disks, and an x64 job never reads an arm64 job's disk.

The action reports what it got through its source output:

A cache miss starts the job cold. A fallback also lets the job run cold unless fail-on-error is set. Some failures cannot safely fall back; see When storage is unavailable.

Use a sticky disk in a workflow

Mount the disk before the step that fills it:

jobs:
  test:
    runs-on: tenki-standard-medium-4c-8g
    steps:
      - uses: actions/checkout@v6
      - id: sticky
        uses: LuxorLabs/stickydisk@v1
        with:
          key: npm-node22-v1
          path: ~/.npm
      - run: npm ci
      - run: echo "sticky disk source is ${{ steps.sticky.outputs.source }}"

No separate sticky disk runner label is needed.

Choosing a key

The key is a plain string of up to 200 characters, matched exactly. There is no prefix matching and no restore-keys input.

Unlike actions/cache, the key does not need a lockfile hash in it: the disk keeps its contents across runs and starts from whatever the last publishing job left there. Use a stable name per cache, such as npm-node22-v1 or go-build-amd64-v1, and change it when a tool upgrade or a cache format change makes the old contents unusable. A commit SHA in the key prevents any reuse between commits.

Inputs

Outputs

The action also writes a Sticky disk block to the job summary with the mount mode, the generation, any fallback reason, the outcome of the previous job's candidate, and whether publication was requested.

Where a disk can be mounted

path can be absolute, ~-relative, or relative to the job's workspace. Whichever form you use, it has to resolve to a directory that is empty or does not exist yet, has no symlink anywhere on the way to it, and sits under one of:

• the job's workspace, $GITHUB_WORKSPACE, but not the workspace directory itself
• ~/.cache, ~/.npm, ~/.cargo, ~/.gradle, or ~/go/pkg/mod

Other system directories are rejected, and so is a path that overlaps another sticky disk mounted in the same job. Mount the disk before anything writes to the path; a step that fills the directory first leaves the action nothing to mount. Repeating the same mount in the same job returns the same disk rather than creating another one.

Publishing

With commit: auto, a job that is allowed to publish asks Tenki to publish what it wrote once it succeeds. Publication is not immediate and not guaranteed. Tenki publishes only after all of the following:

1. The job is allowed to publish under the workspace policy.
2. The action's post step records the request to publish and flushes the disk.
3. GitHub reports the job as successful.
4. The disk is detached from the VM and passes Tenki's filesystem check.
5. The key still accepts the candidate: no other job has published since this one started, and the key and policy have not changed.

A cancelled job, a failed job, or a job whose post step never ran publishes nothing, and the current generation stays as it was. The post step can finish while publication is still pending; the job summary and the cache's recent runs show the final outcome.

Read-only jobs

Set commit: never for jobs that should read the cache but never change it:

- uses: LuxorLabs/stickydisk@v1
  with:
    key: npm-node22-v1
    path: ~/.npm
    commit: never

Such a job mounts as readonly. readonly describes the shared generation, not the directory: the job sees the whole cache and can change or add files, and those changes stay on its runner and are thrown away when the job ends.

Concurrent jobs

Any number of read-only jobs can use the same generation at once, each with its own private writes. A publishing job can run alongside them without changing what they see.

If two publishing jobs start from the same generation, the first one to be published advances the cache. The other candidate is discarded rather than overwriting the newer generation, and the two sets of changes are never merged; both jobs can still succeed. Use separate keys for independent caches, or GitHub workflow concurrency, if publishers must run one after another.

Branch Protection

Branch Protection is on for every new workspace. With it on, only push, schedule, and workflow_dispatch jobs on the repository's default branch publish. Every other job, including a pull request from a fork, gets a read-only view even with commit: auto. Workspaces whose sticky disk policy was created before this default keep whatever value they have; Tenki support can change it for you. Turning Branch Protection off changes who can publish; it does not remove the workspace or repository scoping.

Limits and retention

Tenki support can change these for a workspace.

Each sticky disk is a fixed-size disk, so a cache cannot grow past it. A publishing job reserves a full disk of that size from the workspace budget before it mounts, even if what it finally stores is smaller. The budget also counts retained generations and candidates that are still being checked.

An eleventh mount in one job, or a publishing job in a workspace whose budget is full, falls back to local disk rather than failing the job. Read-only jobs can still use existing generations when the budget has no room for another publisher. The Runners > Cache & Disks tab shows how much of the budget is in use.

Older generations beyond the retained count are removed, except the selected generation and any generation a running job still reads from. A key that no job mounts for seven days has its generations removed; the key itself survives and starts cold on its next run. Removal happens in the background, so storage is not always freed the moment a generation is retired.

Managing caches in the dashboard

Runners > Cache & Disks lists sticky disks alongside GitHub Actions cache entries, tagged by kind, with search and a kind filter. Selecting a sticky disk shows its repository, region, architecture, current generation, stored size, expiry, and recent runs.

Clear this cache retires every generation of that key so the next run starts cold. It also stops any publishing job that is already running from bringing the cleared contents back. The key can be used again right away.

Turning sticky disks on or off for a workspace, disabling a single key, pinning a generation, rolling back to an older one, and changing limits are handled by Tenki support. While sticky disks are off for a workspace, new mounts fall back to local disk, or fail with fail-on-error: true, and existing contents are kept.

When storage is unavailable

For a mount failure with a known safe outcome, the action sets source=fallback, writes the reason to the job summary, and lets the job run on the runner's own disk. Set fail-on-error: true to make that a step failure instead, for a job where running cold is not worth the minutes.

Once the action starts, two cases always fail the step, whatever fail-on-error says, because it is not known whether the disk was attached:

• the storage state is reported as degraded
• the mount request gets no clear answer, for example because it timed out

The job can also fail before the action runs if Tenki cannot issue its sticky disk capability. In that case, the action cannot report source=fallback or write a job summary.

Rerun the job. If storage is lost after a disk was attached, Tenki can cancel the job so that damaged data is never published.

Troubleshooting

When reporting a problem, include the links to the affected runs and the Sticky disk block from the job summary.

Sticky disks or the Actions cache

Both can be used in the same workflow, and neither replaces the other.

Reach for a sticky disk when the cache is large, changes a little on every run, and is expensive to pack and unpack: dependency, compiler, and toolchain caches. Reach for the Actions cache when you want content-addressed entries keyed by a lockfile hash, restore keys, cross-repository sharing through GitHub's semantics, or a cache that also has to work on GitHub-hosted runners.

Dependency mirrors run underneath both and need no configuration; see Caching.

Not supported

• Jobs that run in a container with jobs.container.
• macOS runners.
• Sharing one cache across regions. A job that lands in another region starts cold there and builds that region's own generations.