ci: centralize version pins and lane the PR suite

.githooks/pre-commit

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# .githooks/pre-commit -- tracked, reviewable commit gate.
+#
+# Lives in the repo (unlike .git/hooks/, which is per-clone and invisible to
+# review), so a change to what the gate checks arrives as a diff.
+#
+# Enable once per clone:
+#     git config core.hooksPath .githooks
+# Emergency bypass:
+#     git commit --no-verify
+#
+# It lints only the STAGED files, so a commit is never blocked by a finding in
+# a file it does not touch. Run the whole tree yourself with:
+#     ci/linter/run-all.sh
+#
+# Exit 2 (a linter is not installed) blocks the commit on purpose: a gate that
+# skips itself when its tool is missing reports green while checking nothing.
+set -uo pipefail
+
+ROOT="$(git rev-parse --show-toplevel)"
+"$ROOT/ci/linter/run-all.sh" --staged
+rc=$?
+if [ "$rc" -eq 2 ]; then
+    echo "pre-commit: missing linters -- run ci/linter/install-linters.sh" >&2
+elif [ "$rc" -ne 0 ]; then
+    echo "pre-commit: lint failed -- fix, or commit with --no-verify" >&2
+fi
+exit "$rc"

.github/scripts/compute-versions.sh

@@ -0,0 +1,129 @@
+#!/usr/bin/env bash
+# compute-versions.sh -- resolve the latest upstream versions + their sha256 and
+# rewrite .github/versions.env in place. Used by bump.yml (weekly). Prints a
+# short summary of what it resolved to stdout, which bump.yml quotes into the
+# PR body.
+#
+# Resolves:
+#   nginx mainline (odd minor) + stable (even minor)  -- nginx.org download page
+#   Angie latest release                              -- GitHub API tag_name
+#
+# Angie is RESOLVED from the GitHub API (the only machine-readable index of
+# Angie releases) but DOWNLOADED from download.angie.software, which is what
+# ci/tools/ci-build.sh fetches. The two archives differ byte-for-byte, so the
+# digest must come from the URL we actually build from -- hashing the GitHub
+# tag archive here would pin a sha that never matches at build time.
+#
+# Run locally to preview a bump:  bash .github/scripts/compute-versions.sh
+# (it rewrites versions.env; `git diff` to review, `git checkout` to discard).
+#
+# Requires: curl, jq, sha256sum. GITHUB_TOKEN honoured for API rate limits --
+# unauthenticated api.github.com from a shared runner IP gets 403-throttled.
+set -euo pipefail
+
+VERSIONS_FILE=".github/versions.env"
+FV=".github/scripts/fetch-verify.sh"
+tmp="$(mktemp -d)"
+trap 'rm -rf "$tmp"' EXIT
+
+api() {
+  local url="$1"
+  # Same resilience budget as fetch-verify.sh: a transient blip or a stalled
+  # connection must retry, not fail the weekly bump job or hang the runner.
+  local -a opts=(-fsSL --retry 3 --retry-delay 2 --connect-timeout 30 --max-time 300)
+  if [ -n "${GITHUB_TOKEN:-}" ]; then
+    curl "${opts[@]}" -H "Authorization: Bearer $GITHUB_TOKEN" "$url"
+  else
+    curl "${opts[@]}" "$url"
+  fi
+}
+
+# sha256 of a URL (download to scratch, hash). Fails the job on download error.
+sha_of_url() {
+  local url="$1" out="$tmp/dl.$RANDOM" sha
+  # In "-" mode fetch-verify.sh sends progress text to stderr, so stdout is
+  # exactly one "SHA  OUTFILE" line. Read the first field directly rather than
+  # picking the last line out of mixed output -- an extra stdout line there
+  # would otherwise be captured as a digest with no error.
+  read -r sha _ < <(bash "$FV" "$url" - "$out")
+  # Validate the shape rather than trusting position. Moving the progress text
+  # to stderr fixes today's contamination; this catches the next one, because a
+  # non-digest silently written into versions.env would pin every future build
+  # to a value that can never match.
+  if ! printf '%s' "$sha" | grep -qE '^[0-9a-f]{64}$'; then
+    echo "::error::expected a sha256 from $FV for $url, got: ${sha:-<empty>}" >&2
+    return 1
+  fi
+  printf '%s' "$sha"
+}
+
+echo "resolving nginx versions from nginx.org..."
+dl_html="$(curl -fsSL --retry 3 --retry-delay 2 --connect-timeout 30 --max-time 300 \
+  https://nginx.org/en/download.html)"
+# nginx numbers mainline with an odd minor and stable with an even one. Take
+# the highest of each rather than trusting page order.
+NGX_MAINLINE="$(printf '%s' "$dl_html" | grep -oE 'nginx-1\.[0-9]+\.[0-9]+' \
+  | awk -F. '$2%2==1' | sort -uV | tail -1 | sed 's/nginx-//')"
+NGX_STABLE="$(printf '%s' "$dl_html" | grep -oE 'nginx-1\.[0-9]+\.[0-9]+' \
+  | awk -F. '$2%2==0' | sort -uV | tail -1 | sed 's/nginx-//')"
+[ -n "$NGX_MAINLINE" ] && [ -n "$NGX_STABLE" ] || { echo "::error::failed to resolve nginx versions" >&2; exit 1; }
+
+echo "resolving Angie latest release..."
+ANGIE_TAG="$(api 'https://api.github.com/repos/webserver-llc/angie/releases/latest' | jq -r '.tag_name')"
+[ -n "$ANGIE_TAG" ] && [ "$ANGIE_TAG" != "null" ] || { echo "::error::failed to resolve Angie" >&2; exit 1; }
+# Upstream tags releases "Angie-1.12.1"; ci-build.sh wants the bare version.
+ANGIE="${ANGIE_TAG#Angie-}"
+if ! printf '%s' "$ANGIE" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+$'; then
+  echo "::error::unexpected Angie tag format: $ANGIE_TAG" >&2
+  exit 1
+fi
+
+echo "hashing archives..."
+NGX_MAINLINE_SHA="$(sha_of_url "https://nginx.org/download/nginx-${NGX_MAINLINE}.tar.gz")"
+NGX_STABLE_SHA="$(sha_of_url "https://nginx.org/download/nginx-${NGX_STABLE}.tar.gz")"
+ANGIE_SHA="$(sha_of_url "https://download.angie.software/files/angie-${ANGIE}.tar.gz")"
+
+cat > "$VERSIONS_FILE" <<EOF
+# Central version + sha256 pins for all CI workflows.
+#
+# SINGLE SOURCE OF TRUTH. Every workflow loads this file into \$GITHUB_ENV as its
+# first step (via .github/scripts/load-versions.sh); the weekly bump.yml job
+# rewrites it and opens a PR. Tarballs are pinned by version string (release
+# archives are immutable) AND verified against the sha256 recorded here, so a
+# compromised or changed upstream archive fails the build instead of being
+# compiled.
+#
+# Version and digest live on adjacent lines on purpose: they are bumped by one
+# writer (compute-versions.sh) in one file, so a version can no longer move
+# while its digest stays behind.
+#
+# Regenerate with .github/scripts/compute-versions.sh (bump.yml runs it weekly).
+# Keep KEY=value, no spaces, no quotes -- this file is both \`source\`d by
+# ci/tools/ci-build.sh and \`cat\`d into \$GITHUB_ENV.
+
+# nginx mainline (odd minor) -- the default build everywhere; also the
+# ci-deep "mainline" matrix cell.
+NGINX_MAINLINE=${NGX_MAINLINE}
+NGINX_MAINLINE_SHA256=${NGX_MAINLINE_SHA}
+
+# nginx stable (even minor) -- ci-deep "stable" matrix cell only.
+NGINX_STABLE=${NGX_STABLE}
+NGINX_STABLE_SHA256=${NGX_STABLE_SHA}
+
+# nginx version used by every single-version job (build-test, asan, valgrind,
+# codeql, fuzzing, security-scanners, ci-deep memcheck). Tracks mainline.
+NGINX_VERSION=${NGX_MAINLINE}
+NGINX_VERSION_SHA256=${NGX_MAINLINE_SHA}
+
+# Angie (webserver-llc) -- ci-deep "angie" matrix cell. Pinned to the tarball
+# from download.angie.software, NOT the GitHub tag archive: different bytes,
+# so this digest is not interchangeable with a github.com/webserver-llc one.
+# ANGIE_VERSION is the bare version; the upstream release tag is "Angie-<ver>".
+ANGIE_VERSION=${ANGIE}
+ANGIE_SHA256=${ANGIE_SHA}
+EOF
+
+echo "----- resolved -----"
+echo "nginx mainline: ${NGX_MAINLINE}"
+echo "nginx stable:   ${NGX_STABLE}"
+echo "angie:          ${ANGIE}"

.github/scripts/fetch-verify.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# fetch-verify.sh URL EXPECTED_SHA256 OUTFILE
+#
+# Download URL to OUTFILE and verify its sha256 against EXPECTED_SHA256.
+# On mismatch: print the actual sha and exit 1 (fails the CI job — a changed
+# or tampered upstream archive never reaches the build).
+#
+# Pass EXPECTED_SHA256="-" to skip verification and just print the computed
+# sha (used by bump.yml to harvest fresh hashes for a version bump).
+#
+# If OUTFILE already exists with the right sha (warm actions/cache hit) the
+# download is skipped — the sha check still runs, so a poisoned cache is caught.
+set -euo pipefail
+
+url="${1:?usage: fetch-verify.sh URL SHA256 OUTFILE}"
+want="${2:?missing expected sha256}"
+out="${3:?missing output path}"
+
+sha_of() { sha256sum "$1" | cut -d' ' -f1; }
+
+if [ -f "$out" ] && [ "$want" != "-" ] && [ "$(sha_of "$out")" = "$want" ]; then
+  echo "cache hit (sha ok): $out"
+  exit 0
+fi
+
+# stderr, not stdout: in "-" mode stdout must carry ONLY the final
+# "$got  $out" line, which compute-versions.sh reads as the digest.
+echo "downloading: $url" >&2
+# -f: fail on HTTP errors; -S: show errors; -L: follow redirects; retries.
+# --connect-timeout/--max-time: a stalled upstream must not hold a runner open.
+curl -fSL --retry 3 --retry-delay 2 \
+  --connect-timeout 30 --max-time 300 -o "$out" "$url"
+
+got="$(sha_of "$out")"
+if [ "$want" = "-" ]; then
+  echo "$got  $out"
+  exit 0
+fi
+
+if [ "$got" != "$want" ]; then
+  echo "::error::sha256 MISMATCH for $url" >&2
+  echo "  expected: $want" >&2
+  echo "  actual:   $got" >&2
+  exit 1
+fi
+echo "sha256 verified: $out"

.github/scripts/load-versions.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# load-versions.sh — export every pin from .github/versions.env into the
+# workflow environment. Run as the first step of every CI job:
+#
+#   - run: bash .github/scripts/load-versions.sh
+#
+# Skips comments/blanks; validates each line is KEY=value so a malformed
+# versions.env fails loudly instead of injecting garbage into $GITHUB_ENV.
+set -euo pipefail
+
+f=".github/versions.env"
+[ -f "$f" ] || { echo "::error::$f not found" >&2; exit 1; }
+# Outside a GitHub Actions step $GITHUB_ENV is unset, and set -u turns that
+# into a bare "unbound variable" -- give anyone running this by hand a
+# message that says what actually went wrong.
+[ -n "${GITHUB_ENV:-}" ] || { echo "::error::GITHUB_ENV unset -- run this inside a GitHub Actions step" >&2; exit 1; }
+
+while IFS= read -r line || [ -n "$line" ]; do
+  case "$line" in
+    ''|\#*) continue ;;
+  esac
+  if ! printf '%s' "$line" | grep -qE '^[A-Za-z_][A-Za-z0-9_]*='; then
+    echo "::error::malformed line in $f: $line" >&2
+    exit 1
+  fi
+  echo "$line" >> "$GITHUB_ENV"
+  echo "loaded: ${line%%=*}"
+done < "$f"

.github/versions.env

@@ -0,0 +1,37 @@
+# Central version + sha256 pins for all CI workflows.
+#
+# SINGLE SOURCE OF TRUTH. Every workflow loads this file into $GITHUB_ENV as its
+# first step (via .github/scripts/load-versions.sh); the weekly bump.yml job
+# rewrites it and opens a PR. Tarballs are pinned by version string (release
+# archives are immutable) AND verified against the sha256 recorded here, so a
+# compromised or changed upstream archive fails the build instead of being
+# compiled.
+#
+# Version and digest live on adjacent lines on purpose: they are bumped by one
+# writer (compute-versions.sh) in one file, so a version can no longer move
+# while its digest stays behind.
+#
+# Regenerate with .github/scripts/compute-versions.sh (bump.yml runs it weekly).
+# Keep KEY=value, no spaces, no quotes -- this file is both `source`d by
+# ci/tools/ci-build.sh and `cat`d into $GITHUB_ENV.
+
+# nginx mainline (odd minor) -- the default build everywhere; also the
+# ci-deep "mainline" matrix cell.
+NGINX_MAINLINE=1.31.3
+NGINX_MAINLINE_SHA256=a7657c50811c2d92d9895395e8b873ef60398142c4db21eb647811c38f6dd525
+
+# nginx stable (even minor) -- ci-deep "stable" matrix cell only.
+NGINX_STABLE=1.30.4
+NGINX_STABLE_SHA256=4261dc90e9e47c1c4041276e9aaa3d48ebe2e664f728e14fa95ae6c67d57a08b
+
+# nginx version used by every single-version job (build-test, asan, valgrind,
+# codeql, fuzzing, security-scanners, ci-deep memcheck). Tracks mainline.
+NGINX_VERSION=1.31.3
+NGINX_VERSION_SHA256=a7657c50811c2d92d9895395e8b873ef60398142c4db21eb647811c38f6dd525
+
+# Angie (webserver-llc) -- ci-deep "angie" matrix cell. Pinned to the tarball
+# from download.angie.software, NOT the GitHub tag archive: different bytes,
+# so this digest is not interchangeable with a github.com/webserver-llc one.
+# ANGIE_VERSION is the bare version; the upstream release tag is "Angie-<ver>".
+ANGIE_VERSION=1.12.1
+ANGIE_SHA256=5f4f203be2aca6fe20770b489c720e46e51d337e521065e7e472b61e24e3d2f5

.github/workflows/asan.yml

@@ -20,26 +20,12 @@
 
 env:
   FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
-  NGINX_VERSION: "1.31.2"
 
 on:
-  push:
-    branches: [main]
-    paths:
-      - "src/**"
-      - "ci/t/**"
-      - "ci/tools/ci-build.sh"
-      - "ci/tools/soak.sh"
-      - ".github/workflows/asan.yml"
-  pull_request:
-    branches: [main]
-    paths:
-      - "src/**"
-      - "ci/t/**"
-      - "ci/tools/ci-build.sh"
-      - "ci/tools/soak.sh"
-      - ".github/workflows/asan.yml"
-  workflow_dispatch: {}
+  # Triggered by ci.yml, which lanes the PR suite so peak runner use stays
+  # bounded. No push/pull_request trigger here on purpose: two entry points
+  # would run this twice per PR and defeat the laning.
+  workflow_call: {}
 
 concurrency:
   group: asan-${{ github.workflow }}-${{ github.ref }}
@@ -51,7 +37,7 @@
 jobs:
   asan-soak:
     name: ASan/UBSan soak (60s)
     runs-on: ${{ github.event.pull_request.head.repo.fork && 'ubuntu-latest' || fromJSON('["self-hosted","builder02","lxc"]') }}
     timeout-minutes: 45
     steps:
       - name: Checkout module
@@ -59,6 +45,9 @@
         with:
           persist-credentials: false
 
+      - name: Load version pins
+        run: bash .github/scripts/load-versions.sh
+
       - name: Install dependencies
         run: |
           sudo apt-get update

.github/workflows/build-test.yml

@@ -11,17 +11,18 @@
 
 env:
   FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
-  NGINX_VERSION: "1.31.2"
 
 on:
-  push:
-    branches: [main]
-  pull_request:
-    branches: [main]
-  workflow_dispatch: {}
+  # Triggered by ci.yml, which lanes the PR suite so peak runner use stays
+  # bounded. No push/pull_request trigger here on purpose: two entry points
+  # would run this twice per PR and defeat the laning.
+  workflow_call: {}
 
 concurrency:
-  group: ci-${{ github.workflow }}-${{ github.ref }}
+  # Prefix must be unique per workflow. As a workflow_call member this inherits
+  # the caller's github.workflow/github.ref, so a group string matching ci.yml's
+  # would cancel the caller rather than a stale copy of this workflow.
+  group: build-test-${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
 permissions:
@@ -30,7 +31,7 @@
 jobs:
   validation:
     name: Validation
     runs-on: ${{ github.event.pull_request.head.repo.fork && 'ubuntu-latest' || fromJSON('["self-hosted","builder02","lxc"]') }}
     timeout-minutes: 15
     steps:
       - name: Checkout
@@ -85,7 +86,7 @@
 
   build:
     name: Build
     runs-on: ${{ github.event.pull_request.head.repo.fork && 'ubuntu-latest' || fromJSON('["self-hosted","builder02","lxc"]') }}
     timeout-minutes: 30
     steps:
       - name: Checkout
@@ -93,6 +94,9 @@
         with:
           persist-credentials: false
 
+      - name: Load version pins
+        run: bash .github/scripts/load-versions.sh
+
       - name: Install build dependencies
         run: |
           sudo apt-get update
@@ -201,8 +205,8 @@
       - name: Strict module compile
         run: |
           build=".build/nginx-${NGINX_VERSION}-debug"
           cflags=$(awk '/^CFLAGS[[:space:]]*=/{sub(/^CFLAGS[[:space:]]*=[[:space:]]*/,""); print; exit}' "$build/objs/Makefile")
           incs=$(awk '/^ALL_INCS[[:space:]]*=/{found=1} found{line=$0; sub(/^ALL_INCS[[:space:]]*=[[:space:]]*/,"",line); continued=(line ~ /\\$/); gsub(/\\$/, "", line); printf "%s ", line; if (!continued) exit}' "$build/objs/Makefile")
           # cflags and incs are compiler flag lists and must word-split.
           # shellcheck disable=SC2086
           (
@@ -221,7 +225,7 @@
 
   test-nginx:
     name: Test::Nginx
     runs-on: ${{ github.event.pull_request.head.repo.fork && 'ubuntu-latest' || fromJSON('["self-hosted","builder02","lxc"]') }}
     timeout-minutes: 20
     steps:
       - name: Checkout
@@ -229,6 +233,9 @@
         with:
           persist-credentials: false
 
+      - name: Load version pins
+        run: bash .github/scripts/load-versions.sh
+
       - name: Install dependencies
         run: |
           sudo apt-get update
@@ -256,7 +263,7 @@
       - name: Run ci/t/
         env:
           TEST_NGINX_BINARY: ${{ github.workspace }}/.build/nginx-${{ env.NGINX_VERSION }}-debug/objs/nginx
           TEST_NGINX_LOAD_MODULES: ${{ github.workspace }}/.build/nginx-${{ env.NGINX_VERSION }}-debug/objs/ngx_http_skel_module.so
           # Test::Nginx::Socket's client read timeout defaults to ~2s. That is far
           # too tight on the shared builder02 LXC: under normal build-host load a
           # live request can take >2s to first byte, and a whole file then fails as
@@ -276,7 +283,7 @@
   # the renamed module actually builds.
   rename-smoke:
     name: Rename smoke
     runs-on: ${{ github.event.pull_request.head.repo.fork && 'ubuntu-latest' || fromJSON('["self-hosted","builder02","lxc"]') }}
     timeout-minutes: 30
     steps:
       - name: Checkout
@@ -284,6 +291,9 @@
         with:
           persist-credentials: false
 
+      - name: Load version pins
+        run: bash .github/scripts/load-versions.sh
+
       - name: Install build dependencies
         run: |
           sudo apt-get update
@@ -345,6 +355,9 @@
         with:
           persist-credentials: false
 
+      - name: Load version pins
+        run: bash .github/scripts/load-versions.sh
+
       - name: Install dependencies
         run: |
           sudo apt-get update