@htekdev/actions-debugger 1.0.80 → 1.0.82

package/errors/caching-artifacts/cache-lookup-only-no-restore-silent.yml

@@ -0,0 +1,88 @@
+id: caching-artifacts-048
+title: "actions/cache lookup-only: true checks cache existence but does NOT restore files"
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - cache
+  - lookup-only
+  - cache-hit
+  - restore
+  - silent-no-op
+patterns:
+  - regex: 'lookup-only.*true'
+    flags: 'i'
+  - regex: 'Cache found and can be restored from key'
+    flags: 'i'
+error_messages:
+  - "Cache found and can be restored from key: node-modules-abc123"
+  - "lookup-only is set, skipping restore."
+root_cause: |
+  The lookup-only: true input on actions/cache@v4 instructs the action to query
+  the cache service and report whether an entry exists (via the cache-hit output)
+  without transferring any data to the runner. No files are downloaded or written
+  to disk.
+
+  Developers who add lookup-only: true hoping to get a "lightweight restore that
+  skips the upload post-step" receive a misleading green step. The cache-hit output
+  reports 'true', the step log says "Cache found and can be restored from key",
+  and everything looks successful — but the working directory is empty.
+  Subsequent build steps that depend on the cached files fail with cryptic errors
+  (missing executables, import errors, or blank node_modules) that appear unrelated
+  to caching.
+
+  The intended use case for lookup-only is a two-job pipeline: Job A checks if the
+  cache exists (lookup-only: true) and, if not, builds and saves it; Job B restores
+  normally. It is NOT a performance shortcut for regular restore-and-save workflows.
+fix: |
+  Remove lookup-only: true from any step that should actually restore cached files.
+  Use lookup-only: true only in a dedicated pre-check job that gates whether an
+  expensive build step needs to run, combined with a normal actions/cache step in
+  the subsequent job that performs the real restore.
+fix_code:
+  - language: yaml
+    label: "Remove lookup-only for normal cache restore (most cases)"
+    code: |
+      - name: Restore node_modules cache
+        id: cache
+        uses: actions/cache@v4
+        with:
+          path: node_modules
+          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: ${{ runner.os }}-node-
+          # Do NOT set lookup-only: true here — files must be restored
+  - language: yaml
+    label: "Correct pattern: lookup-only in check job, real restore in build job"
+    code: |
+      jobs:
+        check-cache:
+          runs-on: ubuntu-latest
+          outputs:
+            cache-hit: ${{ steps.lookup.outputs.cache-hit }}
+          steps:
+            - id: lookup
+              uses: actions/cache@v4
+              with:
+                path: node_modules
+                key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+                lookup-only: true   # only check — no download
+
+        build:
+          needs: check-cache
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/cache@v4
+              with:
+                path: node_modules
+                key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+                # no lookup-only — restores files and saves after build
+            - if: needs.check-cache.outputs.cache-hit != 'true'
+              run: npm ci
+prevention:
+  - "Only use lookup-only: true in a dedicated cache-check job that feeds a conditional build gate."
+  - "After using lookup-only, always follow up with a standard actions/cache step (no lookup-only) in the job that needs the files."
+  - "If you want to skip the post-step cache save, use actions/cache/restore instead of setting lookup-only: true."
+docs:
+  - url: "https://github.com/actions/cache#inputs"
+    label: "actions/cache README: inputs including lookup-only"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows"
+    label: "GitHub Actions: Caching dependencies"

package/errors/caching-artifacts/upload-artifact-rerun-run-id-collision.yml

@@ -0,0 +1,67 @@
+id: caching-artifacts-047
+title: "Re-run job fails with 'artifact already exists' when artifact name includes github.run_id"
+category: caching-artifacts
+severity: error
+tags:
+  - upload-artifact
+  - re-run
+  - run_id
+  - run_attempt
+  - artifact-name
+  - collision
+patterns:
+  - regex: 'An artifact with this name already exists on the workflow run'
+    flags: 'i'
+  - regex: 'Unable to upload artifact.*already exists'
+    flags: 'i'
+error_messages:
+  - "An artifact with this name already exists on the workflow run."
+  - "Unable to upload artifact: An artifact with this name already exists on the run."
+root_cause: |
+  github.run_id identifies a workflow run and remains the same value across all
+  re-run attempts triggered from the GitHub UI or REST API. When an artifact name
+  is constructed using github.run_id (e.g., my-build-${{ github.run_id }}), the
+  first attempt uploads successfully. If the job fails and is re-run, the re-run
+  attempt tries to create an artifact with the identical name on the same run.
+
+  actions/upload-artifact@v4 enforces unique artifact names per run as a hard
+  error (changed from v3 which silently overwrote). The re-run therefore fails
+  immediately with "artifact already exists" before any meaningful work is done.
+
+  Teams reach for run_id because it appears to be a unique-per-execution
+  identifier. It is not: it is unique per workflow trigger, stable across all
+  re-run attempts within that trigger.
+fix: |
+  Append github.run_attempt to the artifact name. run_attempt starts at 1 and
+  increments for each re-run of the same run_id, making the combined value unique
+  across attempts. Consumers of the artifact (download steps, workflow_run
+  triggers) must include run_attempt in their own references to locate the
+  correct artifact.
+fix_code:
+  - language: yaml
+    label: "Include run_attempt to make artifact name unique across re-runs"
+    code: |
+      - name: Upload build artifact
+        uses: actions/upload-artifact@v4
+        with:
+          # run_attempt increments on each re-run, preventing name collision
+          name: my-build-${{ github.run_id }}-${{ github.run_attempt }}
+          path: dist/
+  - language: yaml
+    label: "Download the matching artifact in a downstream job"
+    code: |
+      - name: Download build artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: my-build-${{ github.run_id }}-${{ github.run_attempt }}
+          path: dist/
+prevention:
+  - "Never use github.run_id alone as an artifact name uniqueness guarantee — it is stable across all re-runs of the same run."
+  - "Combine github.run_id with github.run_attempt to produce a name that is unique within a run AND across re-run attempts."
+  - "Use a matrix value or job name as the differentiator instead of run_id when the artifact is consumed by a job in the same workflow."
+  - "Check the GitHub UI Actions > Artifacts list to inspect existing artifact names before debugging re-run failures."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/storing-workflow-data-as-artifacts"
+    label: "GitHub Actions: Storing workflow data as artifacts"
+  - url: "https://github.com/actions/upload-artifact#not-uploading-to-the-same-artifact"
+    label: "actions/upload-artifact: unique artifact names per run"

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/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"

package/errors/runner-environment/ubuntu-24-ruby-not-preinstalled.yml

@@ -0,0 +1,74 @@
+id: runner-environment-146
+title: "ubuntu-24.04 runner — Ruby and gem not pre-installed"
+category: runner-environment
+severity: error
+tags:
+  - ubuntu-24
+  - ruby
+  - gem
+  - tools-missing
+  - migration
+
+patterns:
+  - regex: 'ruby\s*:\s*command not found'
+    flags: i
+  - regex: 'gem\s*:\s*command not found'
+    flags: i
+  - regex: 'No such file or directory.*ruby'
+    flags: i
+
+error_messages:
+  - "/usr/bin/bash: ruby: command not found"
+  - "/usr/bin/bash: gem: command not found"
+  - "Error: ruby not found"
+
+root_cause: |
+  GitHub's ubuntu-24.04 runner image does not include Ruby in its pre-installed
+  software list. Unlike ubuntu-22.04 (which ships Ruby 3.0.x from the Ubuntu 22
+  package repository), ubuntu-24.04 dropped Ruby as a default pre-installed tool.
+
+  Workflows that rely on `ruby`, `gem`, `bundle`, or `rake` being available without
+  an explicit setup step will fail with "command not found" when the runner image is
+  ubuntu-24.04 or when ubuntu-latest resolves to ubuntu-24.04.
+
+  This commonly affects:
+  - Workflows that run `gem install` or `bundle install` directly
+  - Custom scripts that call `ruby my-script.rb`
+  - Jekyll static site workflows without the setup-ruby action
+  - Workflows that inherited ubuntu-22.04 behavior when pinned to ubuntu-latest
+
+fix: |
+  Use the ruby/setup-ruby action to install Ruby on any runner. This is the
+  recommended approach for cross-platform consistency and version pinning.
+
+  Alternatively, install Ruby via apt-get if a specific package-managed version
+  is acceptable, but ruby/setup-ruby is strongly preferred for version control.
+
+fix_code:
+  - language: yaml
+    label: "Use ruby/setup-ruby action (recommended)"
+    code: |
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+          bundler-cache: true   # runs bundle install and caches gems
+
+      - run: ruby my-script.rb
+
+  - language: yaml
+    label: "Install via apt-get (version uncontrolled)"
+    code: |
+      - run: sudo apt-get install -y ruby ruby-dev
+
+prevention:
+  - Always use ruby/setup-ruby instead of relying on pre-installed Ruby.
+  - Test workflows against ubuntu-24.04 explicitly before switching ubuntu-latest.
+  - Check the ubuntu-24.04 pre-installed software list when migrating from ubuntu-22.04.
+
+docs:
+  - url: https://github.com/ruby/setup-ruby
+    label: "ruby/setup-ruby — 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"
+  - url: https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2204-Readme.md
+    label: "ubuntu-22.04 runner image — Ruby pre-installed"