feat(actions/docker): parse runArgs whitelist and splice into HostConfig

Introduces ParseRunArgs in pkg/skaffold/actions/docker/runargs.go that
accepts a docker-run-style flag list using a conservative whitelist
(--network, -v/--volume, -e/--env, --user, --add-host, --tmpfs,
--privileged, --cap-add, --cap-drop). Unknown flags return an error so
users fail fast rather than have settings silently dropped. Only the
'--flag=value' form is supported to keep the parser unambiguous.

Two small helpers project the parsed result onto the existing docker
API types: ApplyToContainerConfig writes User and appends Env onto
container.Config; ApplyToHostConfig overlays NetworkMode, Binds,
ExtraHosts, Tmpfs, Privileged, CapAdd and CapDrop onto a
container.HostConfig.

To make the overlay available at run time, ContainerCreateOpts in
pkg/skaffold/docker/image.go gains an optional HostConfigApply hook
that is invoked after the default HostConfig is constructed. The Task
parses the owning action's runArgs once in createTasks, stores it on
the Task, and wires both helpers through the existing config paths.

No runtime change occurs when runArgs is absent: the overlay methods
are no-ops on a nil receiver.

Author: bogdannazarenko

pkg/skaffold/actions/docker/exec_env.go

@@ -169,13 +169,20 @@ func (e ExecEnv) createTasks(ctx context.Context, out io.Writer, aCfgs latest.Ac
 	timeout := *aCfgs.Config.Timeout
 	useLocalImages := aCfgs.ExecutionModeConfig.LocalExecutionMode.UseLocalImages
 
+	runArgs, err := ParseRunArgs(aCfgs.ExecutionModeConfig.LocalExecutionMode.RunArgs)
+	if err != nil {
+		return nil, nil, fmt.Errorf("action %q: %w", aCfgs.Name, err)
+	}
+
 	for _, cCfg := range containerCfgs {
 		art, err := e.pullArtifact(ctx, out, builts, useLocalImages, cCfg)
 		if err != nil {
 			return nil, nil, err
 		}
 
-		ts = append(ts, NewTask(cCfg, e.client, e.portManager, e.pResources, *art, timeout, &e))
+		task := NewTask(cCfg, e.client, e.portManager, e.pResources, *art, timeout, &e)
+		task.runArgs = runArgs
+		ts = append(ts, task)
 
 		tracked = append(tracked, graph.Artifact{
 			ImageName: cCfg.Image,

pkg/skaffold/actions/docker/runargs.go

@@ -0,0 +1,156 @@
+/*
+Copyright 2026 The Skaffold Authors
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package docker
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/docker/docker/api/types/container"
+)
+
+// RunArgs is the parsed, whitelisted projection of a user-supplied
+// customActions.*.executionMode.local.runArgs list.
+//
+// Only a small, deliberately conservative subset of `docker run` flags is
+// recognised. Unknown flags are rejected so users fail fast instead of
+// silently being ignored. See ParseRunArgs for the full list.
+type RunArgs struct {
+	NetworkMode string
+	Binds       []string
+	Env         []string
+	User        string
+	ExtraHosts  []string
+	Tmpfs       map[string]string
+	Privileged  bool
+	CapAdd      []string
+	CapDrop     []string
+}
+
+// ParseRunArgs parses a docker-run-style argument list and returns a
+// whitelisted RunArgs projection. Supported flags:
+//
+//	--network=VALUE
+//	-v=SRC:DST[:MODE]          (also --volume=...)
+//	-e=KEY=VALUE               (also --env=...)
+//	--user=UID[:GID]
+//	--add-host=HOST:IP
+//	--tmpfs=PATH[:OPTIONS]
+//	--privileged
+//	--cap-add=CAP
+//	--cap-drop=CAP
+//
+// Each flag must be in the `--flag=value` (or `-f=value`) form; the
+// space-separated variant is not supported to keep the parser unambiguous.
+// A nil / empty input returns a nil *RunArgs.
+func ParseRunArgs(args []string) (*RunArgs, error) {
+	if len(args) == 0 {
+		return nil, nil
+	}
+	out := &RunArgs{}
+	for i, raw := range args {
+		arg := strings.TrimSpace(raw)
+		if arg == "" {
+			continue
+		}
+		if arg == "--privileged" {
+			out.Privileged = true
+			continue
+		}
+		key, val, ok := strings.Cut(arg, "=")
+		if !ok {
+			return nil, fmt.Errorf("runArgs[%d] %q: only --flag=value form is supported (no space-separated values)", i, raw)
+		}
+		switch key {
+		case "--network":
+			out.NetworkMode = val
+		case "-v", "--volume":
+			out.Binds = append(out.Binds, val)
+		case "-e", "--env":
+			out.Env = append(out.Env, val)
+		case "--user":
+			out.User = val
+		case "--add-host":
+			out.ExtraHosts = append(out.ExtraHosts, val)
+		case "--tmpfs":
+			if out.Tmpfs == nil {
+				out.Tmpfs = map[string]string{}
+			}
+			mountPath, opts, _ := strings.Cut(val, ":")
+			out.Tmpfs[mountPath] = opts
+		case "--cap-add":
+			out.CapAdd = append(out.CapAdd, val)
+		case "--cap-drop":
+			out.CapDrop = append(out.CapDrop, val)
+		default:
+			return nil, fmt.Errorf("runArgs[%d] %q: unsupported flag %q (allowed: --network, -v/--volume, -e/--env, --user, --add-host, --tmpfs, --privileged, --cap-add, --cap-drop)", i, raw, key)
+		}
+	}
+	return out, nil
+}
+
+// ApplyToContainerConfig overlays parsed runArgs fields that belong on the
+// container.Config (User, additional env vars) onto cfg in place. A nil
+// receiver is a no-op.
+func (r *RunArgs) ApplyToContainerConfig(cfg *container.Config) {
+	if r == nil || cfg == nil {
+		return
+	}
+	if r.User != "" {
+		cfg.User = r.User
+	}
+	if len(r.Env) > 0 {
+		// RunArgs env entries win over anything already on the container
+		// config — consistent with deploy-parameter precedence.
+		cfg.Env = append(cfg.Env, r.Env...)
+	}
+}
+
+// ApplyToHostConfig overlays parsed runArgs fields that belong on the
+// container.HostConfig onto hc in place. NetworkMode is only overridden
+// when the user provided one. A nil receiver is a no-op.
+func (r *RunArgs) ApplyToHostConfig(hc *container.HostConfig) {
+	if r == nil || hc == nil {
+		return
+	}
+	if r.NetworkMode != "" {
+		hc.NetworkMode = container.NetworkMode(r.NetworkMode)
+	}
+	if len(r.Binds) > 0 {
+		hc.Binds = append(hc.Binds, r.Binds...)
+	}
+	if len(r.ExtraHosts) > 0 {
+		hc.ExtraHosts = append(hc.ExtraHosts, r.ExtraHosts...)
+	}
+	if len(r.Tmpfs) > 0 {
+		if hc.Tmpfs == nil {
+			hc.Tmpfs = map[string]string{}
+		}
+		for k, v := range r.Tmpfs {
+			hc.Tmpfs[k] = v
+		}
+	}
+	if r.Privileged {
+		hc.Privileged = true
+	}
+	if len(r.CapAdd) > 0 {
+		hc.CapAdd = append(hc.CapAdd, r.CapAdd...)
+	}
+	if len(r.CapDrop) > 0 {
+		hc.CapDrop = append(hc.CapDrop, r.CapDrop...)
+	}
+}

pkg/skaffold/actions/docker/task.go

@@ -64,6 +64,11 @@ type Task struct {
 
 	// Reference to the associated execution environment.
 	execEnv *ExecEnv
+
+	// Optional whitelisted docker-run-style flags parsed from the owning
+	// action's executionMode.local.runArgs. Nil when the user didn't
+	// provide any.
+	runArgs *RunArgs
 }
 
 var NewTask = newTask
@@ -153,6 +158,7 @@ func (t Task) containerCreateOpts(ctx context.Context, containerName string) (*d
 		ContainerConfig: containerCfg,
 		Bindings:        bindings,
 		Wait:            true,
+		HostConfigApply: t.runArgs.ApplyToHostConfig,
 	}, nil
 }
 
@@ -177,6 +183,8 @@ func (t Task) generateContainerCfg(ctx context.Context) (*container.Config, erro
 
 	containerCfg.Env = append(envVars, t.envVars...)
 
+	t.runArgs.ApplyToContainerConfig(containerCfg)
+
 	return containerCfg, nil
 }
 

pkg/skaffold/docker/image.go

@@ -76,6 +76,10 @@ type ContainerCreateOpts struct {
 	ContainerConfig *container.Config
 	VerifyTestName  string
 	Labels          map[string]string
+	// HostConfigApply, if non-nil, is invoked after the default HostConfig
+	// has been constructed in Run and lets callers overlay additional
+	// fields (e.g. Binds, ExtraHosts, NetworkMode overrides).
+	HostConfigApply func(*container.HostConfig)
 }
 
 // LocalDaemon talks to a local Docker API.
@@ -231,6 +235,9 @@ func (l *localDaemon) Run(ctx context.Context, out io.Writer, opts ContainerCrea
 		PortBindings: opts.Bindings,
 		Mounts:       opts.Mounts,
 	}
+	if opts.HostConfigApply != nil {
+		opts.HostConfigApply(hCfg)
+	}
 
 	c, err := l.apiClient.ContainerCreate(ctx, opts.ContainerConfig, hCfg, nil, nil, opts.Name)
 	if err != nil {