Cache/README.md

Cache Action

A Gitea Action that caches build files under ~/.cache/ using a key file hash. This action uses actions/cache@v5 under the hood and automatically saves the cache when the job completes successfully.

Inputs

Input	Description	Required	Default
path	Files/directories to cache	No	~/.cache/
key	Explicit cache key	No	Auto-generated from hash
key-file	File to hash for cache key generation	No	Auto-detects lockfiles
restore-keys	Fallback prefix-matched keys	No	{os}-cache-

Outputs

Output	Description
cache-hit	true if exact key match found, false otherwise

Quick Start

Basic Usage

name: Build with Cache
on: push

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: Actions/Cache@main
      - run: echo "Cache restored, proceeding with build..."

With Custom Key File

name: Build with Cache
on: push

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: Actions/Cache@main
        with:
          key-file: 'package-lock.json'
      - run: npm ci
      - run: npm run build

.NET Example

name: .NET Build
on: push

defaults:
  run:
    shell: bash

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: Actions/Cache@main
        with:
          key-file: '**/*.csproj'
          path: |
            ~/.cache/
            ~/.nuget/packages
      - name: Build
        working-directory: src/
        run: |
          dotnet restore
          dotnet build --no-restore -c Release
          dotnet publish --no-build -c Release

Skip Steps on Cache Hit

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-file: 'requirements.txt'
      - name: Install dependencies
        if: steps.cache.outputs.cache-hit != 'true'
        run: pip install -r requirements.txt

How It Works

1. Cache Key Generation: If no explicit key is provided, the action auto-generates one by:

   • Hashing the specified key-file if provided
   • Otherwise, hashing all detected lockfiles (package-lock.json, Cargo.lock, go.mod, etc.)
   • Falls back to hashing all non-git files if no lockfiles found

2. Cache Restore: Uses actions/cache@v5 to restore the cache from ~/.cache/

3. Cache Save: Automatically saves the cache when the job completes successfully (handled by actions/cache@v5)

Cache Scope

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

Remarks

• Requires Gitea Actions runner version >= 2.327.1 for actions/cache@v5
• The cache server must be enabled on your Gitea instance
• Maximum cache size per repository is 10GB