From 4997f33b5f41a1e067fd61ccc5ad723f5158e8d6 Mon Sep 17 00:00:00 2001 From: Nicolas Date: Mon, 15 Jun 2026 21:50:42 +0000 Subject: [PATCH] docs: Improve the documentation for cache (#1034) Reviewed-on: https://gitea.com/gitea/runner/pulls/1034 Reviewed-by: Lunny Xiao Co-authored-by: Nicolas Co-committed-by: Nicolas --- README.md | 37 +++++++++++++++++++++++-- internal/pkg/config/config.example.yaml | 35 +++++++++++------------ 2 files changed, 53 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 9617fa77..cb5b594b 100644 --- a/README.md +++ b/README.md @@ -160,9 +160,42 @@ Prefer a YAML file for all settings. If `runner.labels` is set in the YAML file, those labels are used during `register` and the `--labels` CLI flag is ignored. -#### External cache (`actions/cache`) +#### Caching (`actions/cache`) -If `cache.external_server` is set, you must set `cache.external_secret` to the same value on this runner and on the standalone cache server. Run the server with `gitea-runner cache-server` using a config that defines `cache.external_secret` (and matching `cache.dir` / host / port as needed). Flags `--dir`, `--host`, and `--port` on `cache-server` override the file. +Each runner starts its own cache server automatically. Cache entries are local to that runner — runners do not share a cache by default. + +**Shared cache across multiple runners** + +Run one dedicated `gitea-runner cache-server` that all runners point at. + +1. Create a config file for the cache server host: + + ```yaml + cache: + dir: /data/actcache + port: 8088 + external_secret: "replace-with-a-strong-random-secret" + ``` + +2. Start the server: + + ```bash + gitea-runner -c cache-server-config.yaml cache-server + ``` + +3. On every runner: + + ```yaml + cache: + external_server: "http://:8088/" + external_secret: "replace-with-a-strong-random-secret" # must match the server + ``` + +Alternatively, mount the same NFS/CIFS share on every runner and point `cache.dir` at it — simpler, but with weaker isolation between repositories. + +**S3 / MinIO** — mount object storage as a FUSE filesystem (e.g. [s3fs](https://github.com/s3fs-fuse/s3fs-fuse) or [goofys](https://github.com/kahing/goofys)) and set `cache.dir` to the mount point. + +Flags `--dir`, `--host`, and `--port` on `cache-server` override the corresponding `cache.*` YAML keys; all other settings, including `external_secret`, require the config file. #### Official Docker image diff --git a/internal/pkg/config/config.example.yaml b/internal/pkg/config/config.example.yaml index 9b12b913..fe31138d 100644 --- a/internal/pkg/config/config.example.yaml +++ b/internal/pkg/config/config.example.yaml @@ -85,29 +85,30 @@ runner: allocate_pty: false cache: - # Enable cache server to use actions/cache. + # Enable the built-in cache server (used by actions/cache and similar actions). enabled: true - # The directory to store the cache data. - # If it's empty, the cache data will be stored in $HOME/.cache/actcache. + # Directory where cache blobs are stored on disk. Default: $HOME/.cache/actcache + # Ignored when external_server is set. dir: "" - # The host of the cache server. - # It's not for the address to listen, but the address to connect from job containers. - # So 0.0.0.0 is a bad choice, leave it empty to detect automatically. + # Outbound IP or hostname that job containers use to reach this runner's cache server. + # Leave empty to detect automatically. 0.0.0.0 is not valid here. + # Ignored when external_server is set. host: "" - # The port of the cache server. - # 0 means to use a random available port. + # Port for the built-in cache server. 0 picks a random free port. + # Ignored when external_server is set. port: 0 - # The external cache server URL. Valid only when enable is true. - # If it's specified, runner will use this URL as the ACTIONS_CACHE_URL rather than start a server by itself. - # The URL should generally end with "/". - # Requires external_secret below to be set to the same value on both this runner and the cache-server. + # URL of a shared `gitea-runner cache-server` to use instead of starting a local one. + # Set on every runner that should share a cache pool. Must end with "/". + # Example: "http://cache-host:8088/" + # Requires external_secret (below) to match the value on the cache-server. external_server: "" - # Shared secret between this runner and the external `gitea-runner cache-server`. Required when external_server - # (or `gitea-runner cache-server`) is in use: the runner pre-registers each job's ACTIONS_RUNTIME_TOKEN with the - # cache-server, and the cache-server enforces bearer auth + per-repo cache isolation. + # Shared secret between this runner and the external cache-server. + # Required when external_server is set. Must be identical on every runner and the cache-server. + # Generate with: openssl rand -hex 32 external_secret: "" - # When true, reuse a cached action instead of fetching from the remote on every job. Note: a moved tag - # (e.g. a re-tagged "v6") or an updated branch stays at the cached commit until its cache entry is removed. + # When true, reuse a cached action instead of fetching from the remote on every job. + # A moved tag (e.g. a re-tagged "v6") or an updated branch stays at the cached commit + # until its cache entry expires or is manually removed. offline_mode: false container: