saru
a7eff41c26
- Remove actions/cache@v5 dependency, implement cache API calls directly using curl, tar, and zstd against Gitea's /_apis/artifactcache/ API - Drop 'key' input, add required 'key-prefix' and 'key-file' inputs - Cache key is generated as key-prefix-<sha256-of-key-file> - Update README with revised inputs and Rust-only examples
94 lines
2.5 KiB
Markdown
94 lines
2.5 KiB
Markdown
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
|