@htekdev/actions-debugger 1.0.4 → 1.0.6

package/errors/concurrency-timing/runner-group-not-found-race.yml

@@ -0,0 +1,97 @@
+id: "concurrency-timing-008"
+title: "Intermittent 'Required runner group not found' when ephemeral runner registers after job dispatch"
+category: "concurrency-timing"
+severity: "error"
+tags:
+  - "runner-group"
+  - "self-hosted"
+  - "ephemeral"
+  - "race-condition"
+  - "dispatch"
+  - "organization"
+patterns:
+  - regex: "Required runner group '.*' not found"
+    flags: "i"
+  - regex: "runner_group_id.*null"
+    flags: "i"
+error_messages:
+  - "Required runner group 'x' not found"
+root_cause: |
+  In autoscaling self-hosted runner setups (EC2, GKE ephemeral runners, ARC), the runner
+  must register with GitHub BEFORE the job dispatcher resolves runner group membership.
+
+  The race condition occurs when:
+  1. A workflow is triggered and GitHub's broker immediately tries to assign the job
+  2. The ephemeral runner is still initializing (EC2 bootstrap, container pull, ~2:30 min)
+  3. The broker resolves runner group membership before the new runner completes registration
+  4. The broker reports "Required runner group 'X' not found" and fails the job
+
+  This is intermittent: matrix jobs expose it clearly because some cells get
+  already-running (pre-registered) runners while others need a fresh runner, triggering
+  the race. Inspecting the failed job via the Jobs API shows `runner_group_id: null`
+  and `runner_name: null` throughout the queue duration even though the runner group
+  exists and has the correct repository access.
+
+  A separate but related pattern occurs with org-level runner group repository access
+  grants not propagating to the broker V2 protocol in time, causing identical symptoms
+  regardless of runner initialization speed.
+
+  Reported upstream: https://github.com/actions/runner/issues/4252
+  Related: https://github.com/actions/runner/issues/4429
+fix: |
+  For ephemeral autoscaling runners:
+  Implement a registration wait loop that polls the GitHub Runners API before signaling
+  the runner as available. The runner should only become eligible for jobs after the
+  broker has acknowledged its registration.
+
+  For org-level runner group access issues:
+  Verify that the target repository is in the runner group's allowed repositories list
+  via API. If misconfigured, re-registering the runner at repository level instead of
+  org level is a reliable workaround.
+
+  General mitigation: Add timeout-minutes to all jobs on self-hosted runners so stuck
+  queued jobs fail fast rather than waiting until the 6-hour workflow timeout.
+fix_code:
+  - language: yaml
+    label: "Add timeout-minutes to detect stuck queued jobs quickly"
+    code: |
+      jobs:
+        build:
+          runs-on:
+            group: my-runner-group
+            labels: [self-hosted, linux]
+          timeout-minutes: 10  # Fail fast if runner never picks up the job
+          steps:
+            - uses: actions/checkout@v4
+            - run: echo "Runner assigned successfully"
+  - language: yaml
+    label: "Verify runner group repository access via API"
+    code: |
+      jobs:
+        debug-runner-group:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Check runner group repository access
+              env:
+                GH_TOKEN: ${{ secrets.ORG_RUNNER_READ_TOKEN }}
+              run: |
+                echo "Runner groups and their visibility:"
+                gh api /orgs/${{ github.repository_owner }}/actions/runner-groups \
+                  --jq '.runner_groups[] | "\(.name) (id: \(.id)) — visibility: \(.visibility)"'
+
+                echo "Repositories allowed for runner group ID 1:"
+                gh api /orgs/${{ github.repository_owner }}/actions/runner-groups/1/repositories \
+                  --jq '.repositories[].full_name'
+prevention:
+  - "Add timeout-minutes to all jobs using self-hosted runners so stuck-queued jobs fail fast instead of waiting for the 6h workflow limit"
+  - "For ephemeral runners (EC2/ARC), implement a registration health check that polls the Runners API before the runner accepts jobs"
+  - "For org-level runners, verify group repository access via API after any runner group configuration change"
+  - "For matrix jobs with ephemeral runners, keep N idle pre-registered runners to avoid cold-start races"
+  - "Monitor runner_group_id via the Jobs API to detect dispatch failures early in autoscaling pipelines"
+docs:
+  - url: "https://github.com/actions/runner/issues/4252"
+    label: "actions/runner #4252 — Intermittent runner group not found"
+  - url: "https://github.com/actions/runner/issues/4429"
+    label: "actions/runner #4429 — Org-level runner never dispatched"
+  - url: "https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/managing-access-to-self-hosted-runners-using-groups"
+    label: "GitHub Docs — Managing runner group access"

package/errors/runner-environment/checkout-safe-directory-container.yml

@@ -0,0 +1,84 @@
+id: "runner-environment-022"
+title: "actions/checkout set-safe-directory only runs in post step — container jobs get dubious ownership errors"
+category: "runner-environment"
+severity: "error"
+tags:
+  - "actions/checkout"
+  - "safe-directory"
+  - "container"
+  - "dubious-ownership"
+  - "CVE-2022-24765"
+  - "post-step"
+patterns:
+  - regex: "fatal: detected dubious ownership in repository"
+    flags: "i"
+  - regex: "safe\\.directory.*not.*owned"
+    flags: "i"
+error_messages:
+  - "fatal: detected dubious ownership in repository at '/github/workspace'"
+  - "hint: git config --global --add safe.directory /github/workspace"
+root_cause: |
+  The `actions/checkout` action configures `safe.directory` to allow git operations in
+  the workspace. However, this configuration only runs in the **post step** (cleanup
+  phase), not during the main execution step.
+
+  In container jobs, the workspace is mounted from the host and may be owned by a
+  different UID than the user running inside the container. Git's safe.directory
+  protection (introduced in Git 2.35.2 for CVE-2022-24765) blocks access when the
+  directory owner differs from the running user.
+
+  Because safe.directory is only written during the post step — after all workflow
+  steps have already run — any subsequent git operations in the job's main steps
+  fail with "fatal: detected dubious ownership". This includes third-party actions
+  that internally invoke git (reviewdog, gitops tools, semantic-release, etc.).
+
+  Reported upstream: https://github.com/actions/checkout/issues/2031
+fix: |
+  Add an explicit safe.directory configuration step immediately after `actions/checkout`
+  in any container job that performs git operations. This ensures the directory is
+  trusted before any subsequent steps run.
+fix_code:
+  - language: yaml
+    label: "Add safe.directory config step after checkout in container jobs"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          container: node:20-bookworm
+          steps:
+            - uses: actions/checkout@v4
+
+            # Workaround: post step safe.directory config doesn't help in container jobs
+            - name: Mark workspace as safe for git
+              run: git config --global --add safe.directory "$GITHUB_WORKSPACE"
+
+            - name: Run git-dependent steps
+              run: git log --oneline -5
+  - language: yaml
+    label: "Use wildcard to mark all directories safe in container workflows"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          container: python:3.12-slim
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Configure git safe directories
+              run: |
+                git config --global --add safe.directory '*'
+
+            - name: Lint with pre-commit
+              run: pre-commit run --all-files
+prevention:
+  - "Always add a safe.directory config step after checkout when using container jobs"
+  - "Audit third-party actions in container jobs — reviewdog, semantic-release, and gitops tools invoke git internally"
+  - "Consider running without a container and using docker run explicitly if git safety is complex to manage"
+  - "Track https://github.com/actions/checkout/issues/2031 for an official fix from the actions team"
+docs:
+  - url: "https://github.com/actions/checkout/issues/2031"
+    label: "actions/checkout #2031 — safe.directory only set in post step"
+  - url: "https://github.blog/2022-04-12-git-security-vulnerability-announced/"
+    label: "Git CVE-2022-24765 — safe.directory background"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-where-your-workflow-runs/running-jobs-in-a-container"
+    label: "GitHub Docs — Running jobs in a container"

package/errors/runner-environment/dockerhub-pull-rate-limit.yml

@@ -0,0 +1,125 @@
+id: runner-environment-024
+title: "Docker Hub Pull Rate Limit — toomanyrequests in GitHub Actions"
+category: runner-environment
+severity: error
+tags:
+  - docker
+  - docker-hub
+  - rate-limit
+  - container
+  - pull
+  - authentication
+patterns:
+  - regex: "toomanyrequests: You have reached your pull rate limit"
+    flags: "i"
+  - regex: "You have reached your unauthenticated pull rate limit"
+    flags: "i"
+  - regex: "pull rate limit reached"
+    flags: "i"
+  - regex: "ERROR: toomanyrequests"
+    flags: "i"
+  - regex: "429 Too Many Requests.*docker"
+    flags: "i"
+error_messages:
+  - "toomanyrequests: You have reached your pull rate limit. You may increase the limit by authenticating and upgrading: https://www.docker.com/increase-rate-limit"
+  - "Error response from daemon: toomanyrequests: You have reached your unauthenticated pull rate limit."
+  - "pull access denied, repository does not exist or may require 'docker login'"
+root_cause: |
+  Docker Hub enforces anonymous pull rate limits on all IP addresses. GitHub-hosted
+  runners share a pool of egress IPs — multiple concurrent workflow runs from different
+  repositories hit Docker Hub from the same IP address, exhausting the shared quota
+  rapidly.
+
+  **Rate limit tiers (as of 2024):**
+  - **Unauthenticated (anonymous):** 100 pulls per 6 hours per IP
+  - **Authenticated free account:** 200 pulls per 6 hours per account
+  - **Docker Hub Pro/Team/Business:** unlimited
+
+  Because GitHub-hosted runners use a small set of shared egress IPs, popular runners
+  can hit the anonymous 100-pull limit within minutes during peak hours. The error
+  surfaces as a hard failure when the runner attempts `docker pull` for job containers,
+  service containers, container actions, or explicit `docker pull` commands in steps.
+
+  Even after adding `docker/login-action`, workflows can still hit the limit if they use
+  actions that internally pull images (e.g., `docker/build-push-action`, `docker/bake-action`)
+  before the login step has executed.
+fix: |
+  Add `docker/login-action` as the **first step** in any job that pulls from Docker Hub.
+  The action authenticates with Docker Hub, switching from anonymous to authenticated rate
+  limits (200 pulls/6 hours per account) or unlimited for Pro/Team accounts.
+
+  **Recommended approach:**
+  1. Create a Docker Hub account (free tier) or use an existing one.
+  2. Store credentials as repository secrets: `DOCKERHUB_USERNAME` and `DOCKERHUB_TOKEN`
+     (use an Access Token, not your password — generate at hub.docker.com > Account Settings > Security).
+  3. Add the login step before any image-pulling step.
+
+  **For self-hosted runners:** Configure a Docker Hub mirror or use GitHub Packages /
+  Amazon ECR / Google Artifact Registry to cache images and avoid Docker Hub entirely.
+fix_code:
+  - language: yaml
+    label: "Authenticate with Docker Hub before pulling images"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            # Login FIRST — before any step that pulls from Docker Hub
+            - name: Log in to Docker Hub
+              uses: docker/login-action@v3
+              with:
+                username: ${{ secrets.DOCKERHUB_USERNAME }}
+                password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+            - uses: actions/checkout@v4
+
+            - name: Build and push
+              uses: docker/build-push-action@v5
+              with:
+                push: true
+                tags: myorg/myimage:latest
+  - language: yaml
+    label: "Authenticate for jobs using a container image"
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          container:
+            image: python:3.12
+            credentials:
+              username: ${{ secrets.DOCKERHUB_USERNAME }}
+              password: ${{ secrets.DOCKERHUB_TOKEN }}
+          steps:
+            - uses: actions/checkout@v4
+            - run: python -m pytest
+  - language: yaml
+    label: "Authenticate for service containers pulling from Docker Hub"
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          services:
+            postgres:
+              image: postgres:16
+              credentials:
+                username: ${{ secrets.DOCKERHUB_USERNAME }}
+                password: ${{ secrets.DOCKERHUB_TOKEN }}
+              env:
+                POSTGRES_PASSWORD: postgres
+          steps:
+            - uses: actions/checkout@v4
+prevention:
+  - "Store a Docker Hub access token (not password) in secrets and use docker/login-action@v3 in all jobs that pull images."
+  - "Place the docker/login-action step first in the job — before any action that internally pulls Docker Hub images."
+  - "Consider mirroring frequently-used base images to GitHub Container Registry (ghcr.io) or your cloud provider's registry to eliminate Docker Hub dependency."
+  - "Use Docker Hub's Automated Builds or a scheduled workflow to keep mirror images up to date."
+  - "For service containers and job containers, always provide `credentials:` block alongside `image:` when pulling from Docker Hub."
+docs:
+  - url: "https://docs.docker.com/docker-hub/download-rate-limit/"
+    label: "Docker Hub: Download rate limit documentation"
+  - url: "https://github.com/docker/login-action"
+    label: "docker/login-action — GitHub Marketplace"
+  - url: "https://docs.github.com/en/actions/use-cases-and-examples/publishing-packages/publishing-docker-images"
+    label: "GitHub Docs: Publishing Docker images"
+  - url: "https://github.com/actions/runner-images/issues/1445"
+    label: "actions/runner-images #1445 — Did Docker Hub rate limit affect GitHub Action?"

package/errors/runner-environment/self-hosted-runner-version-deprecated.yml

@@ -0,0 +1,99 @@
+id: "runner-environment-023"
+title: "Self-hosted runner on deprecated version stops receiving jobs"
+category: "runner-environment"
+severity: "error"
+tags:
+  - "self-hosted"
+  - "runner"
+  - "deprecated"
+  - "version"
+  - "cannot-receive-messages"
+  - "maintenance"
+patterns:
+  - regex: "Runner version v\\d+\\.\\d+\\.\\d+ is deprecated and cannot receive messages"
+    flags: "i"
+  - regex: "WRITE ERROR.*runner.*deprecated"
+    flags: "i"
+error_messages:
+  - "Runner version v2.332.0 is deprecated and cannot receive messages."
+  - "WRITE ERROR: An error occured: Runner version v2.XXX.X is deprecated and cannot receive messages."
+root_cause: |
+  GitHub periodically deprecates older self-hosted runner versions. Once a runner version
+  is past its deprecation deadline, the runner agent can no longer communicate with the
+  GitHub Actions broker service.
+
+  The runner process stays alive, appears online in the GitHub UI (Settings → Actions →
+  Runners), and is listed as "Active" — but it can no longer receive job assignments.
+  Jobs queued for a runner group containing only deprecated-version runners will either
+  stay "Queued" indefinitely or time out without a clear error in the workflow UI.
+
+  This is a silent failure mode: the runner shows as online, no workflow error is
+  surfaced, but jobs never start. The deprecation schedule is published in the GitHub
+  Changelog and actions/runner releases but teams often miss it without automated
+  update pipelines.
+
+  As of 2026, GitHub requires runners to be within approximately the last 6 months of
+  releases. Related issues: actions/runner #4305, actions/runner #4442
+fix: |
+  Update the runner binary to a currently supported version.
+
+  For manually managed runners:
+  1. SSH to the runner host
+  2. Stop the runner service: ./svc.sh stop
+  3. Download the latest runner from https://github.com/actions/runner/releases/latest
+  4. Extract to the runner directory (configuration is preserved via .runner file)
+  5. Restart: ./svc.sh start
+
+  For ARC (Actions Runner Controller) or autoscaling solutions: bump the runner image
+  version tag in your HelmRelease or Deployment manifest and redeploy.
+fix_code:
+  - language: yaml
+    label: "Scheduled workflow to alert on outdated runner versions"
+    code: |
+      name: Check self-hosted runner versions
+      on:
+        schedule:
+          - cron: '0 9 * * 1'  # Weekly Monday 9 AM
+
+      jobs:
+        check-runners:
+          runs-on: ubuntu-latest  # GitHub-hosted runner for this diagnostic
+          steps:
+            - name: List runner versions via API
+              env:
+                GH_TOKEN: ${{ secrets.RUNNER_READ_TOKEN }}
+              run: |
+                echo "=== Org runners ==="
+                gh api /orgs/${{ github.repository_owner }}/actions/runners \
+                  --jq '.runners[] | "\(.name): v\(.version) (\(.status))"'
+
+            - name: Check latest available version
+              run: |
+                LATEST=$(curl -sf https://api.github.com/repos/actions/runner/releases/latest | jq -r .tag_name)
+                echo "Latest runner version: $LATEST"
+                echo "Compare against your registered runners above"
+  - language: yaml
+    label: "ARC — bump runner version in HelmRelease"
+    code: |
+      # In your ARC HelmRelease or values.yaml
+      githubConfigUrl: "https://github.com/myorg"
+      template:
+        spec:
+          containers:
+            - name: runner
+              image: ghcr.io/actions/actions-runner:2.335.0  # Bump this regularly
+prevention:
+  - "Subscribe to the GitHub Changelog (https://github.blog/changelog/) or watch actions/runner releases for deprecation notices"
+  - "Use Actions Runner Controller (ARC) or an autoscaling solution to automate runner lifecycle management"
+  - "Schedule a weekly cron workflow that checks registered runner versions via the Runners API and alerts if any are outdated"
+  - "Pin runner version in IaC (Terraform, Ansible) and include a runner version bump in your monthly maintenance checklist"
+  - "Set up Dependabot or Renovate to auto-update runner image tags in Docker/ARC manifests"
+docs:
+  - url: "https://github.com/actions/runner/releases"
+    label: "actions/runner releases — version history and changelogs"
+  - url: "https://github.com/actions/runner/issues/4305"
+    label: "actions/runner #4305 — runner deprecated cannot receive messages"
+  - url: "https://github.com/actions/runner/issues/4442"
+    label: "actions/runner #4442 — version deprecation notice"
+  - url: "https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners"
+    label: "GitHub Docs — About self-hosted runners"

package/errors/runner-environment/service-container-localhost-vs-hostname.yml

@@ -0,0 +1,130 @@
+id: runner-environment-025
+title: "Service Container Network: localhost Works on Runner, Service Name Required in Container Jobs"
+category: runner-environment
+severity: error
+tags:
+  - service-containers
+  - networking
+  - localhost
+  - postgres
+  - mysql
+  - redis
+  - container-jobs
+  - docker-networking
+patterns:
+  - regex: "Connection refused.*(?:localhost|127\\.0\\.0\\.1).*(?:5432|3306|6379|27017)"
+    flags: "i"
+  - regex: "could not connect to server.*Connection refused.*localhost"
+    flags: "i"
+  - regex: "ECONNREFUSED.*(?:5432|3306|6379|27017)"
+    flags: "i"
+  - regex: "dial tcp 127\\.0\\.0\\.1:\\d+: connect: connection refused"
+    flags: "i"
+error_messages:
+  - "Error: connect ECONNREFUSED 127.0.0.1:5432"
+  - "could not connect to server: Connection refused (Is the server running on host \"localhost\" (127.0.0.1) and accepting TCP/IP connections on port 5432?)"
+  - "OperationalError: connection to server at \"localhost\" (127.0.0.1), port 5432 failed: Connection refused"
+  - "Error: getaddrinfo ENOTFOUND postgres"
+root_cause: |
+  GitHub Actions service containers run as Docker containers on the runner machine.
+  The correct hostname to reach them depends on **how the job itself runs**:
+
+  **Scenario A — Job runs directly on the runner (no `container:` key):**
+  The runner process runs natively on the VM. Docker maps service container ports to the
+  runner's loopback interface. Services are reachable at `localhost:<mapped_port>`.
+  Using the service name (e.g. `postgres`) as a hostname will **fail** with ENOTFOUND.
+
+  **Scenario B — Job runs inside a container (`container:` key present):**
+  Both the job container and service containers are on the same Docker user-defined network.
+  Docker's built-in DNS resolves container names. Services are reachable by their
+  **service name** (e.g. `postgres`, `redis`) as the hostname, NOT `localhost`.
+  Using `localhost` here will produce "Connection refused" because the service port is
+  not bound to the job container's loopback interface.
+
+  This asymmetry is the root of most service container connectivity bugs:
+  developers copy a working non-containerized workflow config into a containerized job
+  (or vice versa) without updating the hostname.
+
+  Additionally, when using `ports:` mapping in service definitions, the runner maps the
+  container port to a randomly assigned host port (unless pinned with `host:container`
+  syntax). The `${{ job.services.postgres.ports['5432'] }}` expression returns the
+  actual host-side port, which may differ from 5432.
+fix: |
+  **For jobs running directly on the runner (no `container:` key):**
+  Connect to services via `localhost` (or `127.0.0.1`) and the mapped port.
+  Use `${{ job.services.<service>.ports['<container_port>'] }}` to get the dynamic host port
+  when not using explicit port pinning.
+
+  **For jobs running in a container (`container:` key):**
+  Connect to services via the **service name** as the hostname and the container's
+  internal port directly. No port mapping is required — both containers share the same
+  Docker network and communicate directly.
+
+  Use the `options: --add-host` trick only if you need the same workflow YAML to work
+  in both contexts (rare — avoid this complexity).
+fix_code:
+  - language: yaml
+    label: "Correct connectivity for a runner-native job (no container:)"
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          # No 'container:' key — job runs directly on the runner VM
+          services:
+            postgres:
+              image: postgres:16
+              env:
+                POSTGRES_PASSWORD: postgres
+              ports:
+                - 5432:5432    # pin host:container port for simplicity
+              options: >-
+                --health-cmd pg_isready
+                --health-interval 10s
+                --health-timeout 5s
+                --health-retries 5
+          steps:
+            - uses: actions/checkout@v4
+            - name: Run tests
+              env:
+                # Use localhost — runner-native job maps service ports to loopback
+                DATABASE_URL: postgres://postgres:postgres@localhost:5432/testdb
+              run: npm test
+  - language: yaml
+    label: "Correct connectivity for a containerized job (container: key present)"
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          container:
+            image: node:20  # Job itself runs inside a container
+          services:
+            postgres:
+              image: postgres:16
+              env:
+                POSTGRES_PASSWORD: postgres
+              # NO ports: mapping needed — containers share the Docker network
+              options: >-
+                --health-cmd pg_isready
+                --health-interval 10s
+                --health-timeout 5s
+                --health-retries 5
+          steps:
+            - uses: actions/checkout@v4
+            - name: Run tests
+              env:
+                # Use service NAME "postgres" — Docker DNS resolves it within the network
+                DATABASE_URL: postgres://postgres:postgres@postgres:5432/testdb
+              run: npm test
+prevention:
+  - "When your job uses `container:`, always connect to services via the service name (e.g. `postgres`, `redis`), NOT `localhost`."
+  - "When your job runs natively (no `container:`), always connect to services via `localhost` and the mapped host port."
+  - "Use `options: --health-cmd / --health-interval / --health-retries` on service containers to ensure they are ready before steps execute."
+  - "Avoid using `localhost` as the database hostname in connection strings — parameterize it so the same code works in both runner-native and containerized jobs."
+  - "If you move a job from runner-native to containerized (or vice versa), always audit all service hostnames in env variables and connection strings."
+docs:
+  - url: "https://docs.github.com/en/actions/use-cases-and-examples/using-containerized-services/about-service-containers"
+    label: "GitHub Docs: About service containers"
+  - url: "https://docs.github.com/en/actions/use-cases-and-examples/using-containerized-services/creating-postgresql-service-containers"
+    label: "GitHub Docs: Creating PostgreSQL service containers"
+  - url: "https://docs.github.com/en/actions/use-cases-and-examples/using-containerized-services/creating-redis-service-containers"
+    label: "GitHub Docs: Creating Redis service containers"

package/errors/runner-environment/ubuntu-latest-to-24-04-migration.yml

@@ -0,0 +1,138 @@
+id: runner-environment-026
+title: "ubuntu-latest Switched to Ubuntu 24.04 — Breaks Python 3.8/3.9, System Packages, OpenSSL"
+category: runner-environment
+severity: error
+tags:
+  - ubuntu
+  - ubuntu-24.04
+  - runner-image
+  - python
+  - openssl
+  - apt
+  - migration
+  - breaking-change
+patterns:
+  - regex: "Unable to locate package python3\\.[89]"
+    flags: "i"
+  - regex: "python3\\.[89].*not found.*ubuntu.*24"
+    flags: "i"
+  - regex: "E: Package 'python3\\.[89]' has no installation candidate"
+    flags: "i"
+  - regex: "error.*openssl.*libssl1\\.1.*not available"
+    flags: "i"
+  - regex: "deadsnakes.*ppa.*focal.*not available.*noble"
+    flags: "i"
+  - regex: "ubuntu-latest.*ubuntu 24"
+    flags: "i"
+error_messages:
+  - "E: Package 'python3.8' has no installation candidate"
+  - "E: Package 'python3.9' has no installation candidate"
+  - "E: Package 'libssl1.1' has no installation candidate"
+  - "Error: The version '3.8' with architecture 'x64' was not found for Ubuntu 24.04"
+  - "Error: deadsnakes/ppa does not provide Python 3.8 packages for Ubuntu Noble (24.04)"
+root_cause: |
+  GitHub began rolling out Ubuntu 24.04 as the new target for `ubuntu-latest` on
+  **December 5, 2024**, completing the transition on **January 17, 2025** (tracked in
+  actions/runner-images #10636, 266 👍 reactions). Any workflow using `runs-on: ubuntu-latest`
+  without explicit version pinning now runs on Ubuntu 24.04 ("Noble Numbat") instead of 22.04.
+
+  **Key breaking changes in Ubuntu 24.04:**
+
+  1. **Python 3.8 and 3.9 are end-of-life and not available** — not via `apt` and not via
+     the `deadsnakes/ppa` PPA (which only backports for supported Ubuntu releases). Workflows
+     that `apt-get install python3.8` or use `setup-python` with version `3.8` or `3.9` fail.
+
+  2. **OpenSSL 1.1 removed** — Ubuntu 24.04 ships only OpenSSL 3.x. Packages and Python
+     versions that were compiled against OpenSSL 1.1 (`libssl1.1`) will fail to install or
+     run. This affects older Ruby gems, some Go binaries, and legacy pip packages.
+
+  3. **System Python is 3.12** — the `python3` system binary points to Python 3.12, which
+     may break scripts that relied on the 3.10 default in 22.04.
+
+  4. **`apt` package name changes** — some packages were renamed or split between 22.04 and
+     24.04 (e.g., `python3-distutils` is gone; functionality merged into `python3`).
+
+  5. **`/usr/bin/python` symlink absent by default** — workflows calling bare `python`
+     (not `python3`) fail with "python: command not found".
+fix: |
+  **Short-term — pin to ubuntu-22.04:**
+  Replace `runs-on: ubuntu-latest` with `runs-on: ubuntu-22.04` to freeze the runner image
+  while you migrate. Note: ubuntu-22.04 will eventually reach end-of-support (~April 2027).
+
+  **Long-term — migrate to supported Python/package versions:**
+  - Replace Python 3.8/3.9 with Python 3.10, 3.11, or 3.12 using `actions/setup-python`.
+    `actions/setup-python` downloads a pre-built binary from the tool cache — it works
+    regardless of the runner's system Python.
+  - Replace `libssl1.1` dependencies by upgrading the affected package to an OpenSSL-3
+    compatible version, or adding a compatibility shim if available.
+  - Replace bare `python` calls with `python3`.
+
+  **For `deadsnakes` PPA users:** `deadsnakes/ppa` only provides Python 3.8/3.9 for
+  Ubuntu 20.04 (Focal) and 22.04 (Jammy) — not 24.04 (Noble). There is no supported
+  workaround; upgrade to a supported Python version.
+fix_code:
+  - language: yaml
+    label: "Pin to ubuntu-22.04 as a short-term fix while migrating"
+    code: |
+      jobs:
+        test:
+          # Pin explicitly until Python 3.8/3.9 dependencies are upgraded
+          runs-on: ubuntu-22.04
+          steps:
+            - uses: actions/checkout@v4
+            - run: python3.9 -m pytest
+  - language: yaml
+    label: "Use actions/setup-python to install any Python version on ubuntu-latest"
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-latest  # Now 24.04
+          steps:
+            - uses: actions/checkout@v4
+            - name: Set up Python
+              uses: actions/setup-python@v5
+              with:
+                # setup-python downloads pre-built binaries — works on any runner OS
+                python-version: '3.9'
+            - run: python --version  # 3.9.x from setup-python's tool cache
+            - run: pip install -r requirements.txt
+  - language: yaml
+    label: "Test matrix against multiple Python versions to find breakages early"
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          strategy:
+            matrix:
+              python-version: ['3.9', '3.10', '3.11', '3.12']
+          steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-python@v5
+              with:
+                python-version: ${{ matrix.python-version }}
+            - run: pip install -r requirements.txt && pytest
+  - language: yaml
+    label: "Fix bare 'python' command not found on Ubuntu 24.04"
+    code: |
+      steps:
+        - name: Ensure python symlink exists
+          run: |
+            # Ubuntu 24.04 no longer creates /usr/bin/python by default
+            sudo ln -sf /usr/bin/python3 /usr/bin/python
+        # Or: use actions/setup-python which sets up the PATH correctly
+prevention:
+  - "Pin `runs-on: ubuntu-22.04` explicitly if your workflow depends on Python 3.8/3.9, libssl1.1, or other 22.04-specific packages."
+  - "Use `actions/setup-python@v5` to install a specific Python version instead of relying on `apt-get install python3.x` — it works across all Ubuntu versions."
+  - "When you upgrade Ubuntu runner versions, scan `apt-get install` lines in run steps for packages that may not exist in the new Ubuntu release."
+  - "Replace bare `python` invocations with `python3` or use `actions/setup-python` which adds an alias."
+  - "Test your workflows against `ubuntu-24.04` explicitly before `ubuntu-latest` changes, by running on both runner images in a matrix."
+  - "Subscribe to https://github.com/actions/runner-images/issues for announcements about upcoming `ubuntu-latest` image transitions."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/10636"
+    label: "actions/runner-images #10636 — Ubuntu-latest workflows will use Ubuntu-24.04 image"
+  - url: "https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2404-Readme.md"
+    label: "Ubuntu 24.04 runner image — installed software reference"
+  - url: "https://github.com/actions/setup-python"
+    label: "actions/setup-python — install any Python version on any runner"
+  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources"
+    label: "GitHub Docs: Supported runners and hardware resources"

package/errors/silent-failures/cache-hit-restore-keys-misleading.yml

@@ -0,0 +1,82 @@
+id: "silent-failures-010"
+title: "cache-hit output is 'true' on restore-keys partial match, not just exact key"
+category: "silent-failures"
+severity: "silent-failure"
+tags:
+  - "actions/cache"
+  - "cache-hit"
+  - "restore-keys"
+  - "partial-match"
+  - "output"
+  - "exact-match"
+patterns:
+  - regex: "cache-hit.*true"
+    flags: "i"
+error_messages:
+  - "cache-hit: true"
+root_cause: |
+  The `cache-hit` output of `actions/cache` is documented to return `true` for an exact
+  cache key match. In practice, `cache-hit` also returns `true` when the key matched via
+  `restore-keys` (a partial/fallback match), not only for exact key hits.
+
+  Workflows that gate post-build steps on `steps.cache.outputs.cache-hit == 'true'` to
+  skip dependency installs assume an exact match. When a restore-keys match occurs,
+  `cache-hit` is `true` even though the cache may be stale or from a different branch.
+  The correct exact-match indicator is the `exact-match` output (available in
+  actions/cache v4+) or comparing `cache-matched-key` against the computed key.
+
+  Reported upstream: https://github.com/actions/cache/issues/1675
+fix: |
+  Use the `exact-match` output (actions/cache v4+) to determine if the restore was an
+  exact key match. `cache-hit` alone does not distinguish between exact and partial
+  (restore-keys) matches.
+
+  Alternatively, compare the `cache-matched-key` output against the expected key to
+  determine if the restore was exact.
+fix_code:
+  - language: yaml
+    label: "Use exact-match output (actions/cache v4+)"
+    code: |
+      - name: Restore cache
+        id: cache
+        uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-node-
+
+      # Only skip install on EXACT key match, not partial restore-keys hit
+      - name: Install dependencies
+        if: steps.cache.outputs.exact-match != 'true'
+        run: npm ci
+  - language: yaml
+    label: "Compare cache-matched-key to verify exact hit"
+    code: |
+      - name: Restore cache
+        id: cache
+        uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          key: npm-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: npm-
+
+      - name: Install or skip dependencies
+        run: |
+          EXPECTED_KEY="npm-${{ hashFiles('**/package-lock.json') }}"
+          if [ "${{ steps.cache.outputs.cache-matched-key }}" = "$EXPECTED_KEY" ]; then
+            echo "Exact cache hit — skipping npm ci"
+          else
+            echo "Partial/stale restore-keys hit — running npm ci"
+            npm ci
+          fi
+prevention:
+  - "Never rely on cache-hit == 'true' alone to skip dependency installs; it fires on partial restore-keys matches too"
+  - "Use the exact-match output (actions/cache v4+) when you need to distinguish exact vs partial cache hits"
+  - "Use cache-matched-key output to log or compare the actual key that was restored"
+  - "If using restore-keys, always validate that your skip-install condition handles partial matches correctly"
+docs:
+  - url: "https://github.com/actions/cache/issues/1675"
+    label: "actions/cache #1675 — cache-hit true on restore-keys match"
+  - url: "https://github.com/actions/cache#outputs"
+    label: "actions/cache outputs documentation"

package/errors/silent-failures/github-output-multiline-truncated.yml

@@ -0,0 +1,112 @@
+id: silent-failures-011
+title: "GITHUB_OUTPUT Multiline Values Silently Truncated — Heredoc EOF Required"
+category: silent-failures
+severity: silent-failure
+tags:
+  - github-output
+  - multiline
+  - output
+  - heredoc
+  - truncation
+  - environment-files
+patterns:
+  - regex: "echo\\s+['\"]?\\w+=.*\\$\\([^)]+\\).*>>\\s+\\$GITHUB_OUTPUT"
+    flags: "i"
+  - regex: "invalid value.*GITHUB_OUTPUT.*contains newline"
+    flags: "i"
+  - regex: "Error: Unable to process file command 'output'"
+    flags: "i"
+  - regex: "GITHUB_OUTPUT.*multiline"
+    flags: "i"
+error_messages:
+  - "Error: Unable to process file command 'output' successfully."
+  - "Invalid format 'key=line1\\nline2' - value contains newline, use heredoc syntax"
+  - "Warning: Unexpected input(s) 'output', valid inputs are"
+root_cause: |
+  The `GITHUB_OUTPUT` environment file protocol (introduced November 2022 as a replacement
+  for the deprecated `::set-output` command) uses a line-based key=value format that does
+  NOT support literal newline characters in values when using simple `echo "key=value"` syntax.
+
+  When a step sets a multiline output using the naive approach:
+  ```bash
+  echo "REPORT=$(cat report.txt)" >> $GITHUB_OUTPUT
+  ```
+  the shell expands `$(cat report.txt)` into a multiline string, which is then written as:
+  ```
+  REPORT=line1
+  line2
+  line3
+  ```
+  The runner reads the first newline as end-of-value for `REPORT`, then tries to parse `line2`
+  as a new key=value entry (which fails silently or errors). The downstream step reading
+  `${{ steps.id.outputs.REPORT }}` receives only `line1` — or an empty string if the parser
+  rejects the entry entirely.
+
+  This is a **silent failure** because the workflow step itself does not fail — the `echo`
+  command exits successfully. The broken output only surfaces downstream, often as an empty
+  variable or a truncated value that's hard to trace back to the output-setting step.
+
+  The same issue affects `$GITHUB_ENV` for multiline environment variable values.
+fix: |
+  Use the **heredoc (multi-line delimiter) syntax** documented by GitHub for multiline values.
+  The format is:
+  ```
+  {name}<<{delimiter}
+  {value}
+  {delimiter}
+  ```
+  where `{delimiter}` is any string that does NOT appear in the value itself. `EOF` is the
+  conventional choice, but using a random string (e.g. `$(uuidgen)`) prevents injection
+  attacks if the value is untrusted.
+
+  **For `$GITHUB_ENV` multiline values:** use the identical heredoc pattern with `$GITHUB_ENV`.
+
+  **For JavaScript/TypeScript actions:** use `core.setOutput('name', value)` from
+  `@actions/core` — it handles serialization automatically and is not subject to this limitation.
+fix_code:
+  - language: yaml
+    label: "Correct multiline GITHUB_OUTPUT using heredoc EOF syntax"
+    code: |
+      - name: Set multiline output
+        id: report
+        run: |
+          # WRONG: echo "REPORT=$(cat report.txt)" >> $GITHUB_OUTPUT
+          # Correct: heredoc syntax
+          echo "REPORT<<EOF" >> $GITHUB_OUTPUT
+          cat report.txt >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
+
+      - name: Use multiline output
+        run: |
+          echo "${{ steps.report.outputs.REPORT }}"
+  - language: yaml
+    label: "Use random delimiter to prevent injection from untrusted content"
+    code: |
+      - name: Set multiline output safely
+        id: data
+        run: |
+          DELIMITER=$(openssl rand -hex 16)
+          echo "JSON_OUTPUT<<${DELIMITER}" >> $GITHUB_OUTPUT
+          curl -s https://api.example.com/data >> $GITHUB_OUTPUT
+          echo "${DELIMITER}" >> $GITHUB_OUTPUT
+  - language: yaml
+    label: "Multiline GITHUB_ENV using heredoc (same pattern)"
+    code: |
+      - name: Set multiline environment variable
+        run: |
+          echo "CHANGELOG<<EOF" >> $GITHUB_ENV
+          git log --oneline -10 >> $GITHUB_ENV
+          echo "EOF" >> $GITHUB_ENV
+prevention:
+  - "Never use `echo \"KEY=$(command)\" >> $GITHUB_OUTPUT` when the command output may span multiple lines."
+  - "Always use the heredoc EOF syntax for any output value that could contain newlines: `echo \"KEY<<EOF\" >> $GITHUB_OUTPUT && <value> >> $GITHUB_OUTPUT && echo \"EOF\" >> $GITHUB_OUTPUT`."
+  - "Use a random delimiter (`$(openssl rand -hex 16)`) instead of `EOF` when the value originates from untrusted input to prevent delimiter injection."
+  - "In JavaScript/TypeScript actions, use `@actions/core`'s `core.setOutput()` which handles serialization automatically."
+  - "Test multiline outputs locally with `act` or by printing `cat $GITHUB_OUTPUT` in a subsequent step to verify the full value was captured."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#multiline-strings"
+    label: "GitHub Docs: Workflow commands — Multiline strings"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/passing-information-between-jobs"
+    label: "GitHub Docs: Passing information between jobs"
+  - url: "https://github.blog/changelog/2022-10-11-github-actions-deprecating-save-state-and-set-output-commands/"
+    label: "GitHub Changelog: Deprecating save-state and set-output commands"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@htekdev/actions-debugger",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "65+ real GitHub Actions errors, queryable by agents. MCP server + Copilot skills + error database.",
   "type": "module",
   "main": "./dist/index.js",