Caching

By default, each runner runs a cache server for actions/cache, so caching works without setup. The runner stores entries in cache.dir, which defaults to $HOME/.cache/actcache. It does not share entries with other runners.

Sharing a cache between runners

Run one gitea-runner cache-server and configure each runner to use it. Use the same secret on the cache server and every runner. Generate the secret with openssl rand -hex 32.

On the cache server:

cache:
  dir: /data/actcache
  port: 8088
  external_secret_file: /run/secrets/cache-secret

gitea-runner -c cache-server.yaml cache-server

On each runner:

cache:
  external_server: "http://cache-host:8088/"
  external_secret_file: /run/secrets/cache-secret

Jobs send cache requests to their runner, which forwards them to the shared cache server. Only the runners need to reach the shared cache server. Set external_secret to supply the secret inline instead of from a file.

Runners can also share a cache.dir directory on a filesystem that supports file locks. This makes cache requests slower.

S3-compatible storage

Use an S3-compatible bucket such as AWS S3, MinIO or RustFS to share the cache without a separate cache server:

cache:
  s3:
    endpoint: "http://minio:9000"
    bucket: "runner-cache"
    access_key_file: "/run/secrets/cache-s3-access-key"
    secret_key_file: "/run/secrets/cache-s3-secret-key"

Runners with the same settings share the cache. An entry saved on one runner becomes available to the others within 30 seconds. The eviction settings below do not apply to the bucket. Add lifecycle rules to expire old entries and abort incomplete multipart uploads.

Eviction

Option	Default	Removes
cache.retention	168h	Entries not read or written within this time
cache.repo_size_limit	10GB	Least recently used entries when a repository’s cache exceeds this size
cache.size_limit	off	Least recently used entries when the whole cache exceeds this size

The cache also keeps 1024 MiB free on its volume, or health_check.min_free_disk_space_mb when health checks are enabled. With a shared cache server, set these options on the server.

Artifacts

The runner adapts actions/cache, actions/upload-artifact and actions/download-artifact while a job runs so these actions work with Gitea. With these changes, the cache uses the cache service v2 protocol.

Artifact uploads go through the runner’s cache server, so jobs must be able to reach it. Set cache.v2: false to send artifact uploads directly to Gitea. Set runner.patch_actions: false to run every action exactly as published. This uses the cache service v1 protocol and causes the published artifact actions to fail.

Jobs cannot reach the cache

If actions/cache fails with connect ETIMEDOUT, jobs cannot reach the runner’s cache server.

A runner container connects itself to each job network when it uses the same Docker daemon as its jobs. For jobs on another Docker daemon, for example through a remote DOCKER_HOST, set cache.host and cache.port to an address and port the jobs can reach. Jobs using container.network: bridge cannot reach a runner container outside that network. Leave container.network empty or use a network that includes the runner container.

Action cache

For each job, the runner checks action tags and branches for updates, so it picks up moved tags such as v6. With cache.offline_mode: true, the runner reuses its downloaded copy. This speeds up jobs on slow networks, but moved tags and updated branches stay at the cached commit.