Mount a durable cache disk

Mount a durable disk into your Depot CI jobs to persist data between runs and share a directory across multiple workflows. You mount it with the depot/cache-mount action under a name that's global to your organization, and any workflow that mounts the same name reuses the same disk.

How it works

A cache disk is a durable filesystem you mount into a Depot CI job with the depot/cache-mount action. Unlike a job's ephemeral sandbox, the disk's contents persist after the job finishes, so the next run starts with whatever the previous run left behind.

Each disk is identified by a name that is global to your Depot organization and is unique within it. The disk is created automatically the first time a workflow uses a name, and any workflow in the org that mounts the same name gets the same disk. Reusing a name across runs is what makes a disk shareable across repositories and workflows.

Multiple parallel workflows can mount, read from, and write to the same disk at once. The action mounts the disk in conditional mode, so writes don't require an explicit checkout step. Avoid having jobs modify the same files at the same time; use one writer with many readers or partition writes into separate directories.

Public fork pull requests skip mounting the disk and only create the target directory, so untrusted forks can't read or write your organization's cached data.

When to use a cache disk

A cache disk is a good fit when the work fits a shared directory:

• Package and build caches: Persist dependency and build caches between runs without the upload, download, and restore-key steps that actions/cache requires. The cache is just present on a real filesystem.
• Content-addressed tool caches: Point the mount at the tool's cache via env or flag: GOCACHE/GOMODCACHE, CARGO_HOME registry, ~/.m2, ~/.gradle, ccache/sccache, Bazel/buildkit local cache.
• Sharing data between workflows: Write results to the disk in one workflow and consume them from another, or use files on the disk to communicate between jobs.
• Read-only reference data: Model weights, test fixtures, seed databases, toolchains/SDKs. Populate once, then read concurrently everywhere.
• Directory-partitioned writes: Matrix or monorepo jobs that each write only their own slice (/tmp/cache-mount/<arch>, /tmp/cache-mount/<pkg>) avoid contention.
• Per-job downloads from S3: Anything you would otherwise download from S3 for each job.

Mount a cache disk in a job

Add the depot/cache-mount action to your job before the steps that read or write the cached directory. Give the disk a name and the path to mount it at:

jobs:
  build:
    runs-on: depot-ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: Mount cache disk
        uses: depot/cache-mount@v1
        with:
          name: my-org-build-cache
          path: /mnt/cache

      - name: Build
        run: ./build.sh --cache-dir /mnt/cache

The action takes the following inputs:

Best practices

• Naming: Because names are global and unique to the org, use a convention that prevents collisions and makes intentional sharing obvious, for example prefixing by repository or purpose.
• Sharing: Reads are unlimited and concurrent, so a disk is well-suited to many-reader fan-out. Mount a shared name only where you mean to share.
• Concurrent writes: Avoid having multiple jobs modify the same files at once. Prefer one writer with many readers, or give each writer a separate directory.
• Safety: Don't store secrets or untrusted output. Any build in the organization that knows the disk name can read its contents.

Concurrent access

Cache disks support concurrent reads and writes from multiple workflows. Concurrent access doesn't make overlapping application writes atomic. For predictable results, use a single writer with multiple readers, partition writes so each job owns a separate subdirectory, or use content-addressed caches whose entries are immutable.

Manage and delete cache disks

Cache disks created by the depot/cache-mount action appear on the workflow settings page, where you can see each disk's name, when it was created, when it was last used, and its size. Organization owners can delete a disk from that page. Disks are also removed automatically once they fall outside the retention policy.

Retention

Cache disks are automatically deleted based on your organization's Depot cache retention policy, configured on the organization settings page. The default retention is 14 days.