From f2e0cf9131e2b956229a923c48d24f41835254b1 Mon Sep 17 00:00:00 2001 From: bircni Date: Sat, 4 Jul 2026 00:06:26 +0000 Subject: [PATCH] docs: clarify cache reachability for dockerized runners (#1069) Refs https://gitea.com/gitea/runner/issues/155 The remaining failure mode described in the issue comments is the job container timing out when it tries to reach ACTIONS_CACHE_URL. The generated config now explains that cache.host/cache.port must be reachable from job containers, and calls out dockerized runners with auto-created per-job networks as a case that may need a fixed published cache endpoint or a shared Docker network Co-authored-by: bircni --- internal/pkg/config/config.example.yaml | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/internal/pkg/config/config.example.yaml b/internal/pkg/config/config.example.yaml index 2176dff7..72d6b9c7 100644 --- a/internal/pkg/config/config.example.yaml +++ b/internal/pkg/config/config.example.yaml @@ -110,6 +110,11 @@ cache: dir: "" # 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. + # If the runner itself runs in Docker, automatic detection can choose an + # address on the runner container's network that job containers cannot reach + # when the runner creates a separate per-job network. In that case, set this + # to a hostname/IP reachable from job containers, and set port to a fixed + # published port or put the job containers on a shared Docker network. # Ignored when external_server is set. host: "" # Port for the built-in cache server. 0 picks a random free port. @@ -133,6 +138,8 @@ container: # Specifies the network to which the container will connect. # Could be host, bridge or the name of a custom network. # If it's empty, runner will create a network automatically. + # For dockerized runners using the built-in cache server, a custom shared + # network can be required so job containers can reach cache.host/cache.port. # Deprecated: `network_mode` is still accepted for old configs; use `network` instead. network: "" # network_create_options only apply when `network` is left empty and the runner