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/app/run/runner.go

@@ -366,7 +366,6 @@ func (r *Runner) run(ctx context.Context, task *runnerv1.Task, reporter *report.
 	} else if t := task.Secrets["GITHUB_TOKEN"]; t != "" {
 		preset.Token = t
 	}
-	applyPullRequestTargetCheckoutContext(preset)
 
 	if actionsIDTokenRequestURL := taskContext["actions_id_token_request_url"].GetStringValue(); actionsIDTokenRequestURL != "" {
 		envs["ACTIONS_ID_TOKEN_REQUEST_URL"] = actionsIDTokenRequestURL
@@ -575,41 +574,6 @@ func postInternalCache(url, secret string, body map[string]string) error {
 	return nil
 }
 
-func applyPullRequestTargetCheckoutContext(preset *model.GithubContext) {
-	if preset == nil || preset.EventName != "pull_request_target" {
-		return
-	}
-	headSHA := nestedString(preset.Event, "pull_request", "head", "sha")
-	if headSHA == "" {
-		return
-	}
-	preset.Sha = headSHA
-	preset.Ref = headSHA
-	if headRef := nestedString(preset.Event, "pull_request", "head", "ref"); headRef != "" {
-		preset.HeadRef = headRef
-		preset.RefName = headRef
-	}
-}
-
-func nestedString(m map[string]any, keys ...string) string {
-	var current any = m
-	for _, key := range keys {
-		next, ok := current.(map[string]any)
-		if !ok {
-			return ""
-		}
-		current, ok = next[key]
-		if !ok {
-			return ""
-		}
-	}
-	value := current.(string)
-	if value == "" {
-		return ""
-	}
-	return value
-}
-
 func (r *Runner) RunningCount() int64 {
 	return r.runningCount.Load()
 }

internal/app/run/runner_test.go

@@ -7,7 +7,6 @@ import (
 	"context"
 	"testing"
 
-	"gitea.com/gitea/runner/act/model"
 	clientmocks "gitea.com/gitea/runner/internal/pkg/client/mocks"
 	"gitea.com/gitea/runner/internal/pkg/config"
 	"gitea.com/gitea/runner/internal/pkg/ver"
@@ -93,67 +92,6 @@ func TestNewRunnerInitializesLabelsAndEnvironment(t *testing.T) {
 	require.Nil(t, r.cacheHandler)
 }
 
-func TestApplyPullRequestTargetCheckoutContextUsesHeadSHA(t *testing.T) {
-	preset := &model.GithubContext{
-		EventName: "pull_request_target",
-		Sha:       "base-sha",
-		Ref:       "refs/heads/main",
-		RefName:   "main",
-		HeadRef:   "feature",
-		Event: map[string]any{
-			"pull_request": map[string]any{
-				"head": map[string]any{
-					"sha": "head-sha",
-					"ref": "contributor-branch",
-				},
-			},
-		},
-	}
-
-	applyPullRequestTargetCheckoutContext(preset)
-
-	require.Equal(t, "head-sha", preset.Sha)
-	require.Equal(t, "head-sha", preset.Ref)
-	require.Equal(t, "contributor-branch", preset.RefName)
-	require.Equal(t, "contributor-branch", preset.HeadRef)
-}
-
-func TestApplyPullRequestTargetCheckoutContextNoOpsWithoutHeadSHA(t *testing.T) {
-	preset := &model.GithubContext{
-		EventName: "pull_request_target",
-		Sha:       "base-sha",
-		Ref:       "refs/heads/main",
-		RefName:   "main",
-		Event:     map[string]any{},
-	}
-
-	applyPullRequestTargetCheckoutContext(preset)
-
-	require.Equal(t, "base-sha", preset.Sha)
-	require.Equal(t, "refs/heads/main", preset.Ref)
-	require.Equal(t, "main", preset.RefName)
-}
-
-func TestApplyPullRequestTargetCheckoutContextNoOpsForOtherEvents(t *testing.T) {
-	preset := &model.GithubContext{
-		EventName: "pull_request",
-		Sha:       "merge-sha",
-		Ref:       "refs/pull/1/merge",
-		Event: map[string]any{
-			"pull_request": map[string]any{
-				"head": map[string]any{
-					"sha": "head-sha",
-				},
-			},
-		},
-	}
-
-	applyPullRequestTargetCheckoutContext(preset)
-
-	require.Equal(t, "merge-sha", preset.Sha)
-	require.Equal(t, "refs/pull/1/merge", preset.Ref)
-}
-
 func taskWithDefaultActionsURL(url string) *runnerv1.Task {
 	return &runnerv1.Task{
 		Context: &structpb.Struct{

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