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"