@htekdev/actions-debugger 1.0.81 → 1.0.83

package/errors/concurrency-timing/workflow-level-vs-job-level-concurrency-scope.yml

@@ -0,0 +1,92 @@
+id: concurrency-timing-041
+title: "Workflow-level concurrency cancels entire workflow — job-level concurrency only gates that specific job"
+category: concurrency-timing
+severity: silent-failure
+tags:
+  - concurrency
+  - cancel-in-progress
+  - workflow-level
+  - job-level
+  - scope
+  - deployment
+  - test-cancellation
+patterns:
+  - regex: '^concurrency:\s*$'
+    flags: 'm'
+  - regex: 'jobs\.[a-zA-Z_][a-zA-Z0-9_-]*:\s*\n(\s+.*\n)*\s+concurrency:'
+    flags: 'm'
+error_messages:
+  - "Run was cancelled. (workflow-level concurrency cancelled entire run including unrelated jobs)"
+  - "Skipping job deploy because it is not needed (cancelled by workflow-level concurrency group)"
+root_cause: |
+  The concurrency: key in GitHub Actions behaves fundamentally differently depending on
+  where it is placed in the workflow file:
+
+  WORKFLOW-LEVEL (top-level key, outside jobs:):
+  Cancels or queues the ENTIRE workflow run. When a new run starts for the same concurrency
+  group, all pending or in-progress jobs in the workflow are affected — including build,
+  test, lint, and deploy jobs. The full workflow run is treated as the atomic unit.
+
+  JOB-LEVEL (inside jobs.<job_id>: as a sibling of runs-on: and steps:):
+  Only gates THAT SPECIFIC JOB. Other jobs in the same workflow run execute concurrently
+  without restriction. Serialization or cancellation applies only to the job that declares
+  the concurrency block.
+
+  Common mistake #1: developer adds workflow-level concurrency intending to prevent
+  duplicate deployments, but accidentally causes active test/build jobs to be cancelled
+  on every new push — wasting compute and breaking CI feedback.
+
+  Common mistake #2: developer adds job-level concurrency expecting the whole workflow
+  to be serialized, but parallel test runs from multiple pushes execute simultaneously.
+fix: |
+  Use job-level concurrency on only the deploy job when you want to serialize
+  deployments without interrupting parallel test runs. Use workflow-level concurrency
+  only when you intend for the entire workflow to serialize or cancel on new push.
+fix_code:
+  - language: yaml
+    label: "Correct: job-level concurrency on deploy only — tests run freely"
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          # No concurrency — multiple test runs execute in parallel across pushes
+          steps:
+            - run: npm test
+
+        deploy:
+          needs: test
+          runs-on: ubuntu-latest
+          concurrency:
+            group: deploy-${{ github.ref_name }}
+            cancel-in-progress: false  # Queue deploys, never cancel in-flight
+          steps:
+            - run: ./deploy.sh
+  - language: yaml
+    label: "Caution: workflow-level concurrency cancels test and build jobs too"
+    code: |
+      # This cancels the ENTIRE workflow on new push — tests, build, and deploy all stop
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.ref }}
+        cancel-in-progress: true
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - run: npm test  # Also cancelled when a new push arrives
+
+        deploy:
+          needs: test
+          runs-on: ubuntu-latest
+          steps:
+            - run: ./deploy.sh
+prevention:
+  - "For deploy-only serialization, use job-level concurrency on only the deploy job"
+  - "Avoid cancel-in-progress: true at workflow level for deployment workflows — an interrupted deploy may leave infrastructure in an inconsistent state"
+  - "Use cancel-in-progress: ${{ github.event_name == 'pull_request' }} to cancel PR runs but preserve default-branch deployments"
+  - "Verify scope: if concurrency: is indented under a specific jobs.<id>: block it is job-level; if it is at the same indentation as jobs: it is workflow-level"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-concurrency"
+    label: "GitHub Docs: Using concurrency"
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#concurrency"
+    label: "GitHub Docs: concurrency syntax reference"

package/errors/known-unsolved/org-required-workflow-no-per-repo-override.yml

@@ -0,0 +1,88 @@
+id: known-unsolved-048
+title: 'Organization required workflows block all repo PRs with no per-repo override'
+category: known-unsolved
+severity: limitation
+tags:
+  - required-workflows
+  - organization
+  - branch-protection
+  - enterprise
+  - admin
+patterns:
+  - regex: 'Required status checks have not passed for this branch'
+    flags: 'i'
+  - regex: 'required workflows? are not complete'
+    flags: 'i'
+error_messages:
+  - 'Required status checks have not passed for this branch'
+  - 'The following required workflows are not complete: .github/workflows/required-check.yml'
+  - 'Required workflow failed: org-name/.github/.github/workflows/security-scan.yml'
+root_cause: |
+  GitHub Enterprise Cloud allows org admins to configure "Required workflows"
+  under Org Settings → Actions → Required workflows. These workflows run on
+  every push and pull_request event across every repository in the organization
+  and are automatically added as required status checks on all branches.
+
+  When a required workflow fails — due to a misconfiguration, missing secret,
+  incompatibility with a specific repository's structure, or a transient error
+  — all open PRs in every affected repository are blocked from merging. There
+  is no mechanism for repo admins or developers to bypass or exempt their
+  repository from the org-level required workflow. Only the org admin can fix
+  the required workflow or remove the requirement.
+
+  This creates an org-wide single point of failure: a bug in the centralized
+  required workflow instantly blocks all engineering teams from shipping.
+fix: |
+  There is no per-repository exemption for org required workflows. Mitigation
+  strategies for org admins:
+
+  1. Use `if:` conditions in the required workflow to skip gracefully for
+     incompatible repositories instead of failing.
+  2. Set `continue-on-error: true` on non-critical jobs within the required
+     workflow so that optional checks do not block merges.
+  3. Maintain a staging version of the required workflow tested on a canary
+     repo before rolling changes org-wide.
+  4. Set up alerting on required workflow failure rates to catch regressions
+     before they block the whole org.
+fix_code:
+  - language: yaml
+    label: 'Use if: conditions to gracefully skip incompatible repos'
+    code: |
+      # In org's .github repo: .github/workflows/required-check.yml
+      name: Required Security Scan
+      on: [push, pull_request]
+      jobs:
+        security-scan:
+          runs-on: ubuntu-latest
+          # Skip repos that are explicitly opted out
+          if: >-
+            !contains(
+              fromJSON('["org/legacy-repo", "org/infra-repo"]'),
+              github.repository
+            )
+          steps:
+            - uses: actions/checkout@v4
+            - name: Run scan
+              run: ./scripts/security-scan.sh
+
+  - language: yaml
+    label: 'Use continue-on-error for non-blocking checks'
+    code: |
+      jobs:
+        lint:
+          runs-on: ubuntu-latest
+          continue-on-error: true   # Won't block the required status check
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm run lint
+prevention:
+  - 'Test required workflows in a canary repository before enabling org-wide'
+  - 'Use `if:` guards to skip repos that cannot satisfy the required checks'
+  - 'Monitor required workflow failure rates with org-level Actions dashboards'
+  - 'Prefer `continue-on-error: true` for advisory checks that should not hard-block PRs'
+  - 'Keep required workflows minimal — only truly mandatory gates belong here'
+docs:
+  - url: 'https://docs.github.com/en/actions/administering-github-actions/required-workflows'
+    label: 'Required workflows — GitHub Docs'
+  - url: 'https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-status-checks-before-merging'
+    label: 'Required status checks — GitHub Docs'

package/errors/known-unsolved/step-log-output-truncated-64kb.yml

@@ -0,0 +1,88 @@
+id: known-unsolved-049
+title: 'GitHub Actions step log output silently truncated after 64 KB — tail of large logs invisible'
+category: known-unsolved
+severity: limitation
+tags:
+  - logging
+  - truncation
+  - debug
+  - large-output
+  - verbose-build
+
+patterns:
+  - regex: 'Log upload failed|Error uploading logs'
+    flags: 'i'
+  - regex: 'log size exceeds'
+    flags: 'i'
+
+error_messages:
+  - "##[warning]The log file exceeds the limit."
+  - "##[warning]Some log data was not captured."
+
+root_cause: |
+  GitHub Actions truncates the visible log output for each step at approximately
+  64 KB (65,536 bytes). Steps that produce large stdout or stderr — verbose builds,
+  test suites with thousands of tests, dependency installation logs, or debug-mode
+  tools — have their logs silently cut off at the truncation limit.
+
+  When logs are truncated, the last portion of the output (which often contains
+  the most important information — the actual error or failure message) becomes
+  invisible in the GitHub Actions UI. There is no prominent warning that truncation
+  occurred; only a small warning annotation may appear.
+
+  Common triggers:
+  - `npm install` with many packages in verbose mode
+  - Maven/Gradle builds with `--info` or `--debug` flags
+  - Test runners printing results for thousands of test cases
+  - CMake or Make with verbose output enabled
+  - Custom scripts that echo large data structures for debugging
+
+fix: |
+  GitHub has no setting to increase the per-step log limit. The workarounds
+  involve reducing log volume or capturing overflow output to an artifact file.
+
+  Option 1 — Reduce log verbosity: Remove `--verbose`, `--debug`, or `--info`
+  flags from build/install commands that produce excessive output.
+
+  Option 2 — Redirect overflow to artifact: Pipe output to a file and upload it
+  as an artifact. The complete log is preserved and downloadable.
+
+  Option 3 — Split the step: Break one large step into multiple smaller steps
+  so each step's output stays under the limit.
+
+fix_code:
+  - language: yaml
+    label: 'Redirect large output to artifact file'
+    code: |
+      - name: Run verbose build (output to file)
+        run: |
+          # Tee output: display live AND capture to file for artifact upload
+          set -o pipefail
+          make build 2>&1 | tee build-output.log
+
+      - name: Upload full build log as artifact
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: build-log
+          path: build-output.log
+          retention-days: 7
+  - language: yaml
+    label: 'Reduce log verbosity at build tool level'
+    code: |
+      - name: Install dependencies (quiet)
+        run: npm install --silent   # suppress per-package progress output
+
+      - name: Build (no verbose)
+        run: make build   # omit -v or VERBOSE=1
+
+prevention:
+  - 'Avoid passing `--verbose`, `--debug`, or `--info` flags to build tools in CI unless actively debugging a specific failure.'
+  - 'Use `2>&1 | tee output.log` with artifact upload for any step expected to produce large output.'
+  - 'Split long-running steps into smaller focused steps so each stays well under the 64 KB log limit.'
+
+docs:
+  - url: 'https://docs.github.com/en/actions/monitoring-and-troubleshooting-workflows/monitoring-workflows/using-the-github-actions-debugger'
+    label: 'Using the GitHub Actions debugger — GitHub Docs'
+  - url: 'https://github.com/actions/upload-artifact'
+    label: 'actions/upload-artifact — GitHub Actions'

package/errors/runner-environment/git-commit-author-identity-unknown.yml

@@ -0,0 +1,83 @@
+id: runner-environment-149
+title: '`git commit` fails with "Author identity unknown" — actions/checkout does not configure git user identity'
+category: runner-environment
+severity: error
+tags:
+  - checkout
+  - identity
+  - commit
+  - user-email
+  - author-identity
+  - automation
+
+patterns:
+  - regex: 'Author identity unknown'
+    flags: 'i'
+  - regex: 'please tell me who you are'
+    flags: 'i'
+  - regex: 'user\.email not configured'
+    flags: 'i'
+
+error_messages:
+  - "Author identity unknown"
+  - "*** Please tell me who you are."
+  - "fatal: empty ident name (for <>) not allowed"
+  - "error: empty ident name (for <>) not allowed"
+
+root_cause: |
+  `actions/checkout` sets up the repository and configures a `GITHUB_TOKEN`-based
+  credential helper for pushing, but it does NOT configure a git user identity
+  (`user.email` and `user.name`). When a workflow step subsequently creates a
+  commit, git requires committer identity to record in the commit object.
+
+  GitHub-hosted runners have no system-level git identity configured. Without
+  an explicit configuration step, git rejects the commit with the error
+  "Author identity unknown" and prompts for `user.email` and `user.name`.
+
+  This is one of the most common errors in workflows that automate commits:
+  auto-formatting fixes, changelog updates, version bumps, license header
+  injection, and documentation generation workflows that write changes back
+  to the repository.
+
+fix: |
+  Add an identity configuration step immediately after `actions/checkout`.
+  GitHub provides an official `github-actions[bot]` identity with a documented
+  no-reply email address that is suitable for automated commits. This makes
+  automated commits clearly attributable in repository history.
+
+  The numeric user ID prefix in the email (`41898282+`) is the GitHub user ID
+  for the `github-actions[bot]` service account and ensures the commits are
+  linked to that identity in the GitHub UI.
+
+fix_code:
+  - language: yaml
+    label: 'Add identity configuration step after checkout'
+    code: |
+      steps:
+        - uses: actions/checkout@v4
+          with:
+            token: ${{ secrets.GITHUB_TOKEN }}
+
+        - name: Set bot identity for automated commits
+          run: |
+            echo "Configuring identity for automated commits"
+            git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+            git config user.name "github-actions[bot]"
+
+        - name: Apply and commit changes
+          run: |
+            git add .
+            git commit -m "chore: automated update [skip ci]"
+            git push
+
+prevention:
+  - 'Add identity configuration as the first step after checkout in any job that creates commits.'
+  - 'Use the `github-actions[bot]` no-reply email to make automated commits attributable without a real user email.'
+  - 'Consider setting identity at workflow level using a reusable composite action so all jobs inherit it automatically.'
+  - 'Use `--global` flag if the workflow uses multiple checkouts or subdirectory checkouts that all need the same identity.'
+
+docs:
+  - url: 'https://github.com/actions/checkout'
+    label: 'actions/checkout — GitHub Actions'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-jobs-in-a-workflow'
+    label: 'Using jobs in a workflow — GitHub Docs'

package/errors/runner-environment/larger-runner-labels-require-paid-plan.yml

@@ -0,0 +1,73 @@
+id: runner-environment-144
+title: '`runs-on` larger hosted runner labels require GitHub Teams or Enterprise plan'
+category: runner-environment
+severity: error
+tags:
+  - runs-on
+  - larger-runners
+  - billing
+  - teams
+  - enterprise
+  - ubuntu-latest-4-cores
+patterns:
+  - regex: 'No runner matching the required labels was found:\s+ubuntu-latest-[0-9]+-cores'
+    flags: 'i'
+  - regex: 'No runner matching the required labels was found:\s+windows-latest-[0-9]+-cores'
+    flags: 'i'
+  - regex: 'No runner matching the required labels was found:\s+macos-latest-[0-9]+-cores'
+    flags: 'i'
+error_messages:
+  - 'No runner matching the required labels was found: ubuntu-latest-4-cores'
+  - 'No runner matching the required labels was found: ubuntu-latest-8-cores'
+  - 'No runner matching the required labels was found: windows-latest-8-cores'
+  - 'No runner matching the required labels was found: macos-latest-xlarge'
+root_cause: |
+  GitHub offers larger hosted runners (4-core, 8-core, 16-core, 64-core) via
+  labels like `ubuntu-latest-4-cores`, `ubuntu-latest-8-cores`,
+  `ubuntu-22.04-8-cores`, `windows-latest-8-cores`, and `macos-latest-xlarge`.
+  These runners are only available on GitHub Teams and GitHub Enterprise Cloud
+  plans. On GitHub Free and GitHub Pro plans these labels are not provisioned,
+  so the queued job sits waiting until it times out or immediately fails with
+  "No runner matching the required labels was found."
+
+  GitHub does not display a clear billing-tier explanation in the error message,
+  leaving developers to guess whether the runner label is misspelled or simply
+  unavailable on their plan.
+fix: |
+  Switch to the standard `ubuntu-latest` (2-core) runner for free/pro accounts,
+  upgrade to GitHub Teams/Enterprise to unlock larger runners, or use
+  self-hosted runners with more CPU/RAM as an alternative.
+fix_code:
+  - language: yaml
+    label: 'Use standard runner on free/pro plans'
+    code: |
+      jobs:
+        build:
+          # ubuntu-latest is a 2-core runner available on all GitHub plans
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: make build
+
+  - language: yaml
+    label: 'Conditionally use larger runner for orgs on Teams/Enterprise'
+    code: |
+      jobs:
+        build:
+          # Use larger runner for org workflows, fall back for personal repos
+          runs-on: >-
+            ${{ startsWith(github.repository, 'my-org/') &&
+                'ubuntu-latest-8-cores' || 'ubuntu-latest' }}
+          steps:
+            - uses: actions/checkout@v4
+            - run: make build
+prevention:
+  - 'Verify your GitHub plan tier before using larger runner labels — check under Billing & plans → GitHub Actions'
+  - 'Use self-hosted runners with additional CPU as a free alternative for resource-intensive builds'
+  - 'Document which runner labels require a paid plan in your repository CONTRIBUTING guide'
+  - 'Use `ubuntu-latest` (2-core) for most workflows; only reach for larger runners when build profiling shows a genuine bottleneck'
+docs:
+  - url: 'https://docs.github.com/en/actions/using-github-hosted-runners/about-larger-runners/about-larger-runners'
+    label: 'About larger runners — GitHub Docs'
+  - url: 'https://docs.github.com/en/billing/managing-billing-for-your-products/managing-billing-for-github-actions/about-billing-for-github-actions'
+    label: 'About billing for GitHub Actions — GitHub Docs'

package/errors/runner-environment/macos-bash-32-no-bash4-features.yml

@@ -0,0 +1,110 @@
+id: runner-environment-148
+title: "macOS runners ship with bash 3.2 — bash 4.x/5.x features unavailable"
+category: runner-environment
+severity: error
+tags:
+  - macos
+  - bash
+  - bash-version
+  - associative-arrays
+  - shell-scripting
+
+patterns:
+  - regex: 'declare.*-A.*invalid option'
+    flags: i
+  - regex: 'mapfile.*command not found'
+    flags: i
+  - regex: 'readarray.*command not found'
+    flags: i
+  - regex: 'syntax error near unexpected token.*\|\&'
+    flags: i
+
+error_messages:
+  - "/bin/bash: line N: declare: -A: invalid option"
+  - "declare: usage: declare [-afFirtx] [-p] [name[=value] ...]"
+  - "/bin/bash: mapfile: command not found"
+  - "/bin/bash: readarray: command not found"
+
+root_cause: |
+  macOS ships with GNU Bash 3.2.57 at /bin/bash due to Apple's decision not to
+  include GPL v3 software in the base OS. Bash 4.0 (released 2009) and all later
+  versions are GPL v3. macOS has not updated the system bash beyond 3.2.x for
+  over 15 years as a result.
+
+  GitHub-hosted macOS runners (macos-13, macos-14, macos-15, macos-latest) all use
+  /bin/bash as the default shell for `shell: bash` run steps. This means all bash
+  scripts on macOS runners are subject to bash 3.2 limitations:
+
+  - Associative arrays: `declare -A map` — UNAVAILABLE (added in bash 4.0)
+  - mapfile / readarray built-ins — UNAVAILABLE (added in bash 4.0)
+  - `|&` (pipe stdout and stderr): syntax error (added in bash 4.0)
+  - `**` globbing for recursive matching — UNAVAILABLE (added in bash 4.0, requires shopt -s globstar)
+  - Case-modifying parameter expansion: `${var^^}`, `${var,,}` — UNAVAILABLE (bash 4.0)
+
+  Workflows that run on ubuntu runners may work fine because ubuntu ships bash 5.x,
+  then silently fail on macOS runners at the same step due to the bash version
+  difference.
+
+fix: |
+  Install modern bash via Homebrew and either update the PATH or use the full path
+  to the installed bash in the shell setting or script shebang.
+
+  For cross-platform workflows, avoid bash 4.x/5.x-only features or add an explicit
+  setup step for macOS.
+
+fix_code:
+  - language: yaml
+    label: "Install modern bash via Homebrew (macOS)"
+    code: |
+      jobs:
+        build:
+          runs-on: macos-latest
+          steps:
+            - name: Install modern bash
+              run: brew install bash
+
+            - name: Run script with bash 5
+              run: /opt/homebrew/bin/bash my-script.sh
+              # Intel macOS: /usr/local/bin/bash
+              # Apple Silicon (macos-14+): /opt/homebrew/bin/bash
+
+  - language: yaml
+    label: "Set shell to modern bash for all steps"
+    code: |
+      jobs:
+        build:
+          runs-on: macos-latest
+          steps:
+            - name: Install modern bash
+              run: brew install bash
+
+            - name: Script using bash 4+ features
+              shell: /opt/homebrew/bin/bash {0}
+              run: |
+                declare -A mymap
+                mymap[key]="value"
+                echo "${mymap[key]}"
+
+  - language: yaml
+    label: "Cross-platform workaround — avoid bash 4+ features"
+    code: |
+      - run: |
+          # Use python or node for associative arrays cross-platform
+          python3 -c "
+          mymap = {'key': 'value'}
+          print(mymap['key'])
+          "
+
+prevention:
+  - Test macOS workflows explicitly — a step that passes on ubuntu may fail on macos.
+  - Avoid bash 4.x/5.x-only features (declare -A, mapfile, readarray) in scripts intended to run on macOS.
+  - Add `brew install bash` as the first step in any macOS job that uses modern bash syntax.
+  - Use `bash --version` in a debug step to confirm which bash is being used.
+
+docs:
+  - url: https://www.gnu.org/software/bash/manual/bash.html#What-is-Bash_003f
+    label: "GNU Bash — version history and features"
+  - url: https://brew.sh
+    label: "Homebrew — install modern bash on macOS"
+  - url: https://github.com/actions/runner-images/blob/main/images/macos/macos-15-Readme.md
+    label: "macos-15 runner image — pre-installed software"

package/errors/runner-environment/pip-externally-managed-environment-pep668.yml

@@ -0,0 +1,83 @@
+id: runner-environment-145
+title: "ubuntu-22/24 pip install fails with 'externally-managed-environment' (PEP 668)"
+category: runner-environment
+severity: error
+tags:
+  - ubuntu
+  - python
+  - pip
+  - pep-668
+  - packages
+  - setup-python
+
+patterns:
+  - regex: 'externally.managed.environment'
+    flags: i
+  - regex: 'This environment is externally managed'
+    flags: i
+
+error_messages:
+  - "error: externally-managed-environment"
+  - "× This environment is externally managed"
+  - "╰─> To install Python packages system-wide, try apt install"
+
+root_cause: |
+  PEP 668, adopted in Python 3.11+ and backported by distros like Ubuntu 22.04 and
+  24.04, prevents pip from installing packages into the system Python environment.
+  Ubuntu 22.04 ships Python 3.10 but enforces PEP 668 in the system pip. Ubuntu 24.04
+  ships Python 3.12 with full PEP 668 enforcement.
+
+  GitHub Actions runners expose the system Python when no setup-python step is used.
+  System pip blocks global installs and raises this error to prevent breaking
+  OS-managed packages that depend on system Python libraries.
+
+  Workflows that previously ran `pip install <pkg>` or `pip3 install <pkg>` directly
+  on ubuntu-20.04 succeed silently, but fail on ubuntu-22.04 and ubuntu-24.04 because
+  those images enforce the system-managed environment restriction.
+
+fix: |
+  Use one of these approaches:
+
+  1. Use actions/setup-python (recommended) — configures an isolated Python
+     environment that allows pip installs freely.
+
+  2. Install with --break-system-packages flag — allows global install but may
+     conflict with apt-managed packages. Use only for CI where isolation is
+     acceptable.
+
+  3. Create a virtual environment inline with python -m venv.
+
+fix_code:
+  - language: yaml
+    label: "Use actions/setup-python (recommended)"
+    code: |
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: pip install my-package   # installs into the setup-python venv, no error
+
+  - language: yaml
+    label: "Virtual environment workaround"
+    code: |
+      - run: |
+          python3 -m venv .venv
+          source .venv/bin/activate
+          pip install my-package
+
+  - language: yaml
+    label: "Break system packages flag (use with caution)"
+    code: |
+      - run: pip install --break-system-packages my-package
+
+prevention:
+  - Always use actions/setup-python before any pip install in workflows targeting ubuntu-22.04 or ubuntu-24.04.
+  - Pin ubuntu version explicitly — upgrading from ubuntu-20.04 to ubuntu-latest silently adopts PEP 668 enforcement.
+  - Prefer virtual environments over global installs in CI for reproducibility.
+
+docs:
+  - url: https://peps.python.org/pep-0668/
+    label: "PEP 668 — Marking Python base environments as externally managed"
+  - url: https://github.com/actions/setup-python
+    label: "actions/setup-python — GitHub Actions"
+  - url: https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2404-Readme.md
+    label: "ubuntu-24.04 runner image — pre-installed software"