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 <bircni@icloud.com>

internal/pkg/config/config.example.yaml

@@ -39,7 +39,7 @@ runner:
   # The maximum interval for fetching the job from the Gitea instance.
   # The runner uses exponential backoff when idle, increasing the interval up to this maximum.
   # Set to 0 or same as fetch_interval to disable backoff.
-  fetch_interval_max: 1m
+  fetch_interval_max: 5s
   # While idle, remove stale bind-workdir task directories and orphaned host-mode
   # scratch directories (left behind when a host cleanup delete stalls) older than
   # this duration. Setting either workdir_cleanup_age or idle_cleanup_interval to 0
@@ -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

internal/pkg/config/config.go

@@ -183,7 +183,7 @@ func LoadDefault(file string) (*Config, error) {
 		cfg.Runner.FetchInterval = 2 * time.Second
 	}
 	if cfg.Runner.FetchIntervalMax <= 0 {
-		cfg.Runner.FetchIntervalMax = time.Minute
+		cfg.Runner.FetchIntervalMax = 5 * time.Second
 	}
 	if cfg.Runner.WorkdirCleanupAge == 0 && !definedRunnerKeys["workdir_cleanup_age"] {
 		cfg.Runner.WorkdirCleanupAge = 24 * time.Hour

internal/pkg/config/config_test.go

@@ -48,12 +48,6 @@ func TestLoadDefault_DefaultsWorkdirCleanupAge(t *testing.T) {
 	assert.Equal(t, 10*time.Minute, cfg.Runner.IdleCleanupInterval)
 }
 
-func TestLoadDefault_DefaultsIdleFetchBackoffMax(t *testing.T) {
-	cfg, err := LoadDefault("")
-	require.NoError(t, err)
-	assert.Equal(t, time.Minute, cfg.Runner.FetchIntervalMax)
-}
-
 func TestLoadDefault_UsesConfiguredWorkdirCleanupAge(t *testing.T) {
 	dir := t.TempDir()
 	path := filepath.Join(dir, "config.yaml")