🌱 sync: top up v5 with the v4.0.0/v4.0.1 release line

.github/dependabot.yml

@@ -8,6 +8,14 @@ updates:
     labels:
       - "dependencies"
     open-pull-requests-limit: 10
+    ignore:
+      # Module path moved upstream to cel.dev/cel-go (v0.26.0+); dependabot
+      # reports go_module_path_mismatch and fails the whole gomod job.
+      # Remove once /src/go.mod migrates to the new module path.
+      - dependency-name: "github.com/google/cel-go"
+      # teatest lives in a nested module with independent tags; resolving
+      # github.com/charmbracelet/x@v0.1.0 fails (dependency_file_not_resolvable).
+      - dependency-name: "github.com/charmbracelet/x/exp/teatest"
 
   - package-ecosystem: "github-actions"
     directory: "/"

.github/release-lines.yml

@@ -46,6 +46,11 @@ pinned:
   # release lines and nothing else: a feature branch gets the same gate through
   # `pull_request`, and running it on every pushed branch would burn runner
   # minutes re-scanning code that has not reached a release line.
+  # Added with the docs link checker (#5278), after the v2 line was sunset
+  # (#5030-era). It gates src/docs/ links on v4 only; v2 is excluded rather
+  # than back-filled, because the workflow never ran there and adding it
+  # would gate a line no longer taking doc changes.
+  docs-link-check.yml: [-v2]
   go-security-analysis.yml: []
   podman-arm64-lane.yml: []
   podman-contract.yml: []

.github/workflows/dashboard-lint.yml

@@ -1,11 +1,23 @@
 name: Dashboard Lint
+
+# The checker itself is in scope, not just the files it checks (#5388).
+# The syntax-check job runs .github/scripts/check-inline-js.js, but the filter
+# named only 'dashboard/**' — so a change that broke the checker (or silently
+# stopped it detecting anything) ran no CI at all, and the next dashboard PR
+# would then pass against a checker nobody had exercised. The workflow file is
+# listed for the same reason: an edit to the `find` invocation here changes
+# what gets checked, and that edit must run the job it changes.
 on:
   push:
     paths:
       - 'dashboard/**'
+      - '.github/scripts/check-inline-js.js'
+      - '.github/workflows/dashboard-lint.yml'
   pull_request:
     paths:
       - 'dashboard/**'
+      - '.github/scripts/check-inline-js.js'
+      - '.github/workflows/dashboard-lint.yml'
 
 permissions:
   contents: read

.github/workflows/docker.yml

@@ -62,6 +62,26 @@ jobs:
   # merges and is deleted. workflow_dispatch always pushes so a throwaway branch
   # can be published for a hive on demand before merge.
   #
+  # EXCEPTION: `release-gate/*` (#5072). tagged-release.yml pushes its
+  # release commit to a throwaway `release-gate/v<version>` branch to earn a
+  # `gate` check on
+  # that exact SHA before pushing to protected `v4` (see docs/releases.md,
+  # "Satisfying branch protection"). That push uses the job's default
+  # GITHUB_TOKEN, and GitHub's documented recursive-workflow guard means a
+  # GITHUB_TOKEN push never fires another workflow's `push` trigger — so
+  # tagged-release.yml has to fall back to explicitly dispatching this
+  # workflow via `gh workflow run docker.yml --ref release-gate/v<version>`
+  # instead. Without
+  # this exception, that dispatch would hit the `workflow_dispatch` branch
+  # below and force push=true on a branch nothing should ever publish images
+  # for: a full two-platform GHCR push under a one-off scratch branch name,
+  # solely to obtain a status check that only needs `gate` (a five-second job)
+  # to run. `release-gate/*` branches are deliberately never in LONG_LIVED and
+  # are deleted immediately after use (tagged-release.yml's `trap ... EXIT`),
+  # so this
+  # exception cannot leave a stray moving tag behind — it only ever prevents
+  # one from being created in the first place.
+  #
   # The long-lived branch set is defined ONCE below (LONG_LIVED). To add or
   # remove one, edit only that list — the whole workflow derives from this job's
   # output, so nothing else changes.
@@ -71,6 +91,14 @@ jobs:
   # new release line and never publish its <branch>-latest tag (#4462). The
   # release-line guard asserts this list against .github/release-lines.yml —
   # see the `env_lists` entry there and src/docs/release-line-guard.md.
+  #
+  # NOTE (#5339/#5356): do not special-case `release-gate/*` pull requests in
+  # this job. GITHUB_TOKEN-opened release PR runs may be recursion-blocked
+  # before any job starts, and workflow_dispatch check-runs are not associated
+  # with a PR even when dispatched after it exists. tagged-release.yml handles
+  # that release-only gap by mirroring its verified check-run as a SHA-scoped
+  # commit status. Ordinary pull requests still need this job unchanged so
+  # their head SHA receives the required `gate` check-run (#4965).
   gate:
     runs-on: ubuntu-latest
     outputs:
@@ -90,13 +118,24 @@ jobs:
           EVENT: ${{ github.event_name }}
         run: |
           push=false
-          if [ "$EVENT" = "workflow_dispatch" ]; then
-            push=true
-          else
-            for b in $LONG_LIVED; do
-              if [ "$b" = "$REF_NAME" ]; then push=true; break; fi
-            done
-          fi
+          case "$REF_NAME" in
+            release-gate/*)
+              # See the EXCEPTION comment above this job: this scratch branch
+              # only ever exists to earn a `gate` check for
+              # tagged-release.yml, never to publish an image, regardless of
+              # trigger event.
+              push=false
+              ;;
+            *)
+              if [ "$EVENT" = "workflow_dispatch" ]; then
+                push=true
+              else
+                for b in $LONG_LIVED; do
+                  if [ "$b" = "$REF_NAME" ]; then push=true; break; fi
+                done
+              fi
+              ;;
+          esac
           echo "push=$push" >> "$GITHUB_OUTPUT"
           echo "Push to GHCR: $push (branch=$REF_NAME event=$EVENT)"
 
@@ -109,7 +148,22 @@ jobs:
     # real `hive --version` smoke test (`docker`), plus `build-and-test`
     # (go build + go vet) and `overlayfs-exec-guard`. Building here too would
     # be a third image build of the same commit.
-    if: github.event_name != 'pull_request'
+    # `release-gate/*` is excluded for the same reason `merge*` already skips
+    # it (gate forces push=false there): these builds publish NOTHING for the
+    # scratch branch. They are not merely wasted — branch protection evaluates
+    # the whole check SUITE, so while any job in it runs the `gate` context is
+    # not treated as satisfied even though its check-run is already `success`.
+    # The release job's merge waits 120s and a multi-arch build takes ~10min,
+    # so the merge could never win that race (#5339, 8th recurrence).
+    #
+    # No coverage is lost. A release commit modifies CHANGELOG.md and nothing
+    # else — no source, no Dockerfile — so its tree is byte-identical to the v4
+    # tip whose images this workflow already built, published and freshness-
+    # checked minutes earlier. The `gate` job itself still runs on the scratch
+    # branch; that is the whole reason the branch exists.
+    if: >-
+      github.event_name != 'pull_request' &&
+      !startsWith(github.ref_name, 'release-gate/')
     strategy:
       matrix:
         include:
@@ -344,7 +398,16 @@ jobs:
   build-contributor:
     needs: gate
     # Push-only, same as `build` above (#4965).
-    if: github.event_name != 'pull_request'
+    # `release-gate/*` is excluded for the same reason `merge*` already skips
+    # it (gate forces push=false there): these builds publish NOTHING for the
+    # scratch branch. They are not merely wasted — branch protection evaluates
+    # the whole check SUITE, so while any job in it runs the `gate` context is
+    # not treated as satisfied even though its check-run is already `success`.
+    # The release job's merge waits 120s and a multi-arch build takes ~10min,
+    # so the merge could never win that race (#5339, 8th recurrence).
+    if: >-
+      github.event_name != 'pull_request' &&
+      !startsWith(github.ref_name, 'release-gate/')
     strategy:
       matrix:
         include:
@@ -442,7 +505,16 @@ jobs:
   build-hub:
     needs: gate
     # Push-only, same as `build` above (#4965).
-    if: github.event_name != 'pull_request'
+    # `release-gate/*` is excluded for the same reason `merge*` already skips
+    # it (gate forces push=false there): these builds publish NOTHING for the
+    # scratch branch. They are not merely wasted — branch protection evaluates
+    # the whole check SUITE, so while any job in it runs the `gate` context is
+    # not treated as satisfied even though its check-run is already `success`.
+    # The release job's merge waits 120s and a multi-arch build takes ~10min,
+    # so the merge could never win that race (#5339, 8th recurrence).
+    if: >-
+      github.event_name != 'pull_request' &&
+      !startsWith(github.ref_name, 'release-gate/')
     strategy:
       matrix:
         include:

.github/workflows/docs-link-check.yml

@@ -0,0 +1,81 @@
+name: Docs Link Check
+
+# Why this exists
+#
+# kubestellar/docs (the org's published docs site, Next.js on Netlify at
+# kubestellar.io/docs/hive/*) pulls a growing subset of src/docs/*.md straight
+# from this repo's `v4` branch on every site build
+# (kubestellar/docs:scripts/sync-hive-docs.ts fetches the raw file over HTTP
+# and rewrites relative links to site routes or GitHub blob URLs). That sync
+# runs no Markdown linter and no link checker of its own — it trusts this
+# source tree to already be internally consistent.
+#
+# That trust broke concretely once already: #5206 fixed three cross-reference
+# anchors that a heading rename in design/tui.md had silently broken. Nothing
+# failed red when it happened; a human had to notice. This job is the gate
+# that catches the same class of break before merge, for every relative link
+# and heading anchor inside src/docs/ — whether or not the file happens to be
+# on the sync manifest today, since that manifest only grows over time.
+#
+# It intentionally does NOT validate http(s)/mailto links (network-dependent,
+# and not what broke in #5206) and does not touch the sync manifest itself,
+# which lives in the separate kubestellar/docs repository.
+#
+# The job also guards a second, differently-shaped surface: the wiki vault at
+# src/deploy/data/wiki/. src/Dockerfile bakes that tree into the image and
+# src/deploy/entrypoint.sh seeds it with `cp -rn /opt/hive/seed-data/* /data/`,
+# so it is served FLAT from /data/wiki/ with nothing above it. A parent-
+# relative link there resolves for a reviewer browsing this repo and 404s for
+# the operator reading the deployed page — the repo view is the one that lies,
+# which is what makes the break invisible in review (#5309). The wiki step
+# therefore runs --vault-root, which treats the vault directory as the reader's
+# whole filesystem and rejects any escape regardless of what exists in this
+# checkout. Outbound wiki references belong in absolute blob/v4 URLs, which
+# resolve identically in both views (#5308).
+
+on:
+  push:
+    branches:
+      - v4
+      - v5
+    paths:
+      - 'src/docs/**'
+      - 'src/deploy/data/wiki/**'
+      - 'src/scripts/check-docs-links.py'
+      - 'src/scripts/test-check-docs-links.sh'
+      - '.github/workflows/docs-link-check.yml'
+  pull_request:
+    branches:
+      - v4
+      - v5
+    paths:
+      - 'src/docs/**'
+      - 'src/deploy/data/wiki/**'
+      - 'src/scripts/check-docs-links.py'
+      - 'src/scripts/test-check-docs-links.sh'
+      - '.github/workflows/docs-link-check.yml'
+
+permissions:
+  contents: read
+
+jobs:
+  link-check:
+    name: relative links and anchors resolve
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Self-test the checker against fixtures
+        run: bash src/scripts/test-check-docs-links.sh
+
+      - name: Check src/docs/ relative links and anchors
+        run: python3 src/scripts/check-docs-links.py src/docs
+
+      # The wiki vault is checked in --vault-root mode, which models the
+      # DEPLOYED layout rather than this checkout. See the header comment and
+      # check-docs-links.py's docstring: /data/wiki/ has nothing above it, so a
+      # parent-relative link is rejected here even when the target exists in
+      # the repo. Running the plain checker against this tree would pass
+      # exactly the links that are broken in production (#5309).
+      - name: Check wiki vault links against the deployed flat layout
+        run: python3 src/scripts/check-docs-links.py src/deploy/data/wiki --vault-root

.github/workflows/go-security-analysis.yml

@@ -36,13 +36,22 @@ name: Go Security Analysis
 # correct and complete attribution. See that job's own comment for the full
 # reasoning.
 
+# NOTICE is in the path filter because the notice-drift job below compares the
+# COMMITTED repo-root NOTICE byte-for-byte against a fresh regeneration
+# (`check-notice-drift.sh NOTICE /tmp/NOTICE.generated`). NOTICE does not live
+# under src/, so before #5388 a PR editing NOTICE alone — hand-correcting an
+# attribution, or reverting the autofix commit — changed the exact file this
+# gate polices while running neither that gate nor anything else. The drift
+# would surface only on the next unrelated src/ change, attributed to that PR.
+# Same shape as dashboard/openapi.json in v2-tests.yml: guarded by a job whose
+# filter excluded it.
 on:
   push:
     branches: [v2, v4, v5]
-    paths: ['src/**', '.github/workflows/**', '.github/release-lines.yml']
+    paths: ['src/**', 'NOTICE', '.github/workflows/**', '.github/release-lines.yml']
   pull_request:
     branches: [v2, v4, v5]
-    paths: ['src/**', '.github/workflows/**', '.github/release-lines.yml']
+    paths: ['src/**', 'NOTICE', '.github/workflows/**', '.github/release-lines.yml']
   schedule:
     # Weekly, so a newly-PUBLISHED advisory against unchanged code is still
     # found. A push-only trigger cannot catch that: the vulnerability appears
@@ -145,7 +154,7 @@ jobs:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       # A fabricated 40-hex SHA looks exactly like a correct pin and is only
-      # caught when the workflow RUNS. release.yml shipped one (#4908), so every
+      # caught when the workflow RUNS. tagged-release.yml shipped one (#4908), so every
       # tagged release failed at "Prepare all required actions" — discovered
       # only when someone tried to cut a release.
       - name: Check every pinned action SHA exists
@@ -185,6 +194,16 @@ jobs:
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
+      - name: Exercise NOTICE drift diagnostics
+        run: src/scripts/test-check-notice-drift.sh
+
+      # The autofix workflow commits a generated NOTICE unattended, so the
+      # guard that decides whether a generated file is fit to commit needs its
+      # own regression coverage here — notice-autofix.yml runs on
+      # workflow_run and cannot gate a PR itself.
+      - name: Exercise generated-NOTICE validation
+        run: src/scripts/test-validate-generated-notice.sh
+
       - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
         with:
           go-version: '1.25'
@@ -193,11 +212,38 @@ jobs:
       - name: Regenerate NOTICE from the current module graph
         run: src/scripts/generate-notice.sh /tmp/NOTICE.generated
 
+      # Publish the regenerated file BEFORE the gate runs, so it is uploaded
+      # on the failing path too — that is the only path where anyone needs it.
+      # notice-autofix.yml consumes this artifact via workflow_run to commit
+      # the regeneration back onto a Dependabot branch (#5256). Uploading here
+      # rather than regenerating in the autofix workflow is deliberate: this
+      # job already runs the generator with a read-only token and no secrets,
+      # so the privileged workflow never has to execute PR-head code.
+      - name: Publish the regenerated NOTICE for the autofix workflow
+        if: github.event_name == 'pull_request'
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: notice-generated
+          path: /tmp/NOTICE.generated
+          retention-days: 1
+          if-no-files-found: error
+
+      # The PR number travels with the artifact because workflow_run does not
+      # expose it: the triggering run's event payload is not forwarded, and
+      # resolving head SHA back to a PR is an extra API round trip that can
+      # match the wrong PR when several share a head.
+      - name: Record the PR number for the autofix workflow
+        if: github.event_name == 'pull_request'
+        run: echo "${{ github.event.pull_request.number }}" > /tmp/pr-number.txt
+
+      - name: Publish the PR number for the autofix workflow
+        if: github.event_name == 'pull_request'
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: notice-pr-number
+          path: /tmp/pr-number.txt
+          retention-days: 1
+          if-no-files-found: error
+
       - name: Fail if the committed NOTICE is stale
-        run: |
-          set -euo pipefail
-          if ! diff -u NOTICE /tmp/NOTICE.generated; then
-            echo "::error::NOTICE is out of date with src/go.mod / src/go.sum. Run 'src/scripts/generate-notice.sh' locally (requires a Go toolchain) and commit the regenerated NOTICE." >&2
-            exit 1
-          fi
-          echo "NOTICE matches the current module graph."
+        run: src/scripts/check-notice-drift.sh NOTICE /tmp/NOTICE.generated

.github/workflows/image-attestation-guard.yml

@@ -16,7 +16,7 @@ name: Image Attestation Guard
 # branch-pinned, and the path filter below is what keeps it cheap.
 #
 # Release SBOMs (added in the same change that added this guard) are
-# deliberately NOT part of this workflow — release.yml's SBOM step runs
+# deliberately NOT part of this workflow — tagged-release.yml's SBOM step runs
 # against an already-published image digest and produces a standalone file
 # attached to the GitHub Release, never an in-image attestation. See
 # src/docs/releases.md, "Software bill of materials (SBOM)".