@htekdev/actions-debugger 1.0.23 → 1.0.24

package/errors/runner-environment/powershell-74-76-threadjob-module-rename.yml

@@ -0,0 +1,124 @@
+id: runner-environment-063
+title: "PowerShell 7.4 → 7.6 LTS Upgrade Breaks ThreadJob Module Name and .NET Runtime"
+category: runner-environment
+severity: warning
+tags:
+  - powershell
+  - powershell-76
+  - threadjob
+  - dotnet10
+  - runner-images
+  - breaking-change
+  - module
+patterns:
+  - regex: "The term 'ThreadJob\\\\Start-ThreadJob' is not recognized"
+    flags: "i"
+  - regex: "CommandNotFoundException.*ThreadJob"
+    flags: "i"
+  - regex: "Cannot find module.*ThreadJob"
+    flags: "i"
+  - regex: "Join-Path.*cannot process argument transformation on parameter 'ChildPath'"
+    flags: "i"
+  - regex: "PowerShell.*7\\.4.*not found"
+    flags: "i"
+error_messages:
+  - "The term 'ThreadJob\\Start-ThreadJob' is not recognized as a name of a cmdlet, function, script file, or executable program."
+  - "Cannot find module ThreadJob"
+  - "Join-Path: Cannot process argument transformation on parameter 'ChildPath'."
+  - "Get-Module: The specified module 'ThreadJob' was not found"
+root_cause: |
+  GitHub Actions runner images are being updated from PowerShell 7.4.x to 7.6.x
+  (the latest LTS release, based on .NET 10) across all runner images between
+  June 8–15, 2026 (runner-images#14150). PowerShell 7.6 is a major.minor
+  version upgrade from 7.4 and contains several breaking changes:
+
+  1. **ThreadJob module renamed**: The `ThreadJob` module has been replaced by
+     `Microsoft.PowerShell.ThreadJob`. The `Start-ThreadJob` cmdlet itself is
+     unchanged, but any script using the module-qualified name
+     `ThreadJob\Start-ThreadJob` will throw a CommandNotFoundException because
+     the old module name no longer exists. Scripts that call `Start-ThreadJob`
+     without the module prefix continue to work.
+
+  2. **Join-Path -ChildPath is now string[]**: The `-ChildPath` parameter type
+     changed from `string` to `string[]`. In most cases this is backward-
+     compatible, but scripts with unusual argument binding patterns or that
+     pass a typed `[string]` variable explicitly may encounter parameter
+     transformation errors.
+
+  3. **.NET 10 runtime**: PowerShell 7.6 ships on .NET 10 (7.4 was on .NET 8).
+     Scripts that load .NET assemblies, use P/Invoke, or invoke .NET API
+     members that changed between .NET 8 and .NET 10 may break silently
+     or throw runtime exceptions.
+
+  4. **WildcardPattern.Escape behavior change**: `WildcardPattern.Escape` now
+     correctly escapes lone backticks. Scripts that relied on the old (incorrect)
+     no-escape behavior may produce different wildcard pattern results.
+
+  5. **Trailing space removed from event source name**: Scripts that match
+     exact event source names (e.g., for Windows Event Log) may fail to find
+     the source if they include a trailing space.
+fix: |
+  1. Replace module-qualified ThreadJob references:
+     Find all occurrences of `ThreadJob\Start-ThreadJob` in your scripts and
+     update them to `Microsoft.PowerShell.ThreadJob\Start-ThreadJob` or simply
+     use the unqualified `Start-ThreadJob`.
+
+  2. Review Join-Path usage:
+     Scripts using `Join-Path` with `-ChildPath` should continue to work in
+     most cases. If you see parameter binding errors, check that you are not
+     passing a typed `[string]` variable in a context that is now ambiguous.
+
+  3. Test .NET assembly loading:
+     If your scripts load .NET assemblies via `Add-Type -Path` or
+     `[System.Reflection.Assembly]::LoadFrom()`, test them against .NET 10
+     to catch any API compatibility issues before the upgrade rolls out.
+
+  4. Pin PowerShell version (temporary workaround):
+     Until migration is complete, you can install a specific PowerShell version
+     via the MSI/package manager in a workflow step. This is a temporary
+     workaround and should not be the long-term solution.
+fix_code:
+  - language: yaml
+    label: "Fix module-qualified ThreadJob reference"
+    code: |
+      # Before (PowerShell 7.4 — breaks on 7.6):
+      # $job = ThreadJob\Start-ThreadJob -ScriptBlock { ... }
+      #
+      # After (works on both 7.4 and 7.6):
+      - name: Run threaded job
+        shell: pwsh
+        run: |
+          # Option A: unqualified (works on all versions)
+          $job = Start-ThreadJob -ScriptBlock { Get-Process }
+          
+          # Option B: fully qualified with new module name (7.6+)
+          $job = Microsoft.PowerShell.ThreadJob\Start-ThreadJob -ScriptBlock { Get-Process }
+          
+          $result = $job | Wait-Job | Receive-Job
+          Write-Output $result
+  - language: yaml
+    label: "Verify PowerShell version in workflow to detect future upgrades early"
+    code: |
+      - name: Check PowerShell version
+        shell: pwsh
+        run: |
+          $version = $PSVersionTable.PSVersion
+          Write-Output "PowerShell version: $version"
+          if ($version.Major -lt 7 -or ($version.Major -eq 7 -and $version.Minor -lt 6)) {
+            Write-Warning "PowerShell < 7.6 detected — ensure ThreadJob references use unqualified names"
+          }
+prevention:
+  - "Use unqualified cmdlet names (Start-ThreadJob, not ThreadJob\\Start-ThreadJob) to avoid module-name dependencies."
+  - "Add a PowerShell version check step at the start of complex pwsh workflows to detect unexpected upgrades early."
+  - "Test workflows against the next PowerShell LTS version in a matrix before the runner image upgrade lands."
+  - "Subscribe to GitHub notifications on actions/runner-images to receive Announcement issues for upcoming breaking changes."
+  - "Avoid loading .NET assemblies by absolute path in runner workflows — prefer NuGet package installation to ensure .NET runtime compatibility."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/14150"
+    label: "runner-images #14150: PowerShell will be updated from 7.4 to 7.6 LTS (Jun 8-15 2026)"
+  - url: "https://learn.microsoft.com/en-us/powershell/scripting/whats-new/what-s-new-in-powershell-76"
+    label: "PowerShell 7.6 Release Notes — breaking changes"
+  - url: "https://github.com/PowerShell/PowerShell/releases/tag/v7.6.0"
+    label: "PowerShell v7.6.0 GitHub release"
+  - url: "https://learn.microsoft.com/en-us/powershell/scripting/install/powershell-support-lifecycle"
+    label: "PowerShell support lifecycle"

package/errors/runner-environment/self-hosted-runner-not-found.yml

@@ -0,0 +1,134 @@
+id: runner-environment-067
+title: "Self-Hosted Runner 'An error occurred: Runner not found'"
+category: runner-environment
+severity: error
+tags:
+  - self-hosted
+  - runner
+  - runner-not-found
+  - jit
+  - registration
+  - ephemeral
+patterns:
+  - regex: "An error occurred: Runner not found"
+    flags: "i"
+  - regex: "Runner not found"
+    flags: "i"
+  - regex: "No runner matching the specified criteria was found"
+    flags: "i"
+  - regex: "Could not find any runner that matches the selector"
+    flags: "i"
+error_messages:
+  - "An error occurred: Runner not found"
+  - "Error: An error occurred: Runner not found"
+  - "No runner matching the specified criteria was found"
+root_cause: |
+  "An error occurred: Runner not found" is a vague error emitted by the
+  GitHub Actions broker when it cannot match or allocate a self-hosted runner
+  for a queued job. It has multiple distinct root causes:
+
+  1. **JIT (Just-in-Time) token expiry** (most common with ARC/Kubernetes runners):
+     Ephemeral runners provisioned via Just-in-Time tokens have a short registration
+     window. If the runner process does not connect within the token validity period
+     (~60 seconds), the broker discards the registration and emits "Runner not found"
+     when the job is dispatched. This particularly affects actions-runner-controller
+     (ARC) on Kubernetes when pod startup time exceeds the JIT window.
+
+  2. **Runner de-registered before job starts**:
+     Autoscaling controllers (ARC, custom scripts) that aggressively recycle idle
+     runners may de-register the runner in the brief window between job queue and
+     job dispatch. The broker finds no runner for the job's labels.
+
+  3. **Label mismatch**:
+     The workflow specifies `runs-on: [self-hosted, linux, x64]` but the registered
+     runner has different labels (e.g., just `[self-hosted, linux]`). The broker
+     treats this as "no matching runner found" and emits the same vague error.
+
+  4. **Runner registered at wrong scope**:
+     A runner registered at the organization level is not visible to a repository
+     not in that runner's group, or vice versa. Org runner group access policy
+     may restrict which repos can use the runner.
+
+  5. **Concurrent job stealing**:
+     In autoscaling pools where multiple runners share the same label set, a
+     job token issued to one runner is occasionally "stolen" by another — the
+     original runner's job token is invalid when it tries to start. Less common
+     but documented in high-concurrency pools (actions/runner#3857, 116 reactions).
+
+  The error is intentionally vague because it covers multiple broker-side failures
+  that are indistinguishable from the runner's perspective.
+fix: |
+  Diagnose by checking the runner registration logs first:
+
+  1. **For JIT token expiry (ARC/Kubernetes)**:
+     Reduce pod startup time — use pre-pulled images, smaller base images, or
+     warm pools. Alternatively, switch to Long-Running runners (PAT/App-registered)
+     which don't have JIT token windows. Check actions-runner-controller v0.9+
+     which extended the JIT window.
+
+  2. **For de-registered runner race condition**:
+     Add a grace period to your autoscaler before de-registering idle runners —
+     at least 60 seconds after a job completes. Use `--once` flag on ephemeral
+     runners so they only exit after completing one job, not before.
+
+  3. **For label mismatch**:
+     Run `gh api repos/{owner}/{repo}/actions/runners --jq '.[].labels'` to inspect
+     registered runner labels. Compare against the `runs-on:` in your workflow.
+     Labels are case-sensitive and must be an exact subset match.
+
+  4. **For wrong scope (org vs repo)**:
+     Check Settings → Actions → Runners in both the repo and org. Confirm the
+     runner appears under the correct scope and the runner group allows access
+     to the repository.
+
+  5. **General debugging**:
+     Enable runner diagnostic logs by setting `ACTIONS_RUNNER_DEBUG: true` and
+     `ACTIONS_STEP_DEBUG: true` as repository secrets. This enables verbose
+     broker negotiation logs in the Actions runner output.
+fix_code:
+  - language: yaml
+    label: "Enable runner diagnostic logs to capture broker negotiation details"
+    code: |
+      # Add these as repository secrets (Settings → Secrets → Actions):
+      # ACTIONS_RUNNER_DEBUG = true
+      # ACTIONS_STEP_DEBUG = true
+
+      # Then re-run the failing job. The runner logs will include:
+      # "Checking runner for labels: [self-hosted, linux, x64]"
+      # "Connected to GitHub Actions service"
+      # "Received job assignment: ..."
+      jobs:
+        build:
+          runs-on: [self-hosted, linux, x64]
+          steps:
+            - uses: actions/checkout@v4
+            - run: echo "Runner labels verified"
+  - language: yaml
+    label: "Verify registered runner labels via GitHub API"
+    code: |
+      # Check what labels your self-hosted runners actually have:
+      # gh api repos/{owner}/{repo}/actions/runners --jq '.runners[] | {name: .name, labels: [.labels[].name]}'
+      # Example output:
+      # {"name": "my-runner", "labels": ["self-hosted", "Linux", "X64"]}
+      # Note: Labels are case-sensitive — "Linux" != "linux"
+
+      # Workflow label must match runner label exactly:
+      jobs:
+        build:
+          # Use exact case matching the runner's registered labels:
+          runs-on: [self-hosted, Linux, X64]
+prevention:
+  - "Use explicit, versioned runner labels instead of generic `self-hosted` to make label mismatches immediately visible in the runner registration."
+  - "For ephemeral/JIT runners on Kubernetes, use pre-pulled base images and resource requests that ensure fast pod startup to avoid JIT token expiry."
+  - "Add ACTIONS_RUNNER_DEBUG=true as a repository secret during initial setup to capture detailed registration logs before the runner goes into production."
+  - "Implement health monitoring on your self-hosted runner pool — alert when the runner count drops below the minimum needed for your queue depth."
+  - "Prefer Long-Running runners over JIT ephemeral runners for workflows with unpredictable startup patterns — JIT token windows are unforgiving on slow infrastructure."
+docs:
+  - url: "https://github.com/actions/runner/issues/3857"
+    label: "actions/runner #3857: 'An error occurred: Runner not found' (116 reactions)"
+  - url: "https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/monitoring-and-troubleshooting-self-hosted-runners"
+    label: "GitHub Docs: Monitoring and troubleshooting self-hosted runners"
+  - url: "https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/using-labels-with-self-hosted-runners"
+    label: "GitHub Docs: Using labels with self-hosted runners"
+  - url: "https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions#hardening-for-self-hosted-runners"
+    label: "GitHub Docs: Security hardening for self-hosted runners"

package/errors/runner-environment/self-hosted-runner-selinux-service-exec-failure.yml

@@ -0,0 +1,116 @@
+id: runner-environment-068
+title: "Self-Hosted Runner Service Fails on RHEL/CentOS — SELinux Blocks runsvc.sh with status=203/EXEC"
+category: runner-environment
+severity: error
+tags:
+  - self-hosted
+  - selinux
+  - rhel
+  - centos
+  - oracle-linux
+  - service
+  - systemd
+patterns:
+  - regex: "status=203/EXEC|code=exited.*status=203"
+    flags: "i"
+  - regex: "runsvc\\.sh.*failed|svc\\.sh.*start.*fail|runner.*service.*203"
+    flags: "i"
+  - regex: "avc.*denied.*runner|selinux.*denied.*exec.*runsvc"
+    flags: "i"
+error_messages:
+  - "Active: failed (Result: exit-code)"
+  - "Main PID: XXXX (code=exited, status=203/EXEC)"
+  - "Failed to execute: Permission denied"
+  - "svc install succeeded but svc start exits immediately with status=203/EXEC"
+root_cause: |
+  On SELinux-enforcing Linux distributions (RHEL, CentOS, Oracle Linux, AlmaLinux,
+  Rocky Linux), the GitHub Actions self-hosted runner service fails to start with
+  systemd exit code 203/EXEC when run via sudo ./svc.sh start.
+
+  The root cause is a SELinux security context mismatch:
+  1. GitHub's ./config.sh creates runsvc.sh and run.sh with the security context
+     of the installing user's SSH/interactive session (e.g., unconfined_u:object_r:user_home_t:s0).
+  2. When systemd launches the service, it executes the script in a more restricted
+     domain context. SELinux enforces that service scripts must have a context
+     allowing execution from the systemd context.
+  3. The user_home_t label applied during installation does not permit execution by
+     systemd, so the exec() syscall is denied before the process can start.
+  4. Running ./run.sh directly in an interactive shell works because interactive
+     shells run in a more permissive SELinux context that allows user_home_t exec.
+
+  Exit code 203/EXEC specifically means systemd failed during exec() — not during
+  runtime — confirming SELinux is the blocker rather than a configuration or
+  dependency issue.
+fix: |
+  Apply the correct SELinux security context to the runner service scripts using
+  the chcon command. The usr_t type permits execution by systemd service contexts.
+
+  Step 1 — Fix runsvc.sh context (required):
+    cd /path/to/runner
+    sudo chcon system_u:object_r:usr_t:s0 runsvc.sh
+
+  Step 2 — Fix run.sh context (required if service starts but crashes immediately):
+    sudo chcon system_u:object_r:usr_t:s0 run.sh
+
+  Step 3 — Start the service:
+    sudo ./svc.sh start
+    sudo ./svc.sh status   # Should show: Active: active (running)
+
+  For persistent context that survives runner upgrades and ./config.sh reinstalls,
+  use semanage fcontext to write the context rule permanently. This requires the
+  policycoreutils-python-utils package.
+fix_code:
+  - language: yaml
+    label: "Fix SELinux context — run these commands on the host (not in workflow)"
+    code: |
+      # Navigate to the runner installation directory
+      cd /home/github-runner/actions-runner
+
+      # Step 1: Fix runsvc.sh SELinux context (required)
+      sudo chcon system_u:object_r:usr_t:s0 runsvc.sh
+
+      # Step 2: Fix run.sh as well (needed if service crashes immediately after start)
+      sudo chcon system_u:object_r:usr_t:s0 run.sh
+
+      # Step 3: Start the runner service
+      sudo ./svc.sh start
+
+      # Step 4: Verify the service is running
+      sudo ./svc.sh status
+      # Expected output: Active: active (running)
+
+  - language: yaml
+    label: "Persistent SELinux context via semanage (survives reinstalls)"
+    code: |
+      # Install policycoreutils-python-utils if semanage is not available
+      # sudo dnf install policycoreutils-python-utils
+
+      RUNNER_DIR="/home/github-runner/actions-runner"
+
+      # Add permanent file context rules
+      sudo semanage fcontext -a -t usr_t "${RUNNER_DIR}/runsvc.sh"
+      sudo semanage fcontext -a -t usr_t "${RUNNER_DIR}/run.sh"
+
+      # Apply rules to existing files
+      sudo restorecon -v "${RUNNER_DIR}/runsvc.sh"
+      sudo restorecon -v "${RUNNER_DIR}/run.sh"
+
+      # Verify contexts are set correctly
+      ls -lZ "${RUNNER_DIR}/runsvc.sh" "${RUNNER_DIR}/run.sh"
+      # Expected: system_u:object_r:usr_t:s0
+
+      # Start the runner service
+      sudo ./svc.sh start
+prevention:
+  - "After ./config.sh on SELinux-enforcing systems, always run chcon on runsvc.sh before ./svc.sh start."
+  - "Use semanage fcontext for persistent context that survives runner upgrades and reinstalls."
+  - "Add chcon steps to your runner provisioning runbooks and Ansible/Terraform automation."
+  - "Verify SELinux denials with: sudo ausearch -m avc -ts recent | grep runner"
+  - "Consider using the RHEL runner container image which handles SELinux context automatically."
+docs:
+  - url: "https://stackoverflow.com/questions/71818706/github-self-hosted-runner-fails-to-run-as-a-service-on-rh-linux"
+    label: "Stack Overflow: Self-hosted runner fails as service on RH Linux (17-vote answer)"
+  - url: "https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/configuring-the-self-hosted-runner-application-as-a-service"
+    label: "GitHub Docs: Configuring the self-hosted runner as a service"
+  - url: "https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/8/html/using_selinux/changing-selinux-contexts_using-selinux"
+    label: "Red Hat Docs: Changing SELinux file contexts with chcon"

package/errors/runner-environment/service-container-no-healthcheck.yml

@@ -0,0 +1,158 @@
+id: runner-environment-066
+title: "Service Container Unhealthy — No Healthcheck Causes Job to Run Before Container Is Ready"
+category: runner-environment
+severity: error
+tags:
+  - service-container
+  - postgres
+  - mysql
+  - redis
+  - healthcheck
+  - docker
+  - connection-refused
+patterns:
+  - regex: "db service is unhealthy"
+    flags: "i"
+  - regex: "(?:postgres|mysql|redis|service).*(?:unhealthy|not ready|failed to start)"
+    flags: "i"
+  - regex: "One or more containers failed to start"
+    flags: "i"
+  - regex: "Connection refused.*(?:5432|3306|6379)"
+    flags: "i"
+  - regex: "could not connect to server.*Connection refused"
+    flags: "i"
+  - regex: "ECONNREFUSED.*(?:5432|3306|6379)"
+    flags: "i"
+error_messages:
+  - "Failed to initialize, db service is unhealthy."
+  - "One or more containers failed to start."
+  - "Error: connect ECONNREFUSED 127.0.0.1:5432"
+  - "could not connect to server: Connection refused"
+  - "Is the server running on that host and accepting TCP/IP connections on port 5432?"
+  - "ERROR 2002 (HY000): Can't connect to MySQL server on '127.0.0.1' (111)"
+root_cause: |
+  GitHub Actions starts service containers (defined under `services:`) before
+  job steps begin, but it does NOT wait for the container's internal process to
+  be fully ready unless a healthcheck is configured. The runner only waits for
+  the container to be in a running state — not for the database or service
+  inside to accept connections.
+
+  Databases like PostgreSQL, MySQL, and Redis typically take several seconds
+  after the container starts before they are ready to accept connections. Without
+  a healthcheck configured via the `options:` key, GitHub Actions proceeds to
+  run job steps immediately while the service is still initializing. The first
+  step that attempts a database connection will fail with "Connection refused"
+  or "service is unhealthy."
+
+  Common misconfiguration patterns:
+  1. No `options:` block at all — the service starts but the job doesn't wait
+     for readiness. The runner polls the healthcheck status if one is present.
+  2. Wrong healthcheck command — using `pg_isready` without the correct user/host
+     flags, or using `mysqladmin ping` without the correct credentials.
+  3. Insufficient retries/timeouts — using `--health-retries 1` means a single
+     failed attempt marks the container unhealthy immediately.
+  4. Port not mapped — the `ports:` key is optional when running steps directly
+     on the runner (accessing via 127.0.0.1), but is required when steps run
+     inside a container.
+
+  Note: Even with a healthcheck, the DB container can transiently fail the
+  healthcheck during slow GH-hosted runner provisioning. Default values of
+  `--health-interval 10s --health-timeout 5s --health-retries 5` work for
+  most cases, but MySQL/MariaDB may need longer retries during first initialization.
+fix: |
+  Add a `options:` block to your service definition with a proper Docker
+  healthcheck command. GitHub Actions reads the container's healthcheck status
+  and waits until the container reports "healthy" before starting job steps.
+
+  PostgreSQL:
+    Use `pg_isready` with `-h localhost` and the correct username.
+
+  MySQL/MariaDB:
+    Use `mysqladmin ping` with credentials matching the MYSQL_ROOT_PASSWORD.
+
+  Redis:
+    Use `redis-cli ping` — returns PONG when Redis is ready.
+
+  If the container is still failing, increase `--health-retries` and
+  `--health-start-period` to give the container more initialization time.
+  MySQL in particular needs a longer start period on its first run because it
+  initializes the data directory.
+fix_code:
+  - language: yaml
+    label: "PostgreSQL service with proper healthcheck"
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          services:
+            postgres:
+              image: postgres:16
+              env:
+                POSTGRES_USER: testuser
+                POSTGRES_PASSWORD: testpass
+                POSTGRES_DB: testdb
+              ports:
+                - 5432:5432
+              options: >-
+                --health-cmd pg_isready
+                --health-interval 10s
+                --health-timeout 5s
+                --health-retries 5
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm test
+              env:
+                DATABASE_URL: postgresql://testuser:testpass@localhost:5432/testdb
+  - language: yaml
+    label: "MySQL service with proper healthcheck"
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          services:
+            mysql:
+              image: mysql:8.0
+              env:
+                MYSQL_ROOT_PASSWORD: rootpass
+                MYSQL_DATABASE: testdb
+              ports:
+                - 3306:3306
+              options: >-
+                --health-cmd "mysqladmin ping -h 127.0.0.1 -u root -prootpass"
+                --health-interval 10s
+                --health-timeout 5s
+                --health-retries 10
+                --health-start-period 30s
+  - language: yaml
+    label: "Redis service with proper healthcheck"
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          services:
+            redis:
+              image: redis:7
+              ports:
+                - 6379:6379
+              options: >-
+                --health-cmd "redis-cli ping"
+                --health-interval 10s
+                --health-timeout 5s
+                --health-retries 5
+prevention:
+  - "Always add a `options: --health-cmd ...` block to every service container — the runner will wait for 'healthy' status before running steps."
+  - "Use `--health-start-period 30s` for MySQL/MariaDB which initializes its data directory on the first run and takes longer than PostgreSQL or Redis."
+  - "Test your healthcheck command locally with `docker run --health-cmd ...` to verify it exits 0 when the service is ready."
+  - "Use `ports: - 5432:5432` when steps run directly on the runner host (ubuntu-latest); ports are optional when steps run in a container job."
+  - "Avoid hardcoded `sleep 30` workarounds — these waste time on fast machines and still fail on slow ones. Use healthchecks instead."
+docs:
+  - url: "https://docs.github.com/en/actions/use-cases-and-examples/creating-postgresql-service-containers"
+    label: "GitHub Docs: Creating PostgreSQL service containers"
+  - url: "https://docs.github.com/en/actions/use-cases-and-examples/creating-redis-service-containers"
+    label: "GitHub Docs: Creating Redis service containers"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/running-jobs-in-a-container"
+    label: "GitHub Docs: Running jobs in a container (services section)"
+  - url: "https://stackoverflow.com/questions/60618118/docker-postgres-image-failed-to-initialize-db-service-is-unhealthy"
+    label: "Stack Overflow #60618118: db service is unhealthy (25 votes, 8.8K views)"
+  - url: "https://github.com/orgs/community/discussions/27021"
+    label: "GitHub Community #27021: MySQL service never comes up healthy"

package/errors/runner-environment/setup-node-v5-corepack-pnpm-not-found.yml

@@ -0,0 +1,101 @@
+id: runner-environment-060
+title: "setup-node@v5 Cannot Locate pnpm After Corepack Enable"
+category: runner-environment
+severity: error
+tags:
+  - setup-node
+  - pnpm
+  - corepack
+  - v5
+  - package-manager
+patterns:
+  - regex: "Unable to locate executable file: pnpm"
+    flags: "i"
+  - regex: "actions/setup-node@[a-z0-9]+ # v5"
+    flags: "i"
+  - regex: "package-manager-cache: true"
+    flags: "i"
+error_messages:
+  - "Error: Unable to locate executable file: pnpm. Please verify either the file path exists or the file can be found within a directory specified by the PATH environment variable. Also check the file mode to verify the file is executable."
+root_cause: |
+  `actions/setup-node@v5` changed how corepack and package manager shims are
+  initialized compared to v4. In v5, the action enables `package-manager-cache: true`
+  by default and reads the `packageManager` field from `package.json` to configure
+  corepack, but it no longer automatically activates corepack shims for the pnpm
+  binary in the runner's PATH.
+
+  In v4, setup-node would run `corepack enable` implicitly as part of its package
+  manager setup, making pnpm available immediately after the action. In v5 this
+  behavior changed: corepack is configured for caching purposes but pnpm shims are
+  not written into PATH, so any subsequent `corepack enable` or direct `pnpm`
+  invocation fails with "Unable to locate executable file: pnpm."
+
+  The issue is specific to v5 because the internal action scripts now use Node 24
+  and a refactored corepack integration path that treats corepack enablement as
+  separate from the shim installation step.
+
+  Downgrading to `actions/setup-node@v4` restores the previous behavior where pnpm
+  shims are automatically available after the action.
+fix: |
+  Use `pnpm/action-setup` BEFORE `actions/setup-node` to install pnpm independently
+  of corepack shim management. This is the officially recommended pattern for pnpm
+  on GitHub-hosted runners and works correctly with both v4 and v5 of setup-node.
+
+  Alternatively, pin to `actions/setup-node@v4` until setup-node@v5 resolves the
+  corepack shim regression.
+
+  Do NOT rely on `corepack enable` run after setup-node@v5 to make pnpm available —
+  the shim is not written even after corepack is enabled in a subsequent step.
+fix_code:
+  - language: yaml
+    label: "Wrong: setup-node@v5 + corepack enable (pnpm not found)"
+    code: |
+      steps:
+        - uses: actions/checkout@v4
+        - uses: actions/setup-node@v5   # v5 does not write pnpm shim
+          with:
+            node-version-file: package.json
+        - run: |
+            corepack enable             # pnpm still not in PATH after this
+            corepack prepare --activate
+        - run: pnpm install             # Error: Unable to locate executable file: pnpm
+  - language: yaml
+    label: "Correct: pnpm/action-setup before setup-node (works with v4 and v5)"
+    code: |
+      steps:
+        - uses: actions/checkout@v4
+        - uses: pnpm/action-setup@v4    # install pnpm FIRST, independent of corepack
+          with:
+            version: 10
+        - uses: actions/setup-node@v5
+          with:
+            node-version-file: package.json
+            cache: pnpm
+        - run: pnpm install --frozen-lockfile
+  - language: yaml
+    label: "Alternative: pin to setup-node@v4 (restores previous corepack behavior)"
+    code: |
+      steps:
+        - uses: actions/checkout@v4
+        - uses: actions/setup-node@v4   # v4 writes corepack shims automatically
+          with:
+            node-version-file: package.json
+        - run: |
+            corepack enable
+            corepack prepare --activate
+        - run: pnpm install --frozen-lockfile
+prevention:
+  - "Use pnpm/action-setup before setup-node for reliable pnpm availability regardless of setup-node version."
+  - "Do not assume corepack shim behavior is identical between setup-node major versions."
+  - "Pin action versions with SHAs (e.g. @a0853c24...) to avoid unexpected behavior changes on major bumps."
+  - "Read setup-node release notes and CHANGELOG when upgrading from v4 to v5 — corepack integration changed."
+  - "Test pnpm availability explicitly in CI by adding a debug step: run: which pnpm && pnpm --version"
+docs:
+  - url: "https://github.com/actions/setup-node/issues/1357"
+    label: "actions/setup-node#1357: v5 fails immediately when using pnpm (31 reactions)"
+  - url: "https://github.com/pnpm/action-setup"
+    label: "pnpm/action-setup: Official pnpm GitHub Action"
+  - url: "https://nodejs.org/api/corepack.html"
+    label: "Node.js Corepack documentation"
+  - url: "https://github.com/actions/setup-node/releases"
+    label: "actions/setup-node releases and CHANGELOG"