saru
43f1755c0e
Record last use by touching the archive so the retention policy can expire by access time, and run prune.sh after every restore (even on miss) to keep the shared store trimmed: keep the 3 newest archives per key-prefix family, expire anything older than 7 days, hard-cap the store at 2 GB (oldest first, trumping the keep set), never touch files younger than 1h, and drop stale run workspaces under ~/.cache/act older than 2 days.
126 lines
3.2 KiB
Markdown
126 lines
3.2 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
|
|
|
|
## 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'
|
|
```
|