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.

Branches

Branch	Purpose
restore	Restores cache archive if it exists
save	Saves cache archive (use after build)

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 (restore only)

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. restore branch extracts the archive, save branch creates one

Usage

This action must be used twice in your workflow:

1. Before build — use @restore to restore cache if it exists
2. After build — use @save to save the cache archive

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@restore
        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@save
        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@restore
        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@save
        with:
          key-prefix: 'rust'
          key-file: 'Cargo.lock'
          path: '~/.cargo/registry'