sendnrw/netbird-docs
2
0
Fork 0
mirror of https://github.com/netbirdio/docs.git synced 2026-08-24 16:51:26 +02:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
* 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>
This commit is contained in:
Jack Carter
2026-07-22 17:06:58 +02:00
committed by GitHub
parent 0bbf69dad0
commit 2a02ce7edd
4 changed files with 141 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

53
.github/workflows/build_n_push.yml vendored
View File

@@ -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"

79
.github/workflows/generate_api_pages.yml vendored
View File

@@ -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