Cache Action
============

A Gitea Action that caches build files under `~/.cache/` using a key file hash. Implements the Gitea artifact cache API directly with curl, tar, and zstd — no external actions required.

## Inputs

| Input | Description | Required | Default |
|-------|-------------|----------|---------|
| `path` | Files/directories to cache | No | `~/.cache/` |
| `key-prefix` | Prefix for the cache key | Yes | — |
| `key-file` | File to hash for the cache key | Yes | — |
| `restore-keys` | Fallback prefix-matched keys | No | — |

## Outputs

| Output | Description |
|--------|-------------|
| `cache-hit` | `true` if exact key match found, `false` otherwise |
| `cache-primary-key` | The primary key used for cache lookup |
| `cache-matched-key` | The key of the cache entry that was restored |

## Quick Start

### Rust Example

```yaml
name: Rust Build
on: push

defaults:
  run:
    shell: bash

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: Actions/Cache@main
        with:
          key-prefix: 'rust'
          key-file: 'Cargo.lock'
          path: |
            ~/.cache/
            ~/.cargo/registry
            ~/.cargo/git
            target
      - name: Build
        run: |
          cargo build --release
```

### Skip Steps on Cache Hit

```yaml
name: Build with Conditional Steps
on: push

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: Actions/Cache@main
        id: cache
        with:
          key-prefix: 'rust'
          key-file: 'Cargo.lock'
      - name: Install dependencies
        if: steps.cache.outputs.cache-hit != 'true'
        run: cargo fetch
      - name: Build
        run: cargo build --release
```

## How It Works

1. **Cache Key Generation**: Combines `key-prefix` with the SHA-256 hash of `key-file` (e.g. `rust-<hash>`).

2. **Cache Restore**: Calls the Gitea artifact cache API (`/_apis/artifactcache/cache`) to find a matching entry, downloads the archive, and extracts it.

3. **Cache Save**: Runs on job completion (`if: always()`), creates a zstd-compressed tar archive, reserves a cache entry via the API, uploads it, and commits it. Skipped if there was a cache hit on the primary key.

## Cache Scope

The cache is scoped to the key, version, and branch. The default branch cache is available to other branches.

## Remarks

- The cache server must be enabled on your Gitea instance
- Requires `curl`, `tar`, and `sha256sum` on the runner (zstd is optional, falls back to gzip)
- Maximum cache size per repository is 10GB