Install CI's Python tools from a hash-pinned lock file

.github/workflows/ci.yml

@@ -18,10 +18,6 @@ concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
-env:
-  PLATFORMIO_VERSION: "6.1.19"
-  GCOVR_VERSION: "8.6"
-
 jobs:
   invariants:
     name: invariants
@@ -65,10 +61,10 @@ jobs:
         uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
         with:
           path: ~/.platformio
-          key: pio-host-${{ runner.os }}-${{ env.PLATFORMIO_VERSION }}-${{ hashFiles('platformio.ini') }}
+          key: pio-host-${{ runner.os }}-${{ hashFiles('tools/requirements-ci.txt', 'platformio.ini') }}
 
-      - name: Install PlatformIO Core
-        run: pip install "platformio==${PLATFORMIO_VERSION}"
+      - name: Install the pinned Python tools
+        run: pip install --require-hashes -r tools/requirements-ci.txt
 
       # Host tests build only src/core (invariant 1).
       - name: Run the host tests
@@ -90,10 +86,10 @@ jobs:
         uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
         with:
           path: ~/.platformio
-          key: pio-host-${{ runner.os }}-${{ env.PLATFORMIO_VERSION }}-${{ hashFiles('platformio.ini') }}
+          key: pio-host-${{ runner.os }}-${{ hashFiles('tools/requirements-ci.txt', 'platformio.ini') }}
 
-      - name: Install PlatformIO Core
-        run: pip install "platformio==${PLATFORMIO_VERSION}"
+      - name: Install the pinned Python tools
+        run: pip install --require-hashes -r tools/requirements-ci.txt
 
       # -fno-sanitize-recover is set in platformio.ini, so a finding aborts the
       # run and fails the lane rather than printing and carrying on.
@@ -114,10 +110,10 @@ jobs:
         uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
         with:
           path: ~/.platformio
-          key: pio-host-${{ runner.os }}-${{ env.PLATFORMIO_VERSION }}-${{ hashFiles('platformio.ini') }}
+          key: pio-host-${{ runner.os }}-${{ hashFiles('tools/requirements-ci.txt', 'platformio.ini') }}
 
-      - name: Install PlatformIO Core and gcovr
-        run: pip install "platformio==${PLATFORMIO_VERSION}" "gcovr==${GCOVR_VERSION}"
+      - name: Install the pinned Python tools
+        run: pip install --require-hashes -r tools/requirements-ci.txt
 
       # pipefail because a pipe otherwise reports tee's exit code, which is
       # always 0, and the floor check would pass while failing.
@@ -141,10 +137,10 @@ jobs:
         uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
         with:
           path: ~/.platformio
-          key: pio-host-${{ runner.os }}-${{ env.PLATFORMIO_VERSION }}-${{ hashFiles('platformio.ini') }}
+          key: pio-host-${{ runner.os }}-${{ hashFiles('tools/requirements-ci.txt', 'platformio.ini') }}
 
-      - name: Install PlatformIO Core
-        run: pip install "platformio==${PLATFORMIO_VERSION}"
+      - name: Install the pinned Python tools
+        run: pip install --require-hashes -r tools/requirements-ci.txt
 
       - name: Install clang-tidy
         run: sudo apt-get install -y -qq clang-tidy-18
@@ -188,10 +184,10 @@ jobs:
         uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
         with:
           path: ~/.platformio
-          key: pio-firmware-${{ runner.os }}-${{ env.PLATFORMIO_VERSION }}-${{ steps.toolchain.outputs.key }}
+          key: pio-firmware-${{ runner.os }}-${{ hashFiles('tools/requirements-ci.txt') }}-${{ steps.toolchain.outputs.key }}
 
-      - name: Install PlatformIO Core
-        run: pip install "platformio==${PLATFORMIO_VERSION}"
+      - name: Install the pinned Python tools
+        run: pip install --require-hashes -r tools/requirements-ci.txt
 
       # pipefail so a failed build fails here, with the compiler's message,
       # rather than further down where the footprint step finds no RAM line.
@@ -241,16 +237,16 @@ jobs:
         uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
         with:
           path: ~/.platformio
-          key: pio-firmware-${{ runner.os }}-${{ env.PLATFORMIO_VERSION }}-${{ steps.toolchain.outputs.key }}
+          key: pio-firmware-${{ runner.os }}-${{ hashFiles('tools/requirements-ci.txt') }}-${{ steps.toolchain.outputs.key }}
 
       - name: Cache QEMU
         uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
         with:
           path: ~/qemu-esp
           key: qemu-${{ runner.os }}-${{ hashFiles('tools/run-qemu.sh') }}
 
-      - name: Install PlatformIO Core
-        run: pip install "platformio==${PLATFORMIO_VERSION}"
+      - name: Install the pinned Python tools
+        run: pip install --require-hashes -r tools/requirements-ci.txt
 
       - name: Install QEMU
         run: bash tools/run-qemu.sh --install-only

CONTRIBUTING.md

@@ -70,6 +70,11 @@ pio test -e native-sanitize
 into a shared directory and each suite would otherwise erase the last one's
 coverage data. It takes a few minutes.
 
+CI installs its Python tools from `tools/requirements-ci.txt`, which pins every
+package and its dependencies by hash. If you change a version, edit
+`tools/requirements-ci.in` and regenerate the lock with the command in its
+header; the versions are chosen there and nowhere else.
+
 For firmware, configuration, or platform changes, also build the affected
 environment. Before release, build all four firmware environments:
 

tools/requirements-ci.in

@@ -0,0 +1,17 @@
+# The Python tools CI installs, and the only place their versions are chosen.
+#
+# tools/requirements-ci.txt is generated from this file and pins the whole
+# transitive closure by hash, so a compromised or re-uploaded package on PyPI
+# fails the install instead of running. Regenerate after editing this file:
+#
+#   uv pip compile --generate-hashes --python-version 3.12 --python-platform linux \
+#     --output-file tools/requirements-ci.txt tools/requirements-ci.in
+#
+# Resolve for the runner, not for the machine you are sitting at. Dependencies
+# are conditional on both, and a missing one fails the whole lane under
+# --require-hashes. Resolving this on Windows with Python 3.13 omits
+# typing-extensions, which anyio needs on 3.12 and CI would then refuse to
+# install. Those two flags are the difference; they are not decoration.
+
+platformio==6.1.19
+gcovr==8.6