From a283204e0a74d142a0f7555b6c53c746bca9924f Mon Sep 17 00:00:00 2001
From: Stephen Gibler <261876204+sgibler-droid@users.noreply.github.com>
Date: Tue, 26 May 2026 20:29:14 -0700
Subject: [PATCH] docs: clarify Docker action pre-if metadata

---
 .../workflows-and-actions/metadata-syntax.md    | 17 ++++++++++++++++-
 1 file changed, 16 insertions(+), 1 deletion(-)

diff --git a/content/actions/reference/workflows-and-actions/metadata-syntax.md b/content/actions/reference/workflows-and-actions/metadata-syntax.md
index 9c5aa7b478b8..13ef65016862 100644
--- a/content/actions/reference/workflows-and-actions/metadata-syntax.md
+++ b/content/actions/reference/workflows-and-actions/metadata-syntax.md
@@ -393,7 +393,7 @@ runs:
 
 ### `runs.pre-entrypoint`
 
-**Optional** Allows you to run a script before the `entrypoint` action begins. For example, you can use `pre-entrypoint:` to run a prerequisite setup script. {% data variables.product.prodname_actions %} uses `docker run` to launch this action, and runs the script inside a new container that uses the same base image. This means that the runtime state is different from the main `entrypoint` container, and any states you require must be accessed in either the workspace, `HOME`, or as a `STATE_` variable. The `pre-entrypoint:` action always runs by default but you can override this using [`runs.pre-if`](#runspre-if).
+**Optional** Allows you to run a script before the `entrypoint` action begins. For example, you can use `pre-entrypoint:` to run a prerequisite setup script. {% data variables.product.prodname_actions %} uses `docker run` to launch this action, and runs the script inside a new container that uses the same base image. This means that the runtime state is different from the main `entrypoint` container, and any states you require must be accessed in either the workspace, `HOME`, or as a `STATE_` variable. The `pre-entrypoint:` action always runs by default but you can override this using [`runs.pre-if`](#runspre-if-for-docker-container-actions).
 
 The runtime specified with the [`using`](#runsusing-for-docker-container-actions) syntax will execute this file.
 
@@ -409,6 +409,21 @@ runs:
   entrypoint: 'main.sh'
 ```
 
+### `runs.pre-if` for Docker container actions
+
+**Optional** Allows you to define conditions for the `pre-entrypoint:` action execution. The `pre-entrypoint:` action will only run if the conditions in `pre-if` are met. If not set, then `pre-if` defaults to `always()`.
+
+In this example, the `pre-entrypoint:` action runs only on Linux-based runners:
+
+```yaml
+runs:
+  using: 'docker'
+  image: 'Dockerfile'
+  pre-entrypoint: 'setup.sh'
+  pre-if: runner.os == 'linux'
+  entrypoint: 'main.sh'
+```
+
 ### `runs.image`
 
 **Required** The Docker image to use as the container to run the action. The value can be the Docker base image name, a local `Dockerfile` in your repository, or a public image in Docker Hub or another registry. To reference a `Dockerfile` local to your repository, the file must be named `Dockerfile` and you must use a path relative to your action metadata file. The `docker` application will execute this file.