ink/act_runner
1
1
Fork 0
mirror of https://gitea.com/gitea/act_runner.git synced 2026-06-22 01:34:25 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs: Improve the documentation for cache (#1034)

Browse Source 
Reviewed-on: https://gitea.com/gitea/runner/pulls/1034
Reviewed-by: Lunny Xiao <xiaolunwen@gmail.com>
Co-authored-by: Nicolas <bircni@icloud.com>
Co-committed-by: Nicolas <bircni@icloud.com>
This commit is contained in:
Nicolas
2026-06-15 21:50:42 +00:00
committed by Lunny Xiao
parent 2963716953
commit 4997f33b5f
2 changed files with 53 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

37
README.md
View File

@@ -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. 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://<cache-server-host>: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 #### Official Docker image

35
internal/pkg/config/config.example.yaml
View File

@@ -85,29 +85,30 @@ runner:
allocate_pty: false allocate_pty: false
cache: cache:
# Enable cache server to use actions/cache. # Enable the built-in cache server (used by actions/cache and similar actions).
enabled: true enabled: true
# The directory to store the cache data. # Directory where cache blobs are stored on disk. Default: $HOME/.cache/actcache
# If it's empty, the cache data will be stored in $HOME/.cache/actcache. # Ignored when external_server is set.
dir: "" dir: ""
# The host of the cache server. # Outbound IP or hostname that job containers use to reach this runner's cache server.
# It's not for the address to listen, but the address to connect from job containers. # Leave empty to detect automatically. 0.0.0.0 is not valid here.
# So 0.0.0.0 is a bad choice, leave it empty to detect automatically. # Ignored when external_server is set.
host: "" host: ""
# The port of the cache server. # Port for the built-in cache server. 0 picks a random free port.
# 0 means to use a random available port. # Ignored when external_server is set.
port: 0 port: 0
# The external cache server URL. Valid only when enable is true. # URL of a shared `gitea-runner cache-server` to use instead of starting a local one.
# If it's specified, runner will use this URL as the ACTIONS_CACHE_URL rather than start a server by itself. # Set on every runner that should share a cache pool. Must end with "/".
# The URL should generally end with "/". # Example: "http://cache-host:8088/"
# Requires external_secret below to be set to the same value on both this runner and the cache-server. # Requires external_secret (below) to match the value on the cache-server.
external_server: "" external_server: ""
# Shared secret between this runner and the external `gitea-runner cache-server`. Required when external_server # Shared secret between this runner and the external cache-server.
# (or `gitea-runner cache-server`) is in use: the runner pre-registers each job's ACTIONS_RUNTIME_TOKEN with the # Required when external_server is set. Must be identical on every runner and the cache-server.
# cache-server, and the cache-server enforces bearer auth + per-repo cache isolation. # Generate with: openssl rand -hex 32
external_secret: "" external_secret: ""
# When true, reuse a cached action instead of fetching from the remote on every job. Note: a moved tag # When true, reuse a cached action instead of fetching from the remote on every job.
# (e.g. a re-tagged "v6") or an updated branch stays at the cached commit until its cache entry is removed. # 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 offline_mode: false
container: container: