fix(action): default the binary version to the pinned action ref

CHANGELOG.md

@@ -7,6 +7,14 @@ project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+### Changed
+- **The Action installs the release that ships with the ref you pinned, instead of `latest`.** The
+  `version` input defaulted to `latest`, so a workflow pinned to a commit SHA still resolved the
+  newest release at run time - a new release could flip a `surf check` verdict on a repo whose
+  workflow file and hubs had not changed. It now defaults to the workspace version bundled at the
+  pinned action ref, completing for the binary what #118 did for the installer script. An explicit
+  `version:` still wins, and `version: latest` restores the floating behaviour.
+
 ## [0.8.0] - 2026-07-02
 
 ### Added

action.yml

@@ -15,8 +15,10 @@ inputs:
     description: Arguments passed to surf (e.g. "check" or "check --format json").
     default: check
   version:
-    description: Release tag to install (e.g. v0.1.0), or "latest".
-    default: latest
+    description: >-
+      Release tag to install (e.g. v0.1.0), or "latest" for the newest release. Defaults to the
+      version bundled at this action ref, so pinning `uses:` also pins the binary.
+    default: ""
   working-directory:
     description: Directory to run surf in (must contain or sit under a surf.toml).
     default: .
@@ -29,10 +31,25 @@ runs:
       env:
         SURF_VERSION: ${{ inputs.version }}
         SURF_INSTALL_DIR: ${{ runner.temp }}/surf-bin
-      # Run the installer bundled at the *pinned* action ref rather than the mutable
-      # main branch, so a SHA-pinned `uses:` also pins the installer script
-      # (defense-in-depth; install.sh already checksum-verifies the download).
-      run: sh "${{ github.action_path }}/install.sh"
+        ACTION_PATH: ${{ github.action_path }}
+      # Both the installer and the version it installs come from the *pinned* action ref rather
+      # than the mutable main branch or the floating `latest` release, so a SHA-pinned `uses:`
+      # pins the binary too (#169; the installer half was #118). An explicit `version:` still
+      # wins, and `version: latest` opts back into tracking the newest release.
+      run: |
+        if [ -z "$SURF_VERSION" ]; then
+          bundled="$(sh "$ACTION_PATH/scripts/workspace-version.sh")" || bundled=""
+          # Fail closed: falling back to `latest` here would silently restore the floating
+          # install this default exists to prevent.
+          if [ -z "$bundled" ]; then
+            echo "surf: could not read the bundled version at this action ref" >&2
+            echo "surf: set the action's \`version:\` input explicitly (e.g. version: v0.8.0)" >&2
+            exit 1
+          fi
+          SURF_VERSION="v$bundled"
+        fi
+        export SURF_VERSION
+        sh "$ACTION_PATH/install.sh"
     - name: Run surf
       shell: bash
       working-directory: ${{ inputs.working-directory }}

docs/guides/ci-integration.md

@@ -22,9 +22,23 @@ jobs:
       - uses: Connorrmcd6/surface@v0.8.0
 ```
 
-The action takes `args` (default `check`), `version` (default `latest`), and
-`working-directory` (default `.`). To emit machine-readable output for another job or a reviewer
-bot, set `args: check --format json`.
+The action takes `args` (default `check`), `version`, and `working-directory` (default `.`). To
+emit machine-readable output for another job or a reviewer bot, set `args: check --format json`.
+
+### Which binary you get
+
+`version` defaults to the release that ships with the action ref you pinned - `uses:
+Connorrmcd6/surface@v0.8.0` installs `surf` v0.8.0, and a commit-SHA pin resolves the same way.
+So the gate's behaviour only changes when you move the pin, and a `surf check` verdict is
+reproducible for as long as the workflow file stays put.
+
+To track the newest release instead, ask for it explicitly:
+
+```yaml
+- uses: Connorrmcd6/surface@v0.8.0
+  with:
+    version: latest       # or a specific tag, e.g. v0.7.0
+```
 
 ### Checkout depth
 

scripts/bump-docs-version.sh

@@ -6,18 +6,7 @@ set -eu
 
 cd "$(dirname "$0")/.."
 
-version=$(awk '
-  /^\[workspace\.package\]/ { in_ws = 1; next }
-  /^\[/ { in_ws = 0 }
-  in_ws && /^version *= *"/ {
-    match($0, /"[^"]+"/); print substr($0, RSTART + 1, RLENGTH - 2); exit
-  }
-' Cargo.toml)
-
-if [ -z "$version" ]; then
-  echo "error: could not read [workspace.package] version from Cargo.toml" >&2
-  exit 1
-fi
+version=$(sh scripts/workspace-version.sh)
 
 files=$(grep -rlE 'Connorrmcd6/surface@v[0-9]+\.[0-9]+\.[0-9]+' README.md docs || true)
 if [ -z "$files" ]; then

scripts/workspace-version.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env sh
+# Prints the `[workspace.package]` version from Cargo.toml (e.g. `0.8.0`) - the single source of
+# truth for the released version. Shared by scripts/bump-docs-version.sh (which stamps the pinned
+# Action refs in the docs) and by action.yml (which defaults the binary version to the one bundled
+# at the pinned action ref), so both read one definition rather than each parsing Cargo.toml.
+set -eu
+
+cd "$(dirname "$0")/.."
+
+version=$(awk '
+  /^\[workspace\.package\]/ { in_ws = 1; next }
+  /^\[/ { in_ws = 0 }
+  in_ws && /^version *= *"/ {
+    match($0, /"[^"]+"/); print substr($0, RSTART + 1, RLENGTH - 2); exit
+  }
+' Cargo.toml)
+
+if [ -z "$version" ]; then
+  echo "error: could not read [workspace.package] version from Cargo.toml" >&2
+  exit 1
+fi
+
+printf '%s\n' "$version"