docs(custom-actions): document runArgs whitelist + integration test

Adds a new 'Passing Docker run flags with runArgs' subsection under
the local execution-mode docs covering the whitelist, the accepted
--flag=value form, and a security warning about bind mounts and
privileged mode. Includes a worked example that mounts the host's
ADC credentials into a google/cloud-sdk container.

Introduces an integration example at
integration/examples/custom-actions-runargs/ demonstrating a
hardened action (non-root user, dropped cap) and a gcloud
credential-passthrough action.

Extends TestExec_LocalActions with an 'action with runArgs overlay'
case that asserts --user=1000:1000 pins uid=1000 inside the
container and -e=SENTINEL=from-runargs reaches the process env.

Author: bogdannazarenko

docs-v2/content/en/docs/custom-actions.md

@@ -109,6 +109,53 @@ A Custom Action has an execution mode associated with it that indicates Skaffold
 
 This is the default configuration when no [`customActions[].executionMode`]({{< relref "/docs/references/yaml/#customActions-executionMode" >}}) is specified. With this execution mode, Skaffold will run every container associated to a given Custom Action with a Docker daemon.
 
+##### Passing Docker run flags with `runArgs`
+
+When an action needs to reach host resources (for example your local
+`~/.config/gcloud` credentials) or to tighten its runtime (dropping
+capabilities, pinning a non-root user), use
+[`customActions[].executionMode.local.runArgs`]({{< relref
+"/docs/references/yaml/#customActions-executionMode-local-runArgs" >}}).
+Skaffold parses each entry with a whitelist and overlays the result on
+the Docker `HostConfig`/`Config` used to start the container:
+
+| Flag | Effect |
+| --- | --- |
+| `--network=<mode>` | Sets `HostConfig.NetworkMode`. Accepts `host`, `bridge`, `none`, or a named network. |
+| `-v=<src>:<dst>[:opts]`, `--volume=<src>:<dst>[:opts]` | Appends to `HostConfig.Binds`. |
+| `-e=<KEY>=<VALUE>`, `--env=<KEY>=<VALUE>` | Appends to `Config.Env`. |
+| `--user=<uid[:gid]>` | Sets `Config.User`. |
+| `--add-host=<host>:<ip>` | Appends to `HostConfig.ExtraHosts`. |
+| `--tmpfs=<path>[:opts]` | Merges into `HostConfig.Tmpfs`. |
+| `--privileged` | Sets `HostConfig.Privileged=true`. |
+| `--cap-add=<CAP>`, `--cap-drop=<CAP>` | Appends to `HostConfig.CapAdd`/`CapDrop`. |
+
+Only the `--flag=value` form is accepted — space-separated values and
+unknown flags are rejected at load time so typos fail loudly rather
+than silently dropping settings.
+
+```yaml
+customActions:
+  - name: reuse-local-adc
+    executionMode:
+      local:
+        runArgs:
+          - "-v=/root/.config/gcloud:/root/.config/gcloud:ro"
+          - "--network=host"
+          - "-e=CLOUDSDK_CORE_PROJECT=my-project"
+    containers:
+      - name: gcloud
+        image: google/cloud-sdk:slim
+        command: ["gcloud"]
+        args: ["auth", "list"]
+```
+
+> **Security note:** `runArgs` bypasses Skaffold's sandbox and hands
+> raw flags to the host Docker daemon. Avoid committing `--privileged`,
+> broad bind mounts (`-v=/:/host`) or secret values to source control.
+> Prefer deploy parameters or environment files for per-invocation
+> overrides.
+
 #### Remote (K8s job)
 
 With this execution mode, Skaffold will create a K8s job for each container associated with the given action. For the following configuration:

integration/examples/custom-actions-runargs/skaffold.yaml

@@ -0,0 +1,30 @@
+apiVersion: skaffold/v4beta15
+kind: Config
+metadata:
+  name: custom-actions-runargs
+
+customActions:
+  - name: hardened-action
+    executionMode:
+      local:
+        runArgs:
+          - "--user=1000:1000"
+          - "--cap-drop=NET_RAW"
+          - "-e=SENTINEL=hardened"
+    containers:
+      - name: hardened
+        image: alpine:3.20
+        command: ["/bin/sh"]
+        args: ["-c", "echo uid=$(id -u) && echo sentinel=$SENTINEL"]
+
+  - name: gcloud-auth-list
+    executionMode:
+      local:
+        runArgs:
+          - "-v=/root/.config/gcloud:/root/.config/gcloud:ro"
+          - "--network=host"
+    containers:
+      - name: gcloud
+        image: google/cloud-sdk:slim
+        command: ["gcloud"]
+        args: ["auth", "list"]

integration/exec_test.go

@@ -67,6 +67,14 @@ func TestExec_LocalActions(t *testing.T) {
 				"[task7] bye-from-env-file",
 			},
 		},
+		{
+			description: "action with runArgs overlay",
+			action:      "action-runargs",
+			expectedMsgs: []string{
+				"[runargs-task] uid=1000",
+				"[runargs-task] sentinel=from-runargs",
+			},
+		},
 	}
 
 	for _, test := range tests {

integration/testdata/custom-actions-local/skaffold.yaml

@@ -76,4 +76,16 @@ customActions:
         image: localtaks
         env:
           - name: FOO
-            value: from-local-img
+            value: from-local-img
+
+  - name: action-runargs
+    executionMode:
+      local:
+        runArgs:
+          - "--user=1000:1000"
+          - "-e=SENTINEL=from-runargs"
+    containers:
+      - name: runargs-task
+        image: alpine:3.15.4
+        command: ["/bin/sh"]
+        args: ["-c", "echo uid=$(id -u) && echo sentinel=$SENTINEL"]