docs: recommend pinning runtime_ref to a gateway commit SHA

README.md

@@ -48,6 +48,7 @@ marked values. Minimal shape:
 ```yaml
       - uses: lightninglabs/gateway-action@<COMMIT_SHA> # vX.Y.Z
         with:
+          runtime_ref:     <GATEWAY_COMMIT_SHA> # vX.Y.Z
           event_name:      ${{ github.event_name }}
           event_action:    ${{ github.event.action }}
           repo:            ${{ github.repository }}
@@ -65,9 +66,17 @@ At least one of `claude_code_oauth_token` or `anthropic_api_key` must be set;
 the example uses OAuth. To use an Anthropic API key instead (tried first if both
 are set), add `anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}`.
 
-Pin `uses:` to a **full commit SHA** with a trailing `# vX.Y.Z` comment — never
-a bare tag. Full onboarding (App install, secrets, installation id) lives in the
-private repo's `docs/consumer-setup.md`.
+Pin **both** to a full commit SHA with a trailing `# vX.Y.Z` comment — never a
+bare tag:
+
+- `uses:` → a `gateway-action` commit SHA.
+- `runtime_ref:` → the matching `lightninglabs/gateway` runtime commit SHA.
+
+The action SHA alone is not enough: it fixes the *action* code but resolves the
+runtime at `runtime_ref`, which defaults to a movable tag. Pinning `runtime_ref`
+to a commit SHA closes that gap, so a re-tagged runtime can't change what runs
+without a consumer PR. Full onboarding (App install, secrets, installation id)
+lives in the private repo's `docs/consumer-setup.md`.
 
 ## Prerequisites
 
@@ -80,10 +89,13 @@ private repo's `docs/consumer-setup.md`.
 ## Versioning
 
 This repo is versioned in **lockstep** with `lightninglabs/gateway`. Each
-release tag here pins the matching gateway runtime ref (the `ref:` on the
-checkout step in `action.yml`). A given `gateway-action` SHA therefore maps
-deterministically to one runtime version — consumers track a single version
-axis.
+release sets the `runtime_ref` *default* to the matching gateway runtime tag, so
+a given `gateway-action` SHA maps to one runtime version for convenience.
+
+That default is a **tag**, which is movable, so for an immutable deployment pin
+`runtime_ref` to a gateway commit SHA explicitly (see above). Both pins then
+track in lockstep: bump the `uses:` SHA and the `runtime_ref` SHA together,
+updating both trailing `# vX.Y.Z` comments.
 
 | gateway-action | gateway runtime ref |
 |----------------|---------------------|

docs/architecture.md

@@ -64,4 +64,4 @@ The composite steps in [`action.yml`](../action.yml):
 
 ## Versioning (lockstep)
 
-This repo is versioned in lockstep with `lightninglabs/gateway`. Each release tag here sets the `runtime_ref` input default to the matching gateway runtime ref. A given `gateway-action` SHA therefore maps deterministically to one runtime version — consumers track a single version axis. The `runtime_ref` input exists only as an override for testing an unreleased runtime.
+This repo is versioned in lockstep with `lightninglabs/gateway`. Each release sets the `runtime_ref` input default to the matching gateway runtime ref, so a given `gateway-action` SHA maps to one runtime version by default. That default is a **tag**, which is movable — so for an immutable deployment, consumers pin `runtime_ref` to a gateway commit SHA explicitly (two pins, tracked in lockstep). The `runtime_ref` input also doubles as the override for testing an unreleased runtime.

templates/gateway.yml

@@ -12,9 +12,13 @@ name: gateway
 #   1. The `@<SHA>` on the `uses:` line — pin to a full commit SHA of a
 #      gateway-action release, with a trailing `# vX.Y.Z` comment.
 #      See https://github.com/lightninglabs/gateway-action/releases.
-#   2. `installation_id` — the numeric App installation id for *this* repo
+#   2. `runtime_ref` — pin to the gateway *runtime* commit SHA for the same
+#      release (trailing `# vX.Y.Z`). Without it, runtime_ref defaults to a
+#      movable tag, so a re-tagged runtime could change what runs with no
+#      consumer PR. Pinning both axes routes every upgrade through review.
+#   3. `installation_id` — the numeric App installation id for *this* repo
 #      (see gateway docs/consumer-setup.md).
-#   3. The Anthropic / Claude auth secret(s) you have available (one of
+#   4. The Anthropic / Claude auth secret(s) you have available (one of
 #      ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN must be set; both are
 #      accepted with API tried first and OAuth as fallback).
 #
@@ -40,8 +44,12 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 15
     steps:
-      - uses: lightninglabs/gateway-action@REPLACE_WITH_COMMIT_SHA # v0.4.2
+      - uses: lightninglabs/gateway-action@REPLACE_WITH_COMMIT_SHA # v0.4.3
         with:
+          # Pin the private runtime to an immutable commit (matches the action
+          # SHA-pin above). Without this it defaults to a movable tag, so a
+          # re-tagged runtime could change what runs with no consumer PR.
+          runtime_ref: REPLACE_WITH_GATEWAY_COMMIT_SHA # v0.4.3
           event_name:      ${{ github.event_name }}
           event_action:    ${{ github.event.action }}
           repo:            ${{ github.repository }}