Cache/README.md

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. Saves atomically (write to <key>.tar.xz.tmp, then rename)
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

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

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'