From 5f6825f35262b89235f6b244de504e6b136a1d22 Mon Sep 17 00:00:00 2001
From: Jahvon Dockery <jahvondockery@gmail.com>
Date: Thu, 27 Aug 2026 00:38:50 -0400
Subject: [PATCH] feat: add flow-binary input for testing unreleased builds

Lets a caller run its executables with a flow binary it just built, instead of
one installed from a release or from main.

Without this, a repository whose CI runs flow tasks is always testing a flow
that predates the code under review. That is a silent gap in general, and a hard
block when a task depends on a flow feature that has not shipped: flow's own CI
cannot exercise a new capability from a .execs target, because the action clones
and builds main and discards the branch entirely.

flow-binary takes precedence over flow-version, and skips the download cache
since there is nothing to restore. A missing path fails loudly rather than
falling back to a download, so a typo cannot silently reintroduce the gap it
exists to close.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01R328pa3FUUfga4gYah1iQi
---
 README.md               | 21 +++++++++++++++++++++
 action.yaml             | 11 +++++++++++
 scripts/install-flow.sh | 20 +++++++++++++++++++-
 3 files changed, 51 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 52328d2..9574425 100644
--- a/README.md
+++ b/README.md
@@ -35,6 +35,7 @@ Check out the [flow CI workflow](https://github.com/flowexec/flow/blob/main/.git
 | `clone-token` | GitHub token for cloning private repositories | |
 | `clone-depth` | Git clone depth for repository cloning (0 for full history) | `1` |
 | `flow-version` | Version of flow CLI to install | `latest` |
+| `flow-binary` | Path to a pre-built flow binary to use instead of installing one (relative to the workspace root). Takes precedence over `flow-version`. | |
 | `params` | Parameters to pass to the executable (`KEY=VALUE` pairs, one per line or comma-separated) | |
 | `env` | Environment variables to set during execution (`KEY=VALUE` pairs, one per line) | |
 | `secrets` | Secrets to set in flow vault (`KEY=VALUE` pairs, one per line; JSON also accepted) | |
@@ -223,6 +224,26 @@ Use `continue-on-error` with the `error-code` output to handle failures programm
       KUBECONFIG=${{ secrets.KUBECONFIG }}
 ```
 
+### Testing an Unreleased flow Build
+
+Set `flow-binary` to run your executables with a flow binary you just built, instead of an
+installed release. This matters when the repository *is* flow, or when a task depends on a
+flow feature that has not shipped yet — otherwise CI runs the released flow against the code
+under review, and a task using the new behavior fails no matter what the PR does.
+
+```yaml
+- name: Build flow
+  run: go build -o ./bin/flow .
+
+- name: Run tests with the freshly built flow
+  uses: flowexec/action@v1
+  with:
+    executable: 'test unit'
+    flow-binary: ./bin/flow
+```
+
+The path is relative to the workspace root, and takes precedence over `flow-version`.
+
 ## Requirements
 
 - Valid flow workspaces and executables in your repository
diff --git a/action.yaml b/action.yaml
index a3bcb37..d935862 100644
--- a/action.yaml
+++ b/action.yaml
@@ -37,6 +37,15 @@ inputs:
     required: false
     default: 'latest'
 
+  flow-binary:
+    description: >-
+      Path to a pre-built flow binary to use instead of installing one, relative to
+      the workspace root. Takes precedence over flow-version. Intended for testing a
+      flow build before it is released - notably flow's own CI, which would otherwise
+      run its tasks with a released flow rather than the code under review.
+    required: false
+    default: ''
+
   params:
     description: 'Parameters to pass to the executable (KEY=VALUE pairs, one per line or comma-separated)'
     required: false
@@ -115,6 +124,7 @@ runs:
         FLOW_VERSION: ${{ inputs.flow-version }}
 
     - name: Cache flow binary
+      if: inputs.flow-binary == ''
       uses: actions/cache@v4
       id: flow-cache
       with:
@@ -129,6 +139,7 @@ runs:
       env:
         SCRIPTS_DIR: ${{ github.action_path }}/scripts
         FLOW_VERSION: ${{ inputs.flow-version }}
+        FLOW_BINARY: ${{ inputs.flow-binary }}
         TIMEOUT: ${{ inputs.timeout }}
         CACHE_HIT: ${{ steps.flow-cache.outputs.cache-hit }}
 
diff --git a/scripts/install-flow.sh b/scripts/install-flow.sh
index e136bef..12210e6 100755
--- a/scripts/install-flow.sh
+++ b/scripts/install-flow.sh
@@ -15,7 +15,25 @@ if [ "$RUNNER_OS_TYPE" = "windows" ] && [[ ":$PATH:" != *":$HOME/bin:"* ]]; then
     echo "$HOME/bin" >> "$GITHUB_PATH"
 fi
 
-if [ "${CACHE_HIT:-}" = "true" ] && command -v flow &>/dev/null; then
+if [ -n "${FLOW_BINARY:-}" ]; then
+    # A caller-supplied build takes precedence over anything downloadable. This is
+    # how a repo tests the flow binary it just built rather than a released one.
+    if [ ! -f "$FLOW_BINARY" ]; then
+        echo "flow-binary not found: $FLOW_BINARY"
+        exit 1
+    fi
+    echo "Using provided flow binary: $FLOW_BINARY"
+
+    if [ "$RUNNER_OS_TYPE" = "windows" ]; then
+        install_dir="$HOME/bin"
+        mkdir -p "$install_dir"
+        cp "$FLOW_BINARY" "$install_dir/flow.exe"
+        chmod +x "$install_dir/flow.exe"
+    else
+        sudo cp "$FLOW_BINARY" /usr/local/bin/flow
+        sudo chmod +x /usr/local/bin/flow
+    fi
+elif [ "${CACHE_HIT:-}" = "true" ] && command -v flow &>/dev/null; then
     echo "Using cached flow binary"
 else
     echo "Installing flow CLI..."