From 5b09daa134a894cad10db8b4f1015e92cf9cabf4 Mon Sep 17 00:00:00 2001 From: Jack Carter <128555021+SunsetDrifter@users.noreply.github.com> Date: Thu, 9 Jul 2026 21:23:39 +0200 Subject: [PATCH 1/6] ci: serialise image builds and stop the API-pages workflow clobbering the lockfile MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- .github/workflows/build_n_push.yml | 12 ++++++++++++ .github/workflows/generate_api_pages.yml | 21 ++++++++++++++++----- 2 files changed, 28 insertions(+), 5 deletions(-) diff --git a/.github/workflows/build_n_push.yml b/.github/workflows/build_n_push.yml index 3f5f5cdb8..340f71607 100644 --- a/.github/workflows/build_n_push.yml +++ b/.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 runs per ref so two quick merges to main can't race the :main tag +# (last push wins regardless of commit order). Queued main builds are never +# cancelled mid-push; superseded PR builds are. +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + jobs: docs_build_n_push: runs-on: ubuntu-latest diff --git a/.github/workflows/generate_api_pages.yml b/.github/workflows/generate_api_pages.yml index aa28d1a07..02ce1618d 100644 --- a/.github/workflows/generate_api_pages.yml +++ b/.github/workflows/generate_api_pages.yml @@ -43,8 +43,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,7 +61,7 @@ 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" @@ -64,6 +73,8 @@ jobs: 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 + git push From 491b29933ed7b94bc69087784d5d7b01a089c776 Mon Sep 17 00:00:00 2001 From: Jack Carter <128555021+SunsetDrifter@users.noreply.github.com> Date: Thu, 9 Jul 2026 21:23:39 +0200 Subject: [PATCH 2/6] 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. --- CLAUDE.md | 2 +- scripts/git-dates.mjs | 44 ++++++++++++++++--------------------------- 2 files changed, 17 insertions(+), 29 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index ae23b402e..9f56986c0 100644 --- a/CLAUDE.md +++ b/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) diff --git a/scripts/git-dates.mjs b/scripts/git-dates.mjs index cacd3506e..04d38bb32 100644 --- a/scripts/git-dates.mjs +++ b/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 -- ` 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 — 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 From 31ce3d3c5a371affd398e554e29f0c8271c782db Mon Sep 17 00:00:00 2001 From: Jack Carter <128555021+SunsetDrifter@users.noreply.github.com> Date: Thu, 9 Jul 2026 21:50:29 +0200 Subject: [PATCH 3/6] ci: self-heal the API-pages push when main moves mid-run MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- .github/workflows/generate_api_pages.yml | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/.github/workflows/generate_api_pages.yml b/.github/workflows/generate_api_pages.yml index 02ce1618d..d8c2d1b48 100644 --- a/.github/workflows/generate_api_pages.yml +++ b/.github/workflows/generate_api_pages.yml @@ -8,6 +8,13 @@ on: default: "refs/tags/vX.Y.Z" type: string +# 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. +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + jobs: generate_api_pages: runs-on: macos-latest @@ -77,4 +84,9 @@ jobs: # 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 }}" + # 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 From 1800dfd5a3076cbbd86602b5e3fd2ac0f04de87a Mon Sep 17 00:00:00 2001 From: Jack Carter <128555021+SunsetDrifter@users.noreply.github.com> Date: Thu, 9 Jul 2026 22:05:01 +0200 Subject: [PATCH 4/6] 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. --- .github/workflows/generate_api_pages.yml | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/.github/workflows/generate_api_pages.yml b/.github/workflows/generate_api_pages.yml index d8c2d1b48..2ca64ebaf 100644 --- a/.github/workflows/generate_api_pages.yml +++ b/.github/workflows/generate_api_pages.yml @@ -12,6 +12,8 @@ on: # 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 }} @@ -30,6 +32,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 From a19a7d82db877cd019c32218c7eee055aab55734 Mon Sep 17 00:00:00 2001 From: Brandon Hopkins Date: Wed, 22 Jul 2026 07:23:57 -0700 Subject: [PATCH 5/6] Prevent stale workflows from overwriting newer published content --- .github/workflows/build_n_push.yml | 22 ++++++++++++++- .github/workflows/generate_api_pages.yml | 34 +++++++++++++++++++++++- 2 files changed, 54 insertions(+), 2 deletions(-) diff --git a/.github/workflows/build_n_push.yml b/.github/workflows/build_n_push.yml index 340f71607..e1779f964 100644 --- a/.github/workflows/build_n_push.yml +++ b/.github/workflows/build_n_push.yml @@ -67,12 +67,32 @@ jobs: username: ${{ secrets.DOCKER_USER }} password: ${{ secrets.DOCKER_TOKEN }} + # Concurrency prevents simultaneous pushes, but GitHub does not guarantee + # run ordering. If an older run starts after a newer one, build it for + # validation but do not let it move the published tag backwards. + - name: Check whether this ref is still current + id: freshness + if: github.event_name != 'pull_request' + 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 "push=true" >> "$GITHUB_OUTPUT" + else + echo "push=false" >> "$GITHUB_OUTPUT" + echo "Skipping image push: ${GITHUB_SHA} is stale; ${GITHUB_REF} is now ${remote_sha}" + fi + - name: Docker build and push uses: docker/build-push-action@v6 with: context: . file: docker/Dockerfile - push: ${{ github.event_name != 'pull_request' }} + push: ${{ steps.freshness.outputs.push == 'true' }} # Keep a single-arch manifest (no attestation index) so the server's # `docker compose pull` stays happy. provenance: false diff --git a/.github/workflows/generate_api_pages.yml b/.github/workflows/generate_api_pages.yml index 2ca64ebaf..d720be592 100644 --- a/.github/workflows/generate_api_pages.yml +++ b/.github/workflows/generate_api_pages.yml @@ -8,6 +8,10 @@ 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 @@ -86,8 +90,36 @@ jobs: 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" From a3aa189195024ec70427fd397ee4bbc47988131e Mon Sep 17 00:00:00 2001 From: Brandon Hopkins Date: Wed, 22 Jul 2026 07:56:49 -0700 Subject: [PATCH 6/6] Coderabbit Fix --- .github/workflows/build_n_push.yml | 65 +++++++++++++++++++----------- 1 file changed, 41 insertions(+), 24 deletions(-) diff --git a/.github/workflows/build_n_push.yml b/.github/workflows/build_n_push.yml index e1779f964..2f77a6a20 100644 --- a/.github/workflows/build_n_push.yml +++ b/.github/workflows/build_n_push.yml @@ -18,9 +18,9 @@ on: permissions: contents: read -# Serialise runs per ref so two quick merges to main can't race the :main tag -# (last push wins regardless of commit order). Queued main builds are never -# cancelled mid-push; superseded PR builds are. +# 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' }} @@ -67,12 +67,29 @@ jobs: username: ${{ secrets.DOCKER_USER }} password: ${{ secrets.DOCKER_TOKEN }} - # Concurrency prevents simultaneous pushes, but GitHub does not guarantee - # run ordering. If an older run starts after a newer one, build it for - # validation but do not let it move the published tag backwards. - - name: Check whether this ref is still current - id: freshness + # 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: . + file: docker/Dockerfile + push: ${{ github.event_name != 'pull_request' }} + # Keep a single-arch manifest (no attestation index) so the server's + # `docker compose pull` stays happy. + provenance: false + 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 @@ -80,21 +97,21 @@ jobs: exit 1 fi - if [ "$GITHUB_SHA" = "$remote_sha" ]; then - echo "push=true" >> "$GITHUB_OUTPUT" - else - echo "push=false" >> "$GITHUB_OUTPUT" - echo "Skipping image push: ${GITHUB_SHA} is stale; ${GITHUB_REF} is now ${remote_sha}" + if [ "$GITHUB_SHA" != "$remote_sha" ]; then + echo "Skipping tag promotion: ${GITHUB_SHA} is stale; ${GITHUB_REF} is now ${remote_sha}" + exit 0 fi - - name: Docker build and push - uses: docker/build-push-action@v6 - with: - context: . - file: docker/Dockerfile - push: ${{ steps.freshness.outputs.push == 'true' }} - # Keep a single-arch manifest (no attestation index) so the server's - # `docker compose pull` stays happy. - provenance: false - tags: ${{ steps.meta.outputs.tags }} - labels: ${{ steps.meta.outputs.labels }} + 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"