Skip to content

Explain persistent caches in the README #5

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
PandelisZ merged 1 commit into from
Oct 17, 2026
Merged

Explain persistent caches in the README #5

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
73 changes: 43 additions & 30 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,13 @@
# Composal Disk Volume

Persist dependency directories across Composal GitHub Actions jobs.
Both `composal-x64-2x` and `composal-x64-4x` use the same
repository-scoped storage.
Keep package downloads between GitHub Actions jobs on Composal runners. Mount
your package manager's cache directory, then run your install command as usual.
Later jobs with the same key reuse the files already there.

See the [Composal runner guide](https://composal.ai/docs/github-actions-runners#dependency-caches)
for runner setup and dependency caching.

## Use it in a workflow

```yaml
jobs:
Expand All @@ -19,30 +24,38 @@ jobs:
- run: npm test
```

`key` identifies a persistent directory within your GitHub App installation and
repository. `path` is an empty absolute, workspace-relative, or `~/` directory.
The action outputs `cache-hit` and the absolute mounted `path`. Prefer stable
keys for package download stores (`~/.npm`, a pnpm store, Cargo registry/git
caches); package managers check the package versions and integrity. Use distinct
keys for incompatible platforms or toolchains.

The directory is backed by persistent storage mounted directly on the runner.
Package managers read and update it in place. The post step flushes writes;
there is no archive, restore copy, snapshot publication, or automatic deletion.
The repository checkout and `.git` stay on local runner disk.

Jobs with the same key share a writable cache across branches and runner sizes,
including pull requests and failed jobs. Use it for rebuildable package download
stores with integrity checks. Choose separate keys for tools that require an
exclusive writable directory. Do not store credentials or use these directories
as build outputs or workspaces. Committed writes are visible to subsequent
runners; an already running job does not automatically refresh its view.

Up to five keys can be mounted per job. `cache-hit` means the directory already
exists, not that every dependency is present. Let the package manager install
missing packages. VM runners use bind mounts; sandboxes link the requested path
to the mounted storage. The first run after the direct-storage update starts
cold; archive snapshots from older runners are not copied or extracted.

Dependency disks are opt-in. Ordinary `actions/cache` and language setup actions
continue using GitHub's cache backend.
Composal mounts persistent storage at `path`. Your package manager reads and
updates it in place. At the end of the job, the action flushes its writes.
Composal keeps the cache for future jobs without compressing it, copying it
back or deleting it after use. Your checkout, `.git` and build outputs belong
on local runner disk.

## Choose a key and path

`key` names a cache within your GitHub App installation and repository. Reuse
it across runs and runner sizes. Give incompatible toolchains different keys.

`path` must be an empty directory. It can be absolute, relative to the workspace,
or start with `~/`. You can mount up to five keys per job.

Use package download stores such as `~/.npm`, a pnpm store or
`~/.cargo/registry/cache`. Keep credentials out of these directories and use
package managers that check downloaded files for integrity. Mount only the
download cache, keeping tool configuration, locks and unpacked sources local.

## Understand what is shared

Jobs with the same key share a writable cache across branches, including pull
requests. Writes from failed jobs persist too. If your tool needs exclusive
access to its cache, give concurrent jobs different keys.

New runners see the latest committed writes. A job that is already running
does not automatically refresh its view when another job writes to the cache.

The action outputs `cache-hit` and the absolute mounted `path`. A cache hit
means the directory exists; it may still be missing packages. Keep your install
step in the workflow so the package manager can fetch what it needs.

The first run after switching from archive-backed runners starts cold. Older
archives are not imported. This action is optional and separate from
`actions/cache` and the caching options in language setup actions.
Loading