CNTRLPLANE-3944: Regenerate requirements.txt files with pinned --hash entries

.github/workflows/docs-build-reusable.yaml

@@ -18,9 +18,10 @@ jobs:
       - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: '3.x'
-          pip-install: '-r docs/requirements.txt'
         env:
           PIP_CACHE_DIR: ${{ runner.temp }}/.pip-cache
+      - name: Install documentation dependencies
+        run: pip install --require-hashes -r docs/requirements.txt
       - name: Build documentation
         run: mkdocs build --strict
         working-directory: docs

contrib/oidc/README.md

@@ -58,10 +58,41 @@ sequenceDiagram
 2. Ansible installed on your local machine
 3. Required Python packages and Ansible collections:
    ```bash
-   pip install -r requirements.txt
+   pip install --require-hashes -r requirements.txt
    ansible-galaxy install -r requirements.yml
    ```
 
+### Managing Python dependencies
+
+`requirements.txt` pins every Python dependency (boto3, botocore, and their
+transitive dependencies) to an exact version and includes
+`--hash=sha256:...` entries for each published artifact, enabling pip's
+hash-checking mode (`pip install --require-hashes`) used above.
+
+To add a new dependency or update an existing one:
+
+1. Add or update the package's version constraint in `requirements.txt`
+   (e.g. `newpackage>=1.0.0`, or bump an existing pin).
+2. Regenerate the file with [`uv`](https://docs.astral.sh/uv/), compiling to
+   a new temporary path rather than overwriting `requirements.txt` directly,
+   then move it into place:
+
+   ```bash
+   uv pip compile --generate-hashes contrib/oidc/requirements.txt \
+     -o /tmp/requirements.txt.new
+   mv /tmp/requirements.txt.new contrib/oidc/requirements.txt
+   ```
+
+   This resolves the constraint to a concrete version, pulls in any new
+   transitive dependencies, and adds `--hash=sha256:...` entries for all
+   published wheel/sdist artifacts. Don't edit hashes by hand — always
+   regenerate so they're guaranteed to match the published artifact.
+3. Validate, forcing pip to actually verify every package's hash rather
+   than skipping ones already present locally:
+   ```bash
+   pip install --dry-run --ignore-installed --require-hashes -r requirements.txt
+   ```
+
 ## Configuration
 
 Before running the playbooks, you may want to customize the following variables in `playbooks/infra_setup.yml`:

contrib/oidc/requirements.txt

@@ -1,2 +1,35 @@
-boto3>=1.26.0
-botocore>=1.29.0
+# This file was autogenerated by uv via the following command:
+#    uv pip compile --generate-hashes contrib/oidc/requirements.txt -o /tmp/requirements.txt.new && mv /tmp/requirements.txt.new contrib/oidc/requirements.txt
+boto3==1.43.57 \
+    --hash=sha256:115ed9cac409d9b57e2437b52fdb4286660d12a2bd44a0f48d530e68623d09a7 \
+    --hash=sha256:549c95e45f9b04cf0c69727632dbdda23b84dcd3d0ed7981c6aaff72ef9cb5af
+    # via -r contrib/oidc/requirements.txt
+botocore==1.43.57 \
+    --hash=sha256:001a5653bebc03b862bde2da63bad4adb0b30072a3f247aba4daae5aa097b546 \
+    --hash=sha256:319c6d79f66c3f3f2b538f7dcdc90e410a15a7bfced1db06479134947e629482
+    # via
+    #   -r contrib/oidc/requirements.txt
+    #   boto3
+    #   s3transfer
+jmespath==1.1.0 \
+    --hash=sha256:472c87d80f36026ae83c6ddd0f1d05d4e510134ed462851fd5f754c8c3cbb88d \
+    --hash=sha256:a5663118de4908c91729bea0acadca56526eb2698e83de10cd116ae0f4e97c64
+    # via
+    #   boto3
+    #   botocore
+python-dateutil==2.9.0.post0 \
+    --hash=sha256:37dd54208da7e1cd875388217d5e00ebd4179249f90fb72437e91a35459a0ad3 \
+    --hash=sha256:a8b2bc7bffae282281c8140a97d3aa9c14da0b136dfe83f850eea9a5f7470427
+    # via botocore
+s3transfer==0.19.2 \
+    --hash=sha256:ba0309fd86be3c27dbf78cdd813c13c5e1df16e5874b99d2535ebbdfb9892993 \
+    --hash=sha256:d8168eccca828cbb2cd573675333f3bddd254313a9c42494b84c76b539e8ba25
+    # via boto3
+six==1.17.0 \
+    --hash=sha256:4721f391ed90541fddacab5acf947aa0d3dc7d27b2e1e8eda2be8970586c3274 \
+    --hash=sha256:ff70335d468e7eb6ec65b95b99d3a2836546063f63acc5171de367e834932a81
+    # via python-dateutil
+urllib3==2.7.0 \
+    --hash=sha256:231e0ec3b63ceb14667c67be60f2f2c40a518cb38b03af60abc813da26505f4c \
+    --hash=sha256:9fb4c81ebbb1ce9531cce37674bbc6f1360472bc18ca9a553ede278ef7276897
+    # via botocore

docs/Dockerfile

@@ -8,7 +8,7 @@ WORKDIR /home/docs
 USER docs
 
 COPY requirements.txt .
-RUN pip install --no-cache-dir -r requirements.txt \
+RUN pip install --no-cache-dir --require-hashes -r requirements.txt \
   && mkdir /home/docs/hypershift
 
 WORKDIR /home/docs/hypershift

docs/README.md

@@ -1,9 +1,50 @@
-Any changes to the docs in this directory can be tested locally before pushing changes to GitHub. Just follow these 
+Any changes to the docs in this directory can be tested locally before pushing changes to GitHub. Just follow these
 steps:
 
 1. cd to this directory
 2. Run `make image` to build the image
 3. Run `make build-containerized` to build the containerized version of the image
 4. Run `make serve-containerized` to serve up the docs website locally
 
-Any changes you make while the docs are served locally, will be updated in the local docs website.
+Any changes you make while the docs are served locally, will be updated in the local docs website.
+
+## Managing Python dependencies
+
+`requirements.txt` pins every Python dependency needed to build the docs
+(mkdocs and its plugins) to an exact version and includes
+`--hash=sha256:...` entries for each published artifact, enabling pip's
+hash-checking mode (`pip install --require-hashes`). This is what
+`.github/workflows/docs-build-reusable.yaml` installs before running
+`mkdocs build --strict`.
+
+Because hash-checking mode requires every installed package — including
+transitive dependencies of mkdocs-material, mkdocs-mermaid2-plugin, and
+mkdocs-glightbox — to be pinned and hashed, the file lists the full resolved
+dependency closure, not just the three plugins imported directly.
+
+### Adding or updating a dependency
+
+1. Add or update the package's version constraint in `requirements.txt`
+   (e.g. `newplugin>=1.0.0`, or bump an existing `==` pin).
+2. Regenerate the file with [`uv`](https://docs.astral.sh/uv/), compiling to
+   a new temporary path rather than overwriting `requirements.txt` directly,
+   then move it into place:
+
+   ```bash
+   uv pip compile --generate-hashes docs/requirements.txt -o /tmp/requirements.txt.new
+   mv /tmp/requirements.txt.new docs/requirements.txt
+   ```
+
+   This resolves the full dependency graph, pins every package (direct and
+   transitive) to an exact version, and adds `--hash=sha256:...` entries for
+   all of its published wheel/sdist artifacts. Don't edit hashes by hand —
+   always regenerate so they're guaranteed to match the published artifact.
+3. Validate the result, forcing pip to actually verify every package's hash
+   rather than skipping ones already present locally:
+
+   ```bash
+   pip install --dry-run --ignore-installed --require-hashes -r docs/requirements.txt
+   ```
+
+4. Confirm the docs still build: `cd docs && mkdocs build --strict`
+   (after installing the regenerated requirements into your environment).

docs/image-version.awk

@@ -1 +1 @@
-BEGIN { FS = " |==="}; /mkdocs-material/{print $2}
+BEGIN { FS = "==" }; /^mkdocs-material==/{split($2, p, " "); print p[1]}