From 44ce6c4c1b05c5ff5b964fc97d3f10e7c77f6e10 Mon Sep 17 00:00:00 2001 From: Pandelis Zembashis Date: Fri, 16 Oct 2026 17:02:45 -0700 Subject: [PATCH] Explain cache sharing and link the Composal runner guide --- README.md | 73 ++++++++++++++++++++++++++++++++----------------------- 1 file changed, 43 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index 752cd72..6404b0a 100644 --- a/README.md +++ b/README.md @@ -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: @@ -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.