ci: harden the build and API-pages workflows (#843)

* ci: serialise image builds and stop the API-pages workflow clobbering the lockfile

build_n_push: add a per-ref concurrency group so two quick merges to main can't race the :main tag (last push wins regardless of commit order, and the server auto-pulls :main); add permissions: contents: read; validate .dockerignore and package.json changes in the PR path filter.

generate_api_pages: pin Node 20 and switch npm install -> npm ci so the run can never rewrite the now-tracked package-lock.json with a divergent macOS-resolved tree; stage only src/pages/ipa/resources instead of git add -A; drop --force from the push — a force-push from this workflow would silently rewrite main and destroy any PR merged since its checkout.

* chore: warn when per-page dates are skipped; drop dead per-file git lookup

buildGitDateMap now logs a warning when it emits no dates (git missing or shallow clone) instead of silently blanking every page's Updated line and the sitemap lastmod entries; document the squash-merge assumption behind the --name-only walk. Remove the unused getGitLastModified. Note in CLAUDE.md that npm run start warns under output: 'standalone'. Gen output verified byte-identical.

* ci: self-heal the API-pages push when main moves mid-run

Rebase the single generated-files commit onto the moved branch before pushing, so a PR merged during the multi-minute run no longer rejects the push (the failure --force was presumably papering over). A genuine conflict — a concurrent edit of the generated files themselves — still fails the run loudly with main untouched. Also serialise dispatches with a concurrency group: run history shows several same-day dispatches, and overlapping runs regenerate the same files.

Sandbox-tested against a bare repo: plain push rejected on race; rebase+push lands with both commits intact; true conflict exits 1 leaving the branch tip untouched.

* ci: sync to branch tip before regenerating API pages

A run queued behind another checks out the commit pinned at its dispatch time; regenerating against that stale base means the pre-push rebase replays a snapshot diff, and a file the newer spec removed can silently survive from the prior run. Fetch + reset to the branch tip before generating so the diff is computed against reality. Also note the latest-dispatched-vs-newest-tag caveat on the concurrency comment.

Sandbox-proven: with the old order a removed-in-newer-spec file survives the rebase replay; with sync-first it is gone.

* Prevent stale workflows from overwriting newer published content

* Coderabbit Fix

---------

Co-authored-by: Brandon Hopkins <brandon@techhut.tv>

.github/workflows/build_n_push.yml

@@ -8,11 +8,23 @@ on:
   pull_request:
     paths:
       - 'docker/**'
+      - '.dockerignore'
       - '.github/workflows/build_n_push.yml'
       - 'next.config.mjs'
+      - 'package.json'
       - 'package-lock.json'
   workflow_dispatch:
 
+permissions:
+  contents: read
+
+# Serialise non-PR runs while allowing superseded PR validation to be canceled.
+# Builds publish only an immutable SHA tag; the mutable ref tag is promoted
+# separately after the build and a final ref check.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
 jobs:
   docs_build_n_push:
     runs-on: ubuntu-latest
@@ -55,7 +67,10 @@ jobs:
           username: ${{ secrets.DOCKER_USER }}
           password: ${{ secrets.DOCKER_TOKEN }}
 
-      - name: Docker build and push
+      # Non-PR runs publish an immutable image first. A canceled or stale run
+      # can leave this tag behind, but it cannot change :main (or another
+      # mutable ref tag).
+      - name: Docker build and publish immutable image
         uses: docker/build-push-action@v6
         with:
           context: .
@@ -64,5 +79,39 @@ jobs:
           # Keep a single-arch manifest (no attestation index) so the server's
           # `docker compose pull` stays happy.
           provenance: false
-          tags: ${{ steps.meta.outputs.tags }}
+          tags: netbirdio/docs.netbird.io:${{ github.sha }}
           labels: ${{ steps.meta.outputs.labels }}
+
+      # Promotion is a single remote manifest-tag update after the expensive
+      # build. Combined with serialisation and the final ref comparison, an
+      # older run cannot replace the mutable tag after a newer run publishes.
+      - name: Promote current image to ref tag
+        if: github.event_name != 'pull_request'
+        env:
+          SOURCE_IMAGE: netbirdio/docs.netbird.io:${{ github.sha }}
+          TARGET_TAGS: ${{ steps.meta.outputs.tags }}
+        run: |
+          remote_sha="$(git ls-remote origin "${GITHUB_REF}" | awk 'NR == 1 { print $1 }')"
+          if [ -z "$remote_sha" ]; then
+            echo "Could not resolve ${GITHUB_REF} on origin" >&2
+            exit 1
+          fi
+
+          if [ "$GITHUB_SHA" != "$remote_sha" ]; then
+            echo "Skipping tag promotion: ${GITHUB_SHA} is stale; ${GITHUB_REF} is now ${remote_sha}"
+            exit 0
+          fi
+
+          if [ -z "$TARGET_TAGS" ]; then
+            echo "Docker metadata produced no target tags" >&2
+            exit 1
+          fi
+
+          while IFS= read -r target_tag; do
+            if [ -n "$target_tag" ]; then
+              docker buildx imagetools create \
+                --prefer-index=false \
+                --tag "$target_tag" \
+                "$SOURCE_IMAGE"
+            fi
+          done <<< "$TARGET_TAGS"

.github/workflows/generate_api_pages.yml

@@ -8,6 +8,19 @@ on:
         default: "refs/tags/vX.Y.Z"
         type: string
 
+permissions:
+  actions: read
+  contents: read
+
+# One run at a time: overlapping dispatches (several release tags in a day
+# happen — see run history) regenerate the same files and would collide. A
+# queued run superseded by a newer dispatch is fine: every run regenerates the
+# whole directory from its own tag, so the latest dispatch is the end state.
+# NB "latest dispatched", not "newest tag" — re-dispatching an older tag after
+# a newer one regresses the pages to the older spec.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+
 jobs:
   generate_api_pages:
     runs-on: macos-latest
@@ -23,6 +36,16 @@ jobs:
         with:
           token: ${{ secrets.DEV_GITHUB_TOKEN }}
 
+      # A run queued behind another (see concurrency above) checks out the
+      # commit pinned at its dispatch time, not the branch's current tip.
+      # Sync before generating so the diff is computed against reality —
+      # otherwise the pre-push rebase replays a stale-base snapshot, and a
+      # file the newer spec removed could silently survive from the prior run.
+      - name: Sync to branch tip
+        run: |
+          git fetch origin "${GITHUB_REF_NAME}"
+          git reset --hard "origin/${GITHUB_REF_NAME}"
+
       - name: Create directory
         run: mkdir -p generator/openapi
 
@@ -43,8 +66,17 @@ jobs:
       - name: Remove old generated files
         run: rm -rf src/pages/ipa/resources/*
 
-      - name: Npm install
-        run: npm install
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      # npm ci: this workflow never changes dependencies, so install exactly
+      # the committed lockfile and never mutate it (macos-latest's npm can
+      # differ from the one that generated package-lock.json).
+      - name: Install dependencies
+        run: npm ci
 
       - name: Generate api pages for netbird main openapi definition
         run: npx ts-node generator/index.ts gen --input generator/openapi/expanded.yml --output src/pages/ipa/resources
@@ -52,18 +84,53 @@ jobs:
       - name: Check git diff and untracked files
         id: git_diff
         run: |
-          if [ -n "$(git status --porcelain)" ]; then
+          if [ -n "$(git status --porcelain src/pages/ipa/resources)" ]; then
             echo "changed=true" >> "$GITHUB_OUTPUT"
           else
             echo "changed=false" >> "$GITHUB_OUTPUT"
           fi
 
-      - name: Commit and push changes
+      # Concurrency serialises runs but does not guarantee dispatch order. A
+      # delayed older run must not overwrite output from a newer dispatch.
+      - name: Check whether this is the latest dispatch
+        id: freshness
         if: steps.git_diff.outputs.changed == 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          latest_run_id="$(
+            curl --fail --silent --show-error \
+              -H "Accept: application/vnd.github+json" \
+              -H "Authorization: Bearer ${GH_TOKEN}" \
+              -H "X-GitHub-Api-Version: 2022-11-28" \
+              --get \
+              --data-urlencode "event=workflow_dispatch" \
+              --data-urlencode "branch=${GITHUB_REF_NAME}" \
+              --data-urlencode "per_page=1" \
+              "https://api.github.com/repos/${GITHUB_REPOSITORY}/actions/workflows/generate_api_pages.yml/runs" \
+            | python3 -c 'import json, sys; print(json.load(sys.stdin)["workflow_runs"][0]["id"])'
+          )"
+
+          if [ "$GITHUB_RUN_ID" = "$latest_run_id" ]; then
+            echo "push=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "push=false" >> "$GITHUB_OUTPUT"
+            echo "Skipping generated-page commit: run ${GITHUB_RUN_ID} was superseded by ${latest_run_id}"
+          fi
+
+      - name: Commit and push changes
+        if: steps.git_diff.outputs.changed == 'true' && steps.freshness.outputs.push == 'true'
         run: |
           git config --global user.email "dev@netbird.io"
           git config --global user.name "netbirddev"
 
-          git add -A
+          # Stage only the regenerated API pages — never sweep up incidental
+          # changes like a rewritten package-lock.json.
+          git add src/pages/ipa/resources
           git commit -m "Update API pages with v${{ steps.semver_parser.outputs.fullversion }}"
-          git push --force
+          # The run takes minutes; if the branch moved meanwhile, replay our
+          # single generated-files commit on top instead of failing the push.
+          # A conflict is only possible against a concurrent edit of the
+          # generated files themselves and fails the run loudly.
+          git pull --rebase origin "${GITHUB_REF_NAME}"
+          git push

CLAUDE.md

@@ -16,7 +16,7 @@ There is no test suite in this project. Validate changes with `npm run build`.
 npm install              # Install dependencies
 npm run dev              # Start dev server (also runs gen:llm, gen:edit-routes, gen:last-updated, gen:sitemap)
 npm run build            # Production build (also runs gen:llm, gen:edit-routes, gen:last-updated, gen:sitemap)
-npm run start            # Serve the production build
+npm run start            # Serve the production build (warns under `output: 'standalone'` — safe to ignore locally; prod runs `node server.js` from `.next/standalone`)
 npm run lint             # ESLint (next/core-web-vitals) on src/
 npm run gen              # Regenerate API docs from NetBird OpenAPI spec
 npm run gen:llm          # Regenerate LLM-friendly markdown (auto-runs with dev/build)

scripts/git-dates.mjs

@@ -1,25 +1,5 @@
 import { execSync } from 'child_process'
 
-/**
- * Get the last modified date for a file from git history.
- * Returns YYYY-MM-DD or null if the file is not tracked / git is unavailable.
- *
- * Prefer buildGitDateMap() when you need dates for many files — this spawns a
- * git process per call, which is ~300x slower across a full page tree.
- */
-export function getGitLastModified(filePath) {
-  try {
-    const date = execSync(`git log -1 --format=%cI -- "${filePath}"`, {
-      encoding: 'utf-8',
-      stdio: ['pipe', 'pipe', 'ignore'],
-    }).trim()
-
-    return date ? date.split('T')[0] : null
-  } catch {
-    return null
-  }
-}
-
 let _dateMapCache
 
 /**
@@ -31,22 +11,28 @@ let _dateMapCache
  * most recent commit — the same value `git log -1 -- <path>` returns. Paths are
  * repo-relative with forward slashes, matching path.relative(repoRoot, file).
  *
- * Returns an empty map if git is unavailable (e.g. inside the Docker image,
- * which has no git binary) or the checkout is shallow; callers then fall back
- * to no date, exactly as the per-file getGitLastModified() did.
+ * Note: `git log --name-only` lists no files for merge commits, so content
+ * introduced by a conflict-resolving merge is attributed to its source
+ * commits. That matches this repo's squash-merge workflow; revisit with
+ * `--diff-merges=first-parent` if long-lived branches are ever merged.
+ *
+ * Returns an empty map — with a warning, since every page then renders without
+ * an "Updated" date and the sitemap loses <lastmod> — when git is unavailable
+ * or the checkout is shallow (e.g. actions/checkout without fetch-depth: 0,
+ * where git log would attribute one identical, wrong date to every file).
  */
 export function buildGitDateMap() {
   if (_dateMapCache) return _dateMapCache
   const map = new Map()
   try {
-    // On a shallow clone (e.g. actions/checkout without fetch-depth: 0) git log
-    // only sees the fetched commits, so every file would report the same wrong
-    // date. Emit no dates rather than wrong ones.
     const shallow = execSync('git rev-parse --is-shallow-repository', {
       encoding: 'utf-8',
       stdio: ['pipe', 'pipe', 'ignore'],
     }).trim()
     if (shallow === 'true') {
+      console.warn(
+        '[git-dates] shallow clone detected — emitting no per-page dates (fetch full history to enable them)'
+      )
       _dateMapCache = map
       return map
     }
@@ -68,8 +54,10 @@ export function buildGitDateMap() {
       }
       if (currentDate && !map.has(line)) map.set(line, currentDate)
     }
-  } catch {
-    // git unavailable — return the empty map, callers fall back to null.
+  } catch (err) {
+    console.warn(
+      `[git-dates] could not read git history — emitting no per-page dates: ${err.message}`
+    )
   }
   _dateMapCache = map
   return map