saru
8cdec4603c
Restore only used the path input for a redundant mkdir and then extracted to / using the absolute path baked into the archive, which pointed at the stale per-run workspace of whichever run saved it. Extract relative archives (<basename>/...) into the parent of the requested path; keep a legacy fallback (extract to /) for old archives, which report cache-hit only when the requested path actually gains content.
129 lines
3.4 KiB
Markdown
129 lines
3.4 KiB
Markdown
Cache Action
|
|
============
|
|
|
|
A Gitea Action that caches build files as `tar.xz` archives on the runner filesystem. Simple, fast, no external dependencies.
|
|
|
|
## Inputs
|
|
|
|
| Input | Description | Required | Default |
|
|
|-------|-------------|----------|---------|
|
|
| `path` | Single directory to cache | No | `~/.cache/` |
|
|
| `key-prefix` | Prefix for the cache key | Yes | — |
|
|
| `key-file` | File to hash (SHA-256) for the cache key | Yes | — |
|
|
|
|
## Outputs
|
|
|
|
| Output | Description |
|
|
|--------|-------------|
|
|
| `cache-hit` | `true` if exact key match found, `false` otherwise |
|
|
|
|
## How It Works
|
|
|
|
1. Hashes `key-file` with SHA-256, combines with `key-prefix` as `<prefix>-<hash>`
|
|
2. Stores archives at `~/.cache/.cache-store/<key>.tar.xz`
|
|
3. Restores by extracting the archive to `/`, saves by creating one
|
|
4. Touches the archive on every hit, so the retention policy can expire by
|
|
last use
|
|
5. Archives store the cached directory **relative** (`<basename>/...`), not its
|
|
absolute path — a later run restores into its own `path` location, so the
|
|
cache works across runs even though each run gets a fresh workspace
|
|
|
|
## Cache Retention
|
|
|
|
Archives are content-addressed, so old keys are never needed again — the store
|
|
is pruned automatically on every restore/save (best-effort, safe under
|
|
concurrent runners):
|
|
|
|
- The newest `CACHE_KEEP_N` (default `3`) archives per key-prefix family are
|
|
always kept, so reverting e.g. `Cargo.lock` still hits an older key
|
|
- Anything older than `CACHE_TTL_DAYS` (default `7`) outside the keep set is
|
|
deleted
|
|
- A hard size cap `CACHE_CAP_GB` (default `2`) deletes oldest-first when
|
|
exceeded
|
|
- Files younger than 1 hour are never touched (in-flight save protection)
|
|
- Stale run workspaces under `~/.cache/act/*/hostexecutor` older than
|
|
`CACHE_WORKSPACE_TTL_DAYS` (default `2`) are removed
|
|
|
|
Override the defaults per-job via `env:` (e.g. `env: { CACHE_KEEP_N: 5 }`).
|
|
|
|
## Usage
|
|
|
|
This action must be used **twice** in your workflow:
|
|
|
|
1. **Before build** — restores cache if it exists
|
|
2. **After build** — saves the cache archive (only on cache miss)
|
|
|
|
## Rust Example
|
|
|
|
```yaml
|
|
name: Rust Build
|
|
on: push
|
|
|
|
defaults:
|
|
run:
|
|
shell: bash
|
|
|
|
jobs:
|
|
build:
|
|
runs-on: ubuntu-latest
|
|
steps:
|
|
- uses: actions/checkout@v4
|
|
|
|
# 1. Restore cache before build
|
|
- uses: Actions/Cache@main
|
|
id: cache
|
|
with:
|
|
key-prefix: 'cargo-registry'
|
|
key-file: 'Cargo.lock'
|
|
path: '~/.cargo/registry'
|
|
|
|
- name: Build
|
|
run: cargo build --release
|
|
|
|
# 2. Save cache after build
|
|
- uses: Actions/Cache@main
|
|
with:
|
|
key-prefix: 'cargo-registry'
|
|
key-file: 'Cargo.lock'
|
|
path: '~/.cargo/registry'
|
|
```
|
|
|
|
## Skip Steps on Cache Hit
|
|
|
|
```yaml
|
|
name: Build with Conditional Steps
|
|
on: push
|
|
|
|
defaults:
|
|
run:
|
|
shell: bash
|
|
|
|
jobs:
|
|
build:
|
|
runs-on: ubuntu-latest
|
|
steps:
|
|
- uses: actions/checkout@v4
|
|
|
|
# 1. Restore cache
|
|
- uses: Actions/Cache@main
|
|
id: cache
|
|
with:
|
|
key-prefix: 'rust'
|
|
key-file: 'Cargo.lock'
|
|
path: '~/.cargo/registry'
|
|
|
|
- name: Fetch dependencies
|
|
if: steps.cache.outputs.cache-hit != 'true'
|
|
run: cargo fetch
|
|
|
|
- name: Build
|
|
run: cargo build --release
|
|
|
|
# 2. Save cache
|
|
- uses: Actions/Cache@main
|
|
with:
|
|
key-prefix: 'rust'
|
|
key-file: 'Cargo.lock'
|
|
path: '~/.cargo/registry'
|
|
```
|