From eebec0e19f4c0beae760c18bbaf63b4f6b8a5776 Mon Sep 17 00:00:00 2001 From: Amp Date: Mon, 16 Nov 2026 00:05:34 +0000 Subject: [PATCH 1/2] feat(web3): pin the n8n task runners to the n8n version automatically Renovate now updates only ghcr.io/thundersquared/n8n; n8nio/runners is disabled there. On Renovate's renovate/n8n branch, n8n-sync-runners.yml runs ci/n8n-sync-runners.sh, which pins n8nio/runners to the n8n tag with the digest Docker Hub serves for it, pushes the result and dispatches Validate on it. Renovate ignores those commits (gitIgnoredAuthors). ci/n8n-versions-check.sh runs in the required yamllint job and fails unless both images share a tag, so neither a person nor automerge can merge an n8n update before the runners follow it. Amp-Thread-ID: https://ampcode.com/threads/T-01a1ca59-ee06-73ee-b22a-c0618358f4cf Co-authored-by: Anatoli Nicolae --- .github/workflows/n8n-sync-runners.yml | 63 ++++++++++++++++++++++++++ .github/workflows/validate.yml | 7 +++ CLAUDE.md | 14 +++++- ci/n8n-sync-runners.sh | 33 ++++++++++++++ ci/n8n-versions-check.sh | 34 ++++++++++++++ ci/validate.sh | 3 ++ renovate.json | 17 ++++--- 7 files changed, 162 insertions(+), 9 deletions(-) create mode 100644 .github/workflows/n8n-sync-runners.yml create mode 100755 ci/n8n-sync-runners.sh create mode 100755 ci/n8n-versions-check.sh diff --git a/.github/workflows/n8n-sync-runners.yml b/.github/workflows/n8n-sync-runners.yml new file mode 100644 index 00000000..6a8c11d4 --- /dev/null +++ b/.github/workflows/n8n-sync-runners.yml @@ -0,0 +1,63 @@ +--- +# n8n's external task runners must run the same version as n8n. Renovate +# updates only the n8n image (renovate.json disables n8nio/runners), so this +# workflow pins n8nio/runners to the same tag on Renovate's n8n branch: +# +# 1. Renovate pushes renovate/n8n with a new n8n tag. Until this workflow +# has run, ci/n8n-versions-check.sh fails the required yamllint check, +# so neither a person nor Renovate's automerge can merge it. +# 2. This workflow runs ci/n8n-sync-runners.sh and pushes the result. Its +# commits are listed in renovate.json's gitIgnoredAuthors, so Renovate +# keeps managing the branch, and recreates the commit by triggering this +# workflow again whenever it rebases. +# 3. A push made with GITHUB_TOKEN starts no workflows, so it dispatches +# Validate on the branch itself. Those check runs land on the pushed +# commit and satisfy the pull request's required checks. +# +# When the runners tag is not on Docker Hub yet, the sync fails and the pull +# request stays blocked; rerun this workflow once the tag exists. + +name: Sync n8n task runners + +on: + push: + branches: + - renovate/n8n + workflow_dispatch: + +permissions: {} + +concurrency: + group: n8n-sync-runners-${{ github.ref }} + cancel-in-progress: true + +jobs: + sync: + name: Pin n8nio/runners to the n8n version + runs-on: ubuntu-latest + timeout-minutes: 5 + permissions: + contents: write # push the pinned runners image to this branch + actions: write # dispatch Validate on the pushed commit + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: true # the commit step pushes with this token + + - name: Pin n8nio/runners + run: ci/n8n-sync-runners.sh + + - name: Commit and dispatch Validate + env: + GH_TOKEN: ${{ github.token }} + BRANCH: ${{ github.ref_name }} + run: | + if git diff --quiet; then + echo "n8nio/runners already matches n8n" + exit 0 + fi + git config user.name 'github-actions[bot]' + git config user.email '41898282+github-actions[bot]@users.noreply.github.com' + git commit -am "chore(deps): pin n8nio/runners to the n8n version" + git push origin "HEAD:$BRANCH" + gh workflow run validate.yml --ref "$BRANCH" diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml index fb1cfe04..b7bcc1e8 100644 --- a/.github/workflows/validate.yml +++ b/.github/workflows/validate.yml @@ -134,6 +134,13 @@ jobs: - name: Lint YAML run: yamllint --strict --config-file .yamllint . + # Runs on every pull request, in this required job: Renovate's n8n pull + # requests move only the n8n image and must fail here until + # n8n-sync-runners.yml has pinned the task runners to the same version. + - name: Check n8n and task runners versions match + if: ${{ !cancelled() }} + run: ci/n8n-versions-check.sh + ansible: name: ansible-lint needs: yamllint diff --git a/CLAUDE.md b/CLAUDE.md index f61914f0..6546828f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -151,12 +151,14 @@ Applied to: cloudflared, mailflow frontend + backend, n8n runner. `headscale` is `ci/validate.sh` runs every check that CI runs: yamllint, ansible-lint, `tofu validate` / `tofu fmt` for `tower`, a zizmor audit of the validation -workflow, and `ci/headscale-check.sh`, which runs the headscale image pinned in +workflow, `ci/n8n-versions-check.sh`, which fails unless web3's n8n and +`n8nio/runners` images are pinned to the same version, and +`ci/headscale-check.sh`, which runs the headscale image pinned in `tower/containers/headscale/docker-compose.yml` (`configtest`, `policy check`) against the committed config and policy and needs docker. Run it before pushing; the same failures otherwise surface as a red PR. -In CI only yamllint runs on every pull request. The other checks run when the +In CI only yamllint and the n8n versions check run on every pull request. The other checks run when the diff touches what they read, per the pathspecs in the "Detect which checks the change affects" step of `validate.yml`. When a check starts reading a new path, add it there: otherwise a PR that changes only that path skips the check, and a @@ -208,3 +210,11 @@ resolved only as a transitive dependency of `geerlingguy.docker`, which declares no dependencies of its own — so a clean runner would have failed `ansible-lint`'s syntax check. Keep them listed. +## n8n and its task runners + +web3's n8n and `n8nio/runners` must be pinned to the same version. Renovate +updates only the n8n image, on the `renovate/n8n` branch; +`.github/workflows/n8n-sync-runners.yml` then pins the runners to the same tag +with `ci/n8n-sync-runners.sh` and dispatches Validate on the result. Until it +has run, `ci/n8n-versions-check.sh` fails the required yamllint check. When +bumping n8n by hand, run `ci/n8n-sync-runners.sh` after editing the n8n tag. diff --git a/ci/n8n-sync-runners.sh b/ci/n8n-sync-runners.sh new file mode 100755 index 00000000..66711670 --- /dev/null +++ b/ci/n8n-sync-runners.sh @@ -0,0 +1,33 @@ +#!/usr/bin/env bash +# Pin n8nio/runners to the version of the n8n image, with the digest Docker Hub +# serves for that tag. Renovate updates only the n8n image; this is run on its +# branch by .github/workflows/n8n-sync-runners.yml, and by hand after editing +# the n8n tag. Fails without changing anything when the runners tag does not +# exist yet. +# +# Usage: ci/n8n-sync-runners.sh [COMPOSE_FILE] + +set -euo pipefail + +compose="${1:-web3/containers/n8n/docker-compose.yml}" + +version=$(sed -nE 's#^[[:space:]]*image:[[:space:]]*ghcr\.io/thundersquared/n8n:([^@[:space:]]+).*#\1#p' "$compose") +if [ -z "$version" ]; then + echo "$compose: no ghcr.io/thundersquared/n8n image found" >&2 + exit 1 +fi + +token=$(curl -fsS "https://auth.docker.io/token?service=registry.docker.io&scope=repository:n8nio/runners:pull" | jq -r .token) +headers=$(curl -fsSI \ + -H "Authorization: Bearer $token" \ + -H 'Accept: application/vnd.oci.image.index.v1+json, application/vnd.docker.distribution.manifest.list.v2+json' \ + "https://registry-1.docker.io/v2/n8nio/runners/manifests/$version") || headers= +digest=$(printf '%s\n' "$headers" | tr -d '\r' | + sed -nE 's#^docker-content-digest:[[:space:]]*(sha256:[0-9a-f]{64})$#\1#Ip') +if [ -z "$digest" ]; then + echo "n8nio/runners:$version not found on Docker Hub" >&2 + exit 1 +fi + +sed -i -E "s#^([[:space:]]*image:[[:space:]]*n8nio/runners:)[^[:space:]]+#\1$version@$digest#" "$compose" +echo "n8nio/runners pinned to $version@$digest" diff --git a/ci/n8n-versions-check.sh b/ci/n8n-versions-check.sh new file mode 100755 index 00000000..a6c56a8c --- /dev/null +++ b/ci/n8n-versions-check.sh @@ -0,0 +1,34 @@ +#!/usr/bin/env bash +# Fail unless n8n and its external task runners are pinned to the same +# version. The runners must run n8n's own version. Renovate updates only the +# n8n image, and .github/workflows/n8n-sync-runners.yml then pins the runners +# to match, so this check fails a pull request until that has happened. +# +# Usage: ci/n8n-versions-check.sh [COMPOSE_FILE...] + +set -euo pipefail + +if [ "$#" -eq 0 ]; then + set -- web3/containers/n8n/docker-compose.yml +fi + +# tag FILE IMAGE: the tag of IMAGE pinned in FILE, without the digest. +tag() { + sed -nE "s#^[[:space:]]*image:[[:space:]]*$2:([^@[:space:]]+).*#\1#p" "$1" +} + +status=0 +for compose in "$@"; do + n8n=$(tag "$compose" 'ghcr\.io/thundersquared/n8n') + runners=$(tag "$compose" 'n8nio/runners') + if [ -z "$n8n" ] || [ -z "$runners" ]; then + echo "$compose: could not find both the n8n and the n8nio/runners image" >&2 + status=1 + elif [ "$n8n" != "$runners" ]; then + echo "$compose: n8n is $n8n but its task runners are $runners; run ci/n8n-sync-runners.sh" >&2 + status=1 + else + echo "$compose: n8n and task runners both at $n8n" + fi +done +exit "$status" diff --git a/ci/validate.sh b/ci/validate.sh index 0d75e29b..df5aa5a3 100755 --- a/ci/validate.sh +++ b/ci/validate.sh @@ -39,6 +39,9 @@ else status=1 fi +# n8n and its task runners pinned to the same version. +run "n8n versions" ci/n8n-versions-check.sh + # 2. Ansible correctness: syntax-check, FQCN, idempotency, risky permissions. if have ansible-lint; then run "ansible-lint" ansible-lint --offline diff --git a/renovate.json b/renovate.json index a02600b4..23a009bf 100644 --- a/renovate.json +++ b/renovate.json @@ -17,6 +17,7 @@ "prHourlyLimit": 0, "rangeStrategy": "pin", "rebaseWhen": "conflicted", + "gitIgnoredAuthors": ["41898282+github-actions[bot]@users.noreply.github.com"], "commitBodyTable": true, "vulnerabilityAlerts": { "labels": ["security"], @@ -40,15 +41,18 @@ "separateMajorMinor": false }, { - "description": "Group n8n and its task runners image updates in one PR so their versions stay in step.", + "description": "n8n updates land on the renovate/n8n branch, where .github/workflows/n8n-sync-runners.yml pins n8nio/runners to the same version. Keep the group name: the workflow triggers on that branch.", "matchDatasources": ["docker"], - "matchPackageNames": [ - "ghcr.io/thundersquared/n8n", - "n8nio/runners" - ], + "matchPackageNames": ["ghcr.io/thundersquared/n8n"], "groupName": "n8n", "separateMajorMinor": false }, + { + "description": "n8nio/runners follows the n8n image and is pinned by n8n-sync-runners.yml, never updated on its own: the runners must run n8n's version, and Docker Hub publishes runners tags (n8n 3.x prereleases) the n8n image does not have.", + "matchDatasources": ["docker"], + "matchPackageNames": ["n8nio/runners"], + "enabled": false + }, { "description": "Group the n8n sandbox service images in one PR: the API, runner and sandbox images ship as one release and are only supported together.", "matchDatasources": ["docker"], @@ -104,8 +108,7 @@ "ghcr.io/maathimself/mailflow-frontend", "ghcr.io/maathimself/mailflow-backend", "ghcr.io/tailscale/tailscale", - "ghcr.io/thundersquared/n8n", - "n8nio/runners" + "ghcr.io/thundersquared/n8n" ], "matchUpdateTypes": ["patch", "digest", "pinDigest"], "automerge": true From 0f9169d4d8885d70205730670de05ab3df5f1995 Mon Sep 17 00:00:00 2001 From: Amp Date: Mon, 16 Nov 2026 00:14:34 +0000 Subject: [PATCH 2/2] fix(ci): push the n8n runners sync with a token that runs Validate Checks from a workflow_dispatch run do not satisfy a ruleset's required status checks, so dispatching Validate after a GITHUB_TOKEN push left the synced commit blocked. Push with the N8N_SYNC_TOKEN secret instead, so the push runs Validate on pull_request like any other, and drop the dispatch. Amp-Thread-ID: https://ampcode.com/threads/T-01a1ca59-ee06-73ee-b22a-c0618358f4cf Co-authored-by: Anatoli Nicolae --- .github/workflows/n8n-sync-runners.yml | 32 ++++++++++++++++++-------- CLAUDE.md | 4 ++-- 2 files changed, 24 insertions(+), 12 deletions(-) diff --git a/.github/workflows/n8n-sync-runners.yml b/.github/workflows/n8n-sync-runners.yml index 6a8c11d4..621639f7 100644 --- a/.github/workflows/n8n-sync-runners.yml +++ b/.github/workflows/n8n-sync-runners.yml @@ -10,9 +10,15 @@ # commits are listed in renovate.json's gitIgnoredAuthors, so Renovate # keeps managing the branch, and recreates the commit by triggering this # workflow again whenever it rebases. -# 3. A push made with GITHUB_TOKEN starts no workflows, so it dispatches -# Validate on the branch itself. Those check runs land on the pushed -# commit and satisfy the pull request's required checks. +# 3. It pushes with the N8N_SYNC_TOKEN secret, not GITHUB_TOKEN: a push made +# with GITHUB_TOKEN starts no workflows, and a dispatched Validate run +# cannot satisfy the pull request's required checks. With this token the +# push runs Validate on pull_request as usual. It also runs this workflow +# once more, which finds nothing to change. +# +# N8N_SYNC_TOKEN is a fine-grained personal access token (or a GitHub App +# installation token) limited to this repository, with Contents: read and +# write. # # When the runners tag is not on Docker Hub yet, the sync fails and the pull # request stays blocked; rerun this workflow once the tag exists. @@ -25,7 +31,8 @@ on: - renovate/n8n workflow_dispatch: -permissions: {} +permissions: + contents: read concurrency: group: n8n-sync-runners-${{ github.ref }} @@ -36,20 +43,26 @@ jobs: name: Pin n8nio/runners to the n8n version runs-on: ubuntu-latest timeout-minutes: 5 - permissions: - contents: write # push the pinned runners image to this branch - actions: write # dispatch Validate on the pushed commit steps: + - name: Require N8N_SYNC_TOKEN + env: + N8N_SYNC_TOKEN: ${{ secrets.N8N_SYNC_TOKEN }} + run: | + if [ -z "$N8N_SYNC_TOKEN" ]; then + echo "::error::The N8N_SYNC_TOKEN secret is not set; see the header of this workflow." >&2 + exit 1 + fi + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: + token: ${{ secrets.N8N_SYNC_TOKEN }} persist-credentials: true # the commit step pushes with this token - name: Pin n8nio/runners run: ci/n8n-sync-runners.sh - - name: Commit and dispatch Validate + - name: Commit and push env: - GH_TOKEN: ${{ github.token }} BRANCH: ${{ github.ref_name }} run: | if git diff --quiet; then @@ -60,4 +73,3 @@ jobs: git config user.email '41898282+github-actions[bot]@users.noreply.github.com' git commit -am "chore(deps): pin n8nio/runners to the n8n version" git push origin "HEAD:$BRANCH" - gh workflow run validate.yml --ref "$BRANCH" diff --git a/CLAUDE.md b/CLAUDE.md index 6546828f..a0626976 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -215,6 +215,6 @@ declares no dependencies of its own — so a clean runner would have failed web3's n8n and `n8nio/runners` must be pinned to the same version. Renovate updates only the n8n image, on the `renovate/n8n` branch; `.github/workflows/n8n-sync-runners.yml` then pins the runners to the same tag -with `ci/n8n-sync-runners.sh` and dispatches Validate on the result. Until it -has run, `ci/n8n-versions-check.sh` fails the required yamllint check. When +with `ci/n8n-sync-runners.sh`, pushing with the `N8N_SYNC_TOKEN` secret so the +push runs Validate like any other. Until it has run, `ci/n8n-versions-check.sh` fails the required yamllint check. When bumping n8n by hand, run `ci/n8n-sync-runners.sh` after editing the n8n tag.