@htekdev/actions-debugger 1.0.55 → 1.0.57

package/errors/known-unsolved/known-unsolved-039.yml

@@ -0,0 +1,102 @@
+id: known-unsolved-039
+title: "on.schedule minimum interval is 5 minutes — sub-5-minute cron patterns silently run every 5 minutes"
+category: known-unsolved
+severity: limitation
+tags:
+  - schedule
+  - cron
+  - on.schedule
+  - rate-limit
+  - interval
+  - minimum-frequency
+patterns:
+  - regex: '^\s*-\s*cron:\s*[''"]?\*\/[1-4]\s'
+    flags: 'm'
+  - regex: 'schedule.*cron.*every\s+(?:1|2|3|4)\s+minute'
+    flags: 'i'
+error_messages:
+  - "*/1 * * * *"
+  - "*/2 * * * *"
+  - "*/3 * * * *"
+  - "*/4 * * * *"
+root_cause: |
+  GitHub Actions enforces a minimum cron schedule interval of 5 minutes. Cron
+  expressions that would trigger more frequently — such as */1, */2, */3, or */4
+  in the minutes field — are silently capped and run every 5 minutes instead of
+  the configured interval.
+
+  There is no validation error, no warning in workflow run logs, and no annotation
+  on the workflow YAML file. The workflow appears correctly configured in the GitHub
+  UI, but runs execute every 5 minutes regardless of the specified granularity.
+
+  This limitation is enforced server-side by GitHub's scheduler and cannot be
+  overridden via any workflow configuration. It applies to all hosted runners and
+  self-hosted runners triggered via GitHub's scheduler.
+
+  Additionally, even at the 5-minute minimum, scheduled workflows on busy
+  repositories may be delayed further during periods of high GitHub Actions load.
+  Under heavy load, schedules are queued and run as capacity allows — not
+  necessarily at the exact scheduled time. The schedule event documentation notes
+  that schedules may be delayed "up to hours" when load is high.
+
+  Common developer mental model mismatch: developers migrating from cron daemons
+  (systemd, cron, AWS EventBridge) where sub-minute schedules are routine expect
+  GitHub Actions to support the same granularity.
+fix: |
+  Use a minimum interval of 5 minutes in your cron expression — replace */1,
+  */2, */3, or */4 in the minutes field with */5.
+
+  If sub-5-minute polling or execution is required, use an external trigger
+  mechanism instead of on.schedule:
+
+  - External scheduler (AWS EventBridge, Azure Logic Apps, GCP Cloud Scheduler)
+    that calls the workflow_dispatch REST API
+  - A self-hosted runner with a local cron daemon (systemd timer, Linux cron)
+    that invokes the GitHub API to dispatch the workflow
+  - Move the time-sensitive logic out of GitHub Actions entirely and run it
+    in a dedicated service that can be triggered at any frequency
+fix_code:
+  - language: yaml
+    label: "Minimum supported interval — every 5 minutes"
+    code: |
+      on:
+        schedule:
+          # Minimum supported interval is every 5 minutes
+          - cron: '*/5 * * * *'
+          # The following are silently capped to every 5 minutes:
+          # - cron: '*/1 * * * *'
+          # - cron: '*/2 * * * *'
+          # - cron: '*/3 * * * *'
+          # - cron: '*/4 * * * *'
+  - language: yaml
+    label: "workflow_dispatch trigger for external scheduler integration"
+    code: |
+      # Trigger via REST API from an external scheduler at any frequency:
+      # POST https://api.github.com/repos/OWNER/REPO/actions/workflows/WORKFLOW.yml/dispatches
+      # Body: {"ref": "main"}
+      on:
+        workflow_dispatch:
+          inputs:
+            triggered_by:
+              description: 'Trigger source identifier'
+              type: string
+              default: 'external-scheduler'
+
+      jobs:
+        scheduled-task:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Run task
+              run: echo "Triggered by ${{ inputs.triggered_by }}"
+prevention:
+  - "Always use */5 or higher in the cron minutes field for on.schedule expressions"
+  - "Add a comment next to every cron expression documenting the intended frequency and the 5-minute minimum"
+  - "Test schedule behavior by temporarily adding an on.push trigger during development rather than waiting for scheduled runs"
+  - "For sub-5-minute needs, design the solution with an external scheduler calling workflow_dispatch from the start — do not plan to reduce the interval later"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#schedule"
+    label: "GitHub Docs — Schedule event (on.schedule)"
+  - url: "https://stackoverflow.com/questions/63612471/run-github-actions-every-x-minutes-cron-job"
+    label: "Stack Overflow — Run GitHub Actions every X minutes (highly voted)"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#schedule"
+    label: "GitHub Docs — Note on schedule delays under high load"

package/errors/permissions-auth/permissions-auth-040.yml

@@ -0,0 +1,142 @@
+id: permissions-auth-040
+title: "GITHUB_TOKEN is read-only by default in new repositories — write operations fail with 403"
+category: permissions-auth
+severity: error
+tags:
+  - GITHUB_TOKEN
+  - read-only
+  - permissions
+  - 403
+  - new-repo
+  - workflow-permissions
+patterns:
+  - regex: 'remote:\s*Permission to .* denied to github-actions\[bot\]'
+    flags: i
+  - regex: 'Error:\s*Resource not accessible by integration'
+    flags: i
+  - regex: 'HttpError:\s*Resource not accessible by integration'
+    flags: i
+  - regex: '403.*github-actions\[bot\]'
+    flags: i
+error_messages:
+  - "remote: Permission to org/repo.git denied to github-actions[bot]"
+  - "Error: Resource not accessible by integration"
+  - "HttpError: Resource not accessible by integration"
+  - "fatal: unable to access 'https://github.com/org/repo/': The requested URL returned error: 403"
+  - "GitHub Actions is not permitted to create or approve pull requests"
+root_cause: |
+  In February 2023 (GitHub Changelog), GitHub changed the default GITHUB_TOKEN
+  permissions for all new repositories and new organizations from read-write to
+  read-only. Repositories created before this change retain their original default
+  (read-write) unless an administrator explicitly changes the org-level setting.
+
+  This creates two failure scenarios:
+
+  1. COPIED WORKFLOWS: A developer copies a workflow from an older repo or a public
+     template that relies on the default read-write GITHUB_TOKEN (for example, to push
+     a build artifact, create a release, comment on a PR, or open a pull request). In a
+     new repo, that same workflow fails with 403 or "Resource not accessible by
+     integration" because the token only has read permissions.
+
+  2. ORG POLICY CHANGE: An organization administrator enables the read-only default
+     at the organization level (Settings > Actions > General > Workflow permissions).
+     All repos in the org immediately start failing any workflow that performs write
+     operations without an explicit permissions block.
+
+  The failure message is typically cryptic and does not mention that the root cause is
+  the workflow permissions default — it only says the token was denied.
+fix: |
+  Add explicit permissions blocks to workflows or jobs that perform write operations.
+  GitHub recommends the principle of least privilege: grant only the specific write
+  permission needed, not blanket read-write access.
+
+  At the workflow level, a top-level permissions: block sets defaults for all jobs.
+  At the job level, a permissions: block overrides the workflow-level default for that
+  job only. Job-level is preferred — it minimises the blast radius if a job is
+  compromised.
+
+  Common permissions needed:
+  - contents: write — push commits, create releases, upload release assets
+  - pull-requests: write — create/comment on pull requests
+  - issues: write — create/comment on issues
+  - packages: write — publish to GitHub Packages
+  - pages: write — deploy to GitHub Pages (also needs id-token: write for OIDC)
+
+  Alternatively, change the default at repo level: Settings > Actions > General >
+  Workflow permissions > Read and write permissions. Not recommended for security-
+  conscious teams.
+fix_code:
+  - language: yaml
+    label: "Problem: workflow relies on default write token, fails in new repos"
+    code: |
+      # No permissions block — relies on default, which is READ-ONLY in new repos
+      on: push
+
+      jobs:
+        release:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - name: Build
+              run: npm run build
+            - name: Create GitHub Release
+              uses: softprops/action-gh-release@v2
+              with:
+                files: dist/**
+              # Fails with 403 in new repos — needs contents:write
+  - language: yaml
+    label: "Fix: explicit job-level permissions (least privilege)"
+    code: |
+      on: push
+
+      jobs:
+        release:
+          runs-on: ubuntu-latest
+          permissions:
+            contents: write    # Required to create releases and upload assets
+          steps:
+            - uses: actions/checkout@v4
+            - name: Build
+              run: npm run build
+            - name: Create GitHub Release
+              uses: softprops/action-gh-release@v2
+              with:
+                files: dist/**
+  - language: yaml
+    label: "Workflow-level permissions (when multiple jobs all need write access)"
+    code: |
+      on: push
+
+      # Set workflow-level default — overridden per job as needed
+      permissions:
+        contents: write
+        pull-requests: write
+
+      jobs:
+        build-and-release:
+          runs-on: ubuntu-latest
+          # Inherits workflow-level permissions
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm run build
+
+        comment-on-pr:
+          runs-on: ubuntu-latest
+          permissions:
+            pull-requests: write   # Job-level — more restrictive than workflow default
+            contents: read
+          steps:
+            - uses: actions/checkout@v4
+prevention:
+  - "Always declare explicit permissions blocks in workflows that push, create releases, comment, or deploy — never rely on defaults"
+  - "Run 'actionlint' locally — it warns when a workflow uses write-requiring actions without corresponding permissions"
+  - "Use the minimum permissions required: grant 'contents: write' only on jobs that need it, not at workflow level"
+  - "When copying a workflow from another repo, check whether it has a permissions block — add one if missing"
+  - "Review the GitHub Actions audit log when a workflow fails with 403 to confirm the token permissions in use"
+docs:
+  - url: "https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication#permissions-for-the-github_token"
+    label: "GitHub Docs: GITHUB_TOKEN permissions"
+  - url: "https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#setting-the-permissions-of-the-github_token-for-your-repository"
+    label: "GitHub Docs: Setting default workflow permissions"
+  - url: "https://github.blog/changelog/2023-02-02-github-actions-updating-the-default-github_token-permissions-to-read-only/"
+    label: "GitHub Changelog: Default GITHUB_TOKEN permissions changed to read-only (Feb 2023)"

package/errors/permissions-auth/permissions-auth-041.yml

@@ -0,0 +1,110 @@
+id: permissions-auth-041
+title: "actions/checkout submodules fail with auth error when private submodule repos are outside the workflow repository"
+category: permissions-auth
+severity: error
+tags:
+  - checkout
+  - submodules
+  - github-token
+  - private-repo
+  - authentication
+  - pat
+  - deploy-key
+patterns:
+  - regex: 'fatal: could not read Username for.*terminal prompts disabled'
+    flags: 'i'
+  - regex: 'fatal: repository ''.*github\.com.*'' not found'
+    flags: 'i'
+  - regex: 'remote: Repository not found\.'
+    flags: 'i'
+  - regex: 'Error: The process.*git.*failed with exit code 128'
+    flags: 'i'
+error_messages:
+  - "fatal: could not read Username for 'https://github.com': terminal prompts disabled"
+  - "fatal: repository 'https://github.com/org/private-submodule/' not found"
+  - "remote: Repository not found."
+  - "Error: The process '/usr/bin/git' failed with exit code 128"
+root_cause: |
+  `actions/checkout` uses the `GITHUB_TOKEN` (or the `token` input) to authenticate
+  git operations during checkout, including recursive submodule initialization.
+  `GITHUB_TOKEN` is automatically scoped to the repository that owns the running
+  workflow — it cannot access private repositories in other organizations, or other
+  private repositories within the same organization.
+
+  When a submodule `.gitmodules` entry points to a private repository that is different
+  from the workflow repository, git authentication fails during `submodule update`.
+  The resulting error (`fatal: could not read Username` or `repository not found`)
+  is confusing because the submodule URL is correct — the problem is authentication
+  scope, not the URL itself.
+
+  Developers upgrading from self-hosted runners (where global git credentials were
+  configured) or from `actions/checkout@v1-v2` (which had different authentication
+  behavior) frequently encounter this when moving to `actions/checkout@v4` on
+  GitHub-hosted runners.
+
+  This is a deliberate security boundary: `GITHUB_TOKEN` is intentionally limited to
+  the current repository to prevent workflows from silently reading other private repos.
+fix: |
+  Use one of two approaches:
+
+  1. **PAT approach**: Create a Personal Access Token (classic PAT with `repo` scope,
+     or a fine-grained PAT with read access to all submodule repos). Store it as a
+     repository secret and pass it via the `token` input to `actions/checkout`.
+
+  2. **Deploy key approach**: Add a read-only deploy key to each private submodule
+     repository, then use `webfactory/ssh-agent` to load the key before checkout.
+     This avoids PATs entirely and follows least-privilege principles.
+
+  For organizations, a machine account (a GitHub account created for automation) with
+  `repo` read access to all submodule repos is often easier to manage than fine-grained
+  PATs.
+fix_code:
+  - language: yaml
+    label: "PAT with repo scope passed via token input"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                submodules: recursive
+                token: ${{ secrets.SUBMODULE_PAT }}
+                # SUBMODULE_PAT: classic PAT with repo scope, or fine-grained PAT
+                # with Contents: read on all private submodule repos
+
+  - language: yaml
+    label: "SSH deploy key approach using webfactory/ssh-agent"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Configure SSH agent with submodule deploy key
+              uses: webfactory/ssh-agent@v0.9.0
+              with:
+                ssh-private-key: ${{ secrets.SUBMODULE_DEPLOY_KEY }}
+                # Add multiple keys for multiple private submodule repos:
+                # ssh-private-key: |
+                #   ${{ secrets.SUBMODULE_REPO_A_KEY }}
+                #   ${{ secrets.SUBMODULE_REPO_B_KEY }}
+
+            - uses: actions/checkout@v4
+              with:
+                submodules: recursive
+                # No token needed — SSH agent handles git authentication
+prevention:
+  - "Prefer deploy keys over PATs for submodule access — deploy keys are repo-scoped and easier to rotate"
+  - "Use fine-grained PATs scoped to specific repositories rather than classic PATs with broad repo scope"
+  - "Document which submodule repos require special secrets so new contributors can configure their forks"
+  - "Consider converting private submodule dependencies to private packages in a registry to avoid cross-repo auth complexity"
+  - "Test submodule checkout in a fresh fork or on a runner without existing git credentials to catch auth issues early"
+docs:
+  - url: "https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication#permissions-for-the-github_token"
+    label: "GitHub Docs — GITHUB_TOKEN permissions and scope"
+  - url: "https://github.com/actions/checkout#usage"
+    label: "actions/checkout — token and submodules inputs"
+  - url: "https://docs.github.com/en/authentication/connecting-to-github-with-ssh/managing-deploy-keys"
+    label: "GitHub Docs — Managing deploy keys"
+  - url: "https://github.com/webfactory/ssh-agent"
+    label: "webfactory/ssh-agent — Load SSH keys for Actions"

package/errors/runner-environment/runner-environment-112.yml

@@ -0,0 +1,98 @@
+id: runner-environment-112
+title: "ubuntu-24.04 nftables replaces iptables — Docker bridge networking and kind/minikube cluster setup fails"
+category: runner-environment
+severity: error
+tags:
+  - ubuntu-24.04
+  - docker
+  - networking
+  - iptables
+  - nftables
+  - kind
+  - minikube
+  - runner-image-update
+patterns:
+  - regex: 'No chain/target/match by that name'
+    flags: 'i'
+  - regex: 'iptables.*failed.*nat.*DOCKER'
+    flags: 'i'
+  - regex: 'Failed to set up iptables.*\(iptables-nft\)'
+    flags: 'i'
+  - regex: 'network.*setup.*failed.*iptables'
+    flags: 'i'
+  - regex: 'Error response from daemon.*iptables failed'
+    flags: 'i'
+error_messages:
+  - "iptables: No chain/target/match by that name."
+  - "Error response from daemon: driver failed programming external connectivity on endpoint: iptables failed: iptables --wait -t nat -A DOCKER -p tcp -d 0/0 --dport 5432 -j DNAT --to-destination 172.17.0.2:5432 ! -i docker0: iptables: No chain/target/match by that name."
+  - "Failed to set up iptables rules: iptables-nft is not supported"
+  - "Error: failed to create cluster: failed to ensure docker network: failed to set up kind CNI"
+root_cause: |
+  Ubuntu 24.04 ships with nftables as the primary packet-filtering framework. The `iptables`
+  command is now a thin wrapper around nftables (`iptables-nft`), replacing the legacy
+  `iptables-legacy` backend that was default on Ubuntu 20.04/22.04.
+
+  Docker's bridge networking writes iptables rules using legacy format assumptions. CNI plugins
+  used by Kubernetes tools (kind, minikube, k3s) also expect the legacy iptables backend to be
+  active. When these tools run on ubuntu-24.04, they encounter incompatible chain formats and
+  rule semantics that iptables-nft does not honour, causing network setup to fail with "No
+  chain/target/match by that name" errors.
+
+  The runner-images migration from ubuntu-22.04 to ubuntu-24.04 (and from ubuntu-latest pointing
+  to ubuntu-22.04 to ubuntu-24.04) silently exposes this issue for any workflow running
+  Docker-in-Docker, Kubernetes clusters, or service containers with custom networking.
+fix: |
+  Switch the `iptables` alternative back to the legacy backend before starting Docker or
+  any CNI-based tooling. Add this step at the top of your job, before any Docker or cluster
+  setup steps:
+
+    - name: Switch to legacy iptables
+      run: |
+        sudo update-alternatives --set iptables /usr/sbin/iptables-legacy
+        sudo update-alternatives --set ip6tables /usr/sbin/ip6tables-legacy
+
+  For kind clusters, the above fix is the most reliable approach.
+
+  If you cannot switch the iptables backend (e.g., you require nftables for other reasons),
+  use Docker with `--iptables=false` and manage forwarding rules manually, or use network
+  mode `host` where possible.
+
+  Long-term: upgrade to versions of kind (≥ v0.24), minikube (≥ v1.33), and Docker Engine
+  (≥ 27) that include nftables-native support.
+fix_code:
+  - language: yaml
+    label: "Switch to iptables-legacy before Docker or cluster setup (ubuntu-24.04)"
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-24.04
+          steps:
+            - name: Switch to legacy iptables
+              run: |
+                sudo update-alternatives --set iptables /usr/sbin/iptables-legacy
+                sudo update-alternatives --set ip6tables /usr/sbin/ip6tables-legacy
+
+            - name: Start kind cluster
+              uses: helm/kind-action@v1
+              with:
+                cluster_name: ci
+  - language: yaml
+    label: "Pin runs-on to ubuntu-22.04 as a temporary workaround"
+    code: |
+      jobs:
+        test:
+          # Temporary: ubuntu-22.04 uses iptables-legacy by default
+          # TODO: migrate to ubuntu-24.04 after updating kind/Docker versions
+          runs-on: ubuntu-22.04
+prevention:
+  - "Test workflows on ubuntu-24.04 explicitly before relying on ubuntu-latest switching to it"
+  - "Keep kind, minikube, and Docker Engine versions current — nftables-native support arrived in each"
+  - "Add an iptables-legacy switch step as a defensive measure in any job using Docker networking or CNI plugins"
+  - "Watch runner-images release notes (github.com/actions/runner-images) for ubuntu-latest label changes"
+docs:
+  - url: "https://docs.docker.com/network/iptables/"
+    label: "Docker — iptables and nftables networking"
+  - url: "https://github.com/actions/runner-images/issues/10636"
+    label: "runner-images #10636 — ubuntu-24.04 iptables-nft Docker incompatibility"
+  - url: "https://kind.sigs.k8s.io/docs/user/known-issues/"
+    label: "kind — Known Issues including iptables compatibility"

package/errors/runner-environment/runner-environment-113.yml

@@ -0,0 +1,118 @@
+id: runner-environment-113
+title: "ubuntu-24.04 removed python3-distutils — ModuleNotFoundError: No module named 'distutils' on pip install"
+category: runner-environment
+severity: error
+tags:
+  - ubuntu-24.04
+  - python
+  - distutils
+  - pip
+  - setup-py
+  - runner-image-update
+  - python-3-12
+patterns:
+  - regex: "ModuleNotFoundError: No module named 'distutils'"
+    flags: 'i'
+  - regex: 'No module named ''distutils\.core'''
+    flags: 'i'
+  - regex: 'error in setup command.*distutils'
+    flags: 'i'
+  - regex: 'distutils.*not found.*pip install'
+    flags: 'i'
+error_messages:
+  - "ModuleNotFoundError: No module named 'distutils'"
+  - "ModuleNotFoundError: No module named 'distutils.core'"
+  - "error in setup command: Error parsing /path/to/setup.cfg: No module named 'distutils.core'"
+  - "note: This error originates from a subprocess, and is likely not a problem with pip."
+  - "error: legacy-install-failure"
+root_cause: |
+  Ubuntu 24.04 ships Python 3.12 as the system Python. Python 3.12 fully removed the
+  `distutils` module from its standard library (it was deprecated in 3.10 and removed in 3.12
+  per PEP 632). Ubuntu Noble (24.04) also removed the `python3-distutils` apt backport package
+  that had been available on 20.04 and 22.04.
+
+  Many older Python packages still use `distutils` directly in their `setup.py` or `setup.cfg`
+  files. When `pip install` processes these packages, the build backend invokes `distutils` which
+  is no longer available. The error appears to be a build backend failure rather than a pip
+  failure, so the root cause is easy to miss.
+
+  This affects any workflow that:
+  - Uses the system Python (no `actions/setup-python` step)
+  - Installs packages with legacy `setup.py` that import `distutils`
+  - Creates virtualenvs from the system Python without pre-installing setuptools
+
+  Distinct from `setup-python-version-range-resolves-to-313-distutils-removed` which covers
+  setup-python action resolving to Python 3.12/3.13 and distutils in user packages. This entry
+  covers the apt-level removal affecting system Python on the ubuntu-24.04 runner image itself.
+fix: |
+  Option 1 (recommended): Use actions/setup-python to manage the Python version explicitly.
+  setup-python bundles setuptools which provides a distutils compatibility shim.
+
+  Option 2: Install setuptools as the first pip action before installing other packages.
+  setuptools >= 58.0.0 ships a `distutils` compatibility shim that satisfies `import distutils`.
+
+    - name: Install setuptools (distutils shim)
+      run: pip install setuptools
+
+  Option 3: Install the apt package `python3-setuptools` which restores distutils compatibility
+  at the system level for Python 3.12.
+
+  Option 4 (long-term): Migrate the affected package to PEP 517/518 — replace setup.py with
+  pyproject.toml and a modern build backend (setuptools>=61, flit, hatch, etc.).
+fix_code:
+  - language: yaml
+    label: "Use actions/setup-python so setuptools is available (recommended)"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-24.04
+          steps:
+            - uses: actions/checkout@v4
+
+            - uses: actions/setup-python@v5
+              with:
+                python-version: '3.12'
+
+            - name: Install dependencies
+              run: pip install -r requirements.txt
+  - language: yaml
+    label: "Pre-install setuptools to restore distutils shim (quick fix for system Python)"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-24.04
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Install setuptools (distutils compatibility shim for Python 3.12)
+              run: pip install --upgrade setuptools
+
+            - name: Install dependencies
+              run: pip install -r requirements.txt
+  - language: yaml
+    label: "Install python3-setuptools via apt (system-level fix)"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-24.04
+          steps:
+            - name: Install python3-setuptools
+              run: sudo apt-get install -y python3-setuptools
+
+            - name: Install dependencies
+              run: pip install -r requirements.txt
+prevention:
+  - "Always use actions/setup-python rather than relying on system Python — it ships with setuptools"
+  - "Pin a Python version explicitly; avoid implicit system Python which changes per runner image"
+  - "Run pip install --dry-run in CI to detect distutils/setuptools issues before they block builds"
+  - "Audit third-party dependencies for setup.py usage with: pip install pipdeptree; pipdeptree | grep setup.py"
+  - "Migrate legacy setup.py packages to pyproject.toml for long-term Python 3.12+ compatibility"
+docs:
+  - url: "https://docs.python.org/3/whatsnew/3.12.html#removed"
+    label: "Python 3.12 — Removed modules (distutils)"
+  - url: "https://peps.python.org/pep-0632/"
+    label: "PEP 632 — Deprecate distutils"
+  - url: "https://github.com/actions/runner-images/issues/9674"
+    label: "runner-images #9674 — python3-distutils unavailable on ubuntu-24.04"
+  - url: "https://github.com/actions/setup-python"
+    label: "actions/setup-python — bundles setuptools"