From 7abd3e0dbd78a5b11b05b911ad74bd6626dbeb63 Mon Sep 17 00:00:00 2001 From: saubyk <39208279+saubyk@users.noreply.github.com> Date: Thu, 18 Jun 2026 19:49:13 -0700 Subject: [PATCH] docs: recommend pinning runtime_ref to a gateway commit SHA MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A SHA-pinned uses: fixes the action code but resolves the runtime at runtime_ref, which defaults to a movable tag — so a re-tagged runtime can change what runs with no consumer PR. Document pinning both axes (action SHA + runtime_ref SHA) in templates/gateway.yml, README, and architecture.md. Surfaced by calvinrzachman in lightningnetwork/lnd#10910. --- README.md | 26 +++++++++++++++++++------- docs/architecture.md | 2 +- templates/gateway.yml | 14 +++++++++++--- 3 files changed, 31 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index e251dc4..0992288 100644 --- a/README.md +++ b/README.md @@ -48,6 +48,7 @@ marked values. Minimal shape: ```yaml - uses: lightninglabs/gateway-action@ # vX.Y.Z with: + runtime_ref: # 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 | |----------------|---------------------| diff --git a/docs/architecture.md b/docs/architecture.md index 6916d28..2dbfc90 100644 --- a/docs/architecture.md +++ b/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. diff --git a/templates/gateway.yml b/templates/gateway.yml index 22e00b9..213b44a 100644 --- a/templates/gateway.yml +++ b/templates/gateway.yml @@ -12,9 +12,13 @@ name: gateway # 1. The `@` 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 }}