docs: document runArgs for custom actions and verify

Documents the conservative runArgs whitelist (--network, -v/--volume,
--add-host, --tmpfs) and its security note on the custom-actions page, adds a
short cross-linked note on the verify page (verify shares the same whitelist),
and ships a runnable custom-actions-runargs example.

Author: bogdannazarenko

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

@@ -109,6 +109,45 @@ 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 the host network for GCE/GKE metadata),
+use [`customActions[].executionMode.local.runArgs`]({{< relref
+"/docs/references/yaml/#customActions-executionMode-local-runArgs" >}}).
+Skaffold parses each entry against a conservative whitelist and overlays
+the result on the Docker `HostConfig` 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`. |
+| `--add-host=<host>:<ip>` | Appends to `HostConfig.ExtraHosts`. |
+| `--tmpfs=<path>[:opts]` | Merges into `HostConfig.Tmpfs`. |
+
+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"
+    containers:
+      - name: gcloud
+        image: google/cloud-sdk:slim
+        command: ["gcloud"]
+        args: ["auth", "list"]
+```
+
+> **Security note:** `runArgs` hands raw flags to the host Docker daemon.
+> Avoid committing broad bind mounts (`-v=/:/host`) or host-network access
+> to source control unless the action genuinely needs them.
+
 #### 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:

docs-v2/content/en/docs/verify.md

@@ -21,6 +21,8 @@ You can run post-deployment verification tests in the following execution enviro
 
 When Skaffold runs a post-deployment verifications test in the local execution mode, it uses the `docker` CLI to run the test container on the host machine. This is the default execution mode.
 
+Local verify containers accept the same conservative `runArgs` whitelist as custom actions via [`verify[].executionMode.local.runArgs`]({{< relref "/docs/references/yaml/#verify-executionMode-local-runArgs" >}}) (`--network`, `-v`/`--volume`, `--add-host`, `--tmpfs`). See [Passing Docker run flags with `runArgs`]({{< relref "/docs/custom-actions#passing-docker-run-flags-with-runargs" >}}) for details and the security note.
+
 ### Kubernetes cluster
 
 When Skaffold runs a post-deployment verification test in the Kubernetes cluster execution mode, it uses the `kubectl` CLI to run the test container as a Kubernetes Job.

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

@@ -0,0 +1,29 @@
+apiVersion: skaffold/v4beta15
+kind: Config
+metadata:
+  name: custom-actions-runargs
+
+customActions:
+  - name: extra-host
+    executionMode:
+      local:
+        runArgs:
+          - "--add-host=metadata-server:169.254.169.254"
+          - "--tmpfs=/scratch:size=16m"
+    containers:
+      - name: probe
+        image: alpine:3.20
+        command: ["/bin/sh"]
+        args: ["-c", "grep metadata-server /etc/hosts && touch /scratch/ok && echo scratch-writable"]
+
+  - 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"]