security: hash-lock the docs build toolchain

This commit is contained in:
inference-admin committed 2026-11-19 23:55:59 +00:00
1 parent 279886fd83
commit 20477174e5
5 files changed
+642 -32

No files matched your search

+14 -11
View File
@@ -2,9 +2,10 @@
# Build the member-readable documentation site from this repository.
#
# The repository is the single source of truth. This script:
# 1. checks the build venv against publishing/requirements.txt and
# 1. checks the build venv against publishing/requirements.in and
# self-heals anything missing or off-version (fast local no-op when
# current — no network, a few `pip show` calls);
# current — no network, a few `pip show` calls); installs from the
# hash-locked publishing/requirements.txt with --require-hashes);
# 2. checks that every plugin mkdocs.yml configures is pinned in
# requirements.txt (fails loudly naming any that is not);
# 3. stages a mirror of the documents into .site-src/ (generated, gitignored),
@@ -27,8 +28,8 @@
# # poller's pre-deploy check; also
# # cold-bootstraps the venv if absent)
#
# In CI (Woodpecker), install the toolchain and run MkDocs directly:
# pip install -r publishing/requirements.txt && mkdocs build --strict
# In CI (Woodpecker), install the hash-locked toolchain and run MkDocs directly:
# pip install --require-hashes -r publishing/requirements.txt && mkdocs build --strict
set -euo pipefail
@@ -41,7 +42,8 @@ if [ "${1:-}" = "--check-only" ]; then
shift
fi
VENV="${1:-$REPO_DIR/.venv-docs}"
REQUIREMENTS="$REPO_DIR/publishing/requirements.txt"
REQUIREMENTS_IN="$REPO_DIR/publishing/requirements.in"
REQUIREMENTS_LOCK="$REPO_DIR/publishing/requirements.txt"
# --- gate 1: pinned toolchain ----------------------------------------------
# Compare the venv against the pinned requirements; install anything missing
@@ -60,10 +62,10 @@ check_toolchain() {
if [ -z "$have" ] || { [ -n "$want" ] && [ "$have" != "$want" ]; }; then
missing="$missing ${pkg}(${want:-any}; have: ${have:-none})"
fi
done < "$REQUIREMENTS"
done < "$REQUIREMENTS_IN"
if [ -n "$missing" ]; then
echo "Self-heal: installing pinned toolchain package(s):$missing"
"$VENV/bin/pip" install -r "$REQUIREMENTS" || {
"$VENV/bin/pip" install --require-hashes -r "$REQUIREMENTS_LOCK" || {
echo "FATAL: could not install the pinned toolchain into $VENV (network? disk?)" >&2
exit 1
}
@@ -116,20 +118,20 @@ PY
while IFS= read -r req; do
case "$req" in ''|\#*) continue ;; esac
pinned="$pinned ${req%%[=<>!~]*}"
done < "$REQUIREMENTS"
done < "$REQUIREMENTS_IN"
for plug in $names; do
ok=0
for cand in "$plug" "mkdocs-$plug"; do
case " $pinned " in *" $cand "*) ok=1 ;; esac
done
if [ "$ok" = 0 ]; then
echo "FATAL: plugin '$plug' is configured in mkdocs.yml but NOT pinned in publishing/requirements.txt." >&2
echo "FATAL: plugin '$plug' is configured in mkdocs.yml but NOT pinned in publishing/requirements.in." >&2
echo " Add '<package>==<version>' there (usually mkdocs-$plug) so every build environment" >&2
echo " installs the same toolchain, then reinstall it in the build venv." >&2
return 1
fi
done
echo "plugin check OK: configured plugin(s) $(echo "$names" | tr '\n' ' ') covered by requirements.txt"
echo "plugin check OK: configured plugin(s) $(echo "$names" | tr '\n' ' ') covered by requirements.in"
return 0
}
@@ -142,7 +144,7 @@ check_toolchain
check_plugins
if [ "$CHECK_ONLY" = 1 ]; then
echo "check OK: $VENV satisfies publishing/requirements.txt and every configured plugin"
echo "check OK: $VENV satisfies publishing/requirements.in and every configured plugin"
exit 0
fi
@@ -164,6 +166,7 @@ tar cf - \
--exclude='mkdocs.yml' \
--exclude='.gitignore' \
--exclude='requirements.txt' \
--exclude='requirements.in' \
. | tar xf - -C "$SITE_SRC"
# A file that must sit at the site root (crawler rules), not under publishing/.