@htekdev/actions-debugger 1.0.29 → 1.0.31

package/errors/known-unsolved/input-unset-vs-empty-string.yml

@@ -0,0 +1,78 @@
+id: 'known-unsolved-030'
+title: 'core.getInput cannot distinguish unset input from explicitly-empty input'
+category: known-unsolved
+severity: limitation
+tags:
+  - toolkit
+  - core-getInput
+  - composite-action
+  - empty-string
+  - null-input
+  - fork-secrets
+patterns:
+  - regex: 'core\.getInput\('
+    flags: 'i'
+error_messages:
+  - 'No way to detect if input was provided vs set to empty string'
+root_cause: |
+  The `core.getInput(name)` function in `@actions/core` always returns an empty string ('')
+  when an input is either not provided by the caller or explicitly set to the empty string.
+  There is no `core.hasInput(name)` API or other mechanism to distinguish these two cases.
+
+  This creates several practical problems for action authors:
+  - A required input set to '' passes the required: true check in getInput but is semantically absent
+  - Fork pull requests inject secrets as empty strings (secrets are unavailable); an action cannot tell
+    if a secret input was omitted vs provided-as-empty-because-fork
+  - Composite action callers cannot express "I intentionally leave this blank" vs "I don't provide this at all"
+  - YAML null or ~ values (e.g., with: my_val: ~) are coerced to '' by the runner before the action sees them
+
+  Upstream GitHub toolkit issue #940 has been open since 2022 with 22 upvotes and no fix planned.
+fix: |
+  No direct fix exists — there is no core.hasInput() API. Workarounds depend on the use case:
+  - For sentinel detection: document a convention like 'none' or '__unset__' as the explicit absent value
+    and check getInput('x') === 'none'
+  - For fork secret detection: check github.event.pull_request.head.repo.fork == true and gate on that
+    rather than on whether the secret is empty
+  - For optional inputs: provide a well-documented default value in action.yml so callers always get a
+    predictable non-empty string when they omit the input
+  - For composite actions: use ${{ inputs.my_input != '' }} in if: conditions, documenting that
+    callers must pass a non-empty string to opt in
+fix_code:
+  - language: yaml
+    label: 'Use sentinel value convention to detect absent input'
+    code: |
+      # action.yml — declare sentinel default
+      inputs:
+        deploy_env:
+          description: 'Target environment (leave blank to skip deployment)'
+          required: false
+          default: '__unset__'
+
+      # In composite action steps
+      steps:
+        - name: Deploy
+          if: ${{ inputs.deploy_env != '__unset__' && inputs.deploy_env != '' }}
+          run: echo "Deploying to ${{ inputs.deploy_env }}"
+  - language: yaml
+    label: 'Detect fork PR to guard secret-gated steps instead of empty-check'
+    code: |
+      steps:
+        - name: Publish (skip on fork PRs)
+          if: >-
+            ${{ github.event_name != 'pull_request' ||
+                github.event.pull_request.head.repo.full_name == github.repository }}
+          run: echo "$NPM_TOKEN" | npm login --registry https://registry.npmjs.org
+          env:
+            NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+prevention:
+  - 'Document in action.yml that empty string and absent are treated identically by core.getInput'
+  - 'Use a non-empty sentinel default value (e.g. __unset__) instead of relying on empty-check logic'
+  - 'Never gate fork-secret logic on secret emptiness — use fork-detection via event context instead'
+  - 'For required inputs that must be non-empty, add an explicit validation step that fails with a helpful message'
+docs:
+  - url: 'https://github.com/actions/toolkit/issues/940'
+    label: 'actions/toolkit#940: Impossible to detect unset inputs from inputs set as empty string'
+  - url: 'https://github.com/actions/toolkit/tree/main/packages/core'
+    label: 'actions/toolkit core package — getInput API'
+  - url: 'https://docs.github.com/en/actions/sharing-automations/creating-actions/metadata-syntax-for-github-actions#inputs'
+    label: 'GitHub Docs: Action metadata — inputs'

package/errors/permissions-auth/tj-actions-changed-files-supply-chain-cve-2025-30066.yml

@@ -0,0 +1,99 @@
+id: 'permissions-auth-030'
+title: 'tj-actions/changed-files supply chain attack exposed CI/CD secrets in workflow logs (CVE-2025-30066)'
+category: permissions-auth
+severity: error
+tags:
+  - supply-chain
+  - tj-actions
+  - changed-files
+  - cve-2025-30066
+  - secrets-exposed
+  - security
+  - third-party-action
+patterns:
+  - regex: 'tj-actions/changed-files@(?:v(?:1|35|44)\b|0e58ed8671d6b60d0890c21b07f8835ace038e67)'
+    flags: 'i'
+  - regex: '(?:memdump\.py|gist\.githubusercontent\.com/nikitastupin)'
+    flags: 'i'
+error_messages:
+  - 'Unexpected base64-encoded output in tj-actions/changed-files step logs'
+  - 'Unauthorized outbound request to gist.githubusercontent.com detected in workflow run'
+root_cause: |
+  Between March 14 and March 15, 2025, attackers compromised the tj-actions/changed-files
+  GitHub Action (CVE-2025-30066, GHSA-mw4p-6x4p-x5m5) by retroactively modifying multiple
+  version tags to reference a malicious commit SHA
+  (0e58ed8671d6b60d0890c21b07f8835ace038e67).
+
+  The malicious commit injected a Python script that:
+  1. Downloaded a memory-dump utility from a public GitHub Gist
+  2. Scanned the GitHub Actions Runner Worker process memory for secrets
+  3. Base64-encoded the extracted memory content
+  4. Printed the encoded secrets directly to the workflow log
+
+  For repositories with public workflow logs, these secrets were immediately publicly
+  accessible. Over 23,000 repositories were affected.
+
+  The attack exploited a fundamental trust model weakness: when workflows pin to a version
+  tag (e.g., @v35 or @v44.5.1) rather than a specific commit SHA, an attacker who gains
+  write access to the upstream repository can silently redirect any tag to malicious code.
+  The workflow continues to run without any error — it just also exfiltrates secrets.
+
+  The compromised tags included: v1.0.0, v35.7.7-sec, v44.5.1, and others.
+  The vulnerability window was March 14–15, 2025. Tags have since been updated to safe
+  code, but any secrets exposed during that window must be treated as compromised.
+fix: |
+  Immediate actions if your workflows ran tj-actions/changed-files between March 14-15, 2025:
+  1. Inspect workflow logs for unexpected base64 output in the changed-files step
+  2. Decode any suspicious output: echo 'BLOB' | base64 -d | base64 -d
+  3. Rotate ALL secrets (API keys, tokens, SSH keys, cloud credentials) that were present
+     in any workflow that used the affected action during the vulnerability window
+
+  For all workflows (ongoing prevention):
+  - Pin third-party actions to specific commit SHAs instead of version tags
+  - Use tools like StepSecurity Harden-Runner to detect unexpected outbound network calls
+  - Use tools like pin-github-action or GitHub's allowed-actions list to enforce SHA pinning
+fix_code:
+  - language: yaml
+    label: 'Pin third-party actions to a specific commit SHA instead of a version tag'
+    code: |
+      steps:
+        # Vulnerable: tag can be silently repointed to malicious code
+        # - uses: tj-actions/changed-files@v44
+        # - uses: tj-actions/changed-files@v44.5.1
+
+        # Safe: commit SHA is immutable — attacker cannot redirect it
+        - name: Get changed files
+          id: changed-files
+          uses: tj-actions/changed-files@823fcebdb31bb97eca5b8e3cd20bb12abfa9b68d
+          with:
+            files: |
+              src/**
+  - language: yaml
+    label: 'Use StepSecurity Harden-Runner to detect unauthorized outbound network calls'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Harden runner
+              uses: step-security/harden-runner@v2
+              with:
+                egress-policy: audit   # or 'block' to prevent unauthorized calls
+            - name: Get changed files
+              uses: tj-actions/changed-files@823fcebdb31bb97eca5b8e3cd20bb12abfa9b68d
+prevention:
+  - 'Always pin third-party GitHub Actions to a specific commit SHA, not a version tag'
+  - 'Audit your workflows periodically for version-tagged (not SHA-pinned) third-party actions'
+  - 'Use StepSecurity Harden-Runner or similar tooling to detect anomalous outbound network requests in CI'
+  - 'Subscribe to security advisories for third-party actions your workflows depend on'
+  - 'Rotate secrets immediately if a supply chain compromise is announced for any action you use'
+  - 'Consider using a private action mirror with controlled updates rather than pulling from public repos'
+docs:
+  - url: 'https://github.com/tj-actions/changed-files/security/advisories/GHSA-mw4p-6x4p-x5m5'
+    label: 'GHSA-mw4p-6x4p-x5m5: tj-actions/changed-files supply chain attack advisory'
+  - url: 'https://www.cve.org/CVERecord?id=CVE-2025-30066'
+    label: 'CVE-2025-30066: NVD entry'
+  - url: 'https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions#using-third-party-actions'
+    label: 'GitHub Docs: Security hardening — using third-party actions'
+  - url: 'https://docs.stepsecurity.io/harden-runner/'
+    label: 'StepSecurity Harden-Runner documentation'

package/errors/runner-environment/arc-task-cancelled-pod-eviction.yml

@@ -0,0 +1,90 @@
+id: 'runner-environment-083'
+title: 'Actions Runner Controller pods intermittently fail with "A task was cancelled" during large matrix jobs'
+category: runner-environment
+severity: error
+tags:
+  - arc
+  - kubernetes
+  - matrix
+  - task-cancelled
+  - pod-eviction
+  - self-hosted
+  - keda
+patterns:
+  - regex: 'A task was cancell?ed\.'
+    flags: 'i'
+  - regex: 'The operation was canceled\.'
+    flags: 'i'
+error_messages:
+  - 'Error: A task was cancelled.'
+  - 'Error: The operation was canceled.'
+root_cause: |
+  When using Actions Runner Controller (ARC) to run GitHub Actions on Kubernetes, ephemeral
+  runner pods can be evicted or preempted mid-job by the Kubernetes scheduler, producing
+  a "A task was cancelled" or "The operation was canceled" error with no application-level
+  log output before the failure.
+
+  Common causes:
+  - Kubernetes resource pressure: if a node is under memory or CPU pressure, the kubelet
+    evicts lower-priority pods. ARC runner pods have no PriorityClass by default and are
+    among the first to be evicted
+  - Node autoscaling: Cluster Autoscaler draining nodes for scale-down triggers eviction of
+    runner pods that have been running longer than the scale-down grace period
+  - KEDA queue-length scaling: KEDA scaling down the runner Deployment while jobs are
+    in-flight terminates runner pods before jobs complete
+  - OOM kills: matrix jobs that each consume significant memory can saturate node memory,
+    causing the OOM killer to terminate runner pods
+
+  The issue is especially common with large matrix builds (10+ parallel jobs) because the
+  aggregate resource demand spike can trigger autoscaler or eviction behavior. Because ARC
+  runner pods are ephemeral and have no restart policy, the job is permanently failed when
+  the pod is evicted.
+fix: |
+  Assign a high PriorityClass to ARC runner pods so the Kubernetes scheduler avoids evicting
+  them during resource pressure. Also set adequate resource requests/limits and configure
+  terminationGracePeriodSeconds to at least the expected maximum job duration.
+fix_code:
+  - language: yaml
+    label: 'Create a high-priority PriorityClass for ARC runner pods'
+    code: |
+      apiVersion: scheduling.k8s.io/v1
+      kind: PriorityClass
+      metadata:
+        name: github-runner-high
+      value: 1000000
+      globalDefault: false
+      description: 'High priority for GitHub Actions runner pods to prevent eviction'
+  - language: yaml
+    label: 'Reference PriorityClass and set resource limits in ARC AutoscalingRunnerSet values'
+    code: |
+      # helm values for actions-runner-controller AutoscalingRunnerSet chart
+      template:
+        spec:
+          priorityClassName: github-runner-high
+          # Allow jobs up to 1 hour to finish before pod is force-terminated
+          terminationGracePeriodSeconds: 3600
+          containers:
+            - name: runner
+              resources:
+                requests:
+                  memory: '2Gi'
+                  cpu: '500m'
+                limits:
+                  memory: '4Gi'
+                  cpu: '2000m'
+prevention:
+  - 'Assign a PriorityClass to ARC runner pods to prevent eviction under resource pressure'
+  - 'Set terminationGracePeriodSeconds to at least the expected maximum single-job duration'
+  - 'Set explicit resource requests and limits to avoid OOM kills during large matrix builds'
+  - 'Configure KEDA scale-down stabilization windows to prevent scaling down while jobs run'
+  - 'Monitor node resource utilization and right-size cluster nodes for peak matrix concurrency'
+  - 'Enable PodDisruptionBudgets for runner workloads to reduce involuntary evictions during node drains'
+docs:
+  - url: 'https://github.com/actions/runner/issues/3819'
+    label: 'actions/runner#3819: A lot of random "A task was cancelled" errors'
+  - url: 'https://kubernetes.io/docs/concepts/scheduling-eviction/pod-priority-preemption/'
+    label: 'Kubernetes: Pod Priority and Preemption'
+  - url: 'https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/autoscaling-with-self-hosted-runners'
+    label: 'GitHub Docs: Autoscaling with self-hosted runners'
+  - url: 'https://github.com/actions/actions-runner-controller'
+    label: 'Actions Runner Controller (ARC) GitHub repository'

package/errors/runner-environment/bash-script-path-unquoted-spaces.yml

@@ -0,0 +1,83 @@
+id: 'runner-environment-084'
+title: 'Bash/sh script handler does not quote script path — fails when path contains spaces'
+category: runner-environment
+severity: error
+tags:
+  - bash
+  - shell
+  - path-spaces
+  - job-hooks
+  - self-hosted
+  - macos
+  - tart-vm
+patterns:
+  - regex: 'ACTIONS_RUNNER_HOOK_JOB_(?:STARTED|COMPLETED)'
+    flags: 'i'
+  - regex: 'bash.*No such file or directory'
+    flags: 'i'
+error_messages:
+  - 'bash: /Volumes/My Shared Files/hook.sh: No such file or directory'
+  - 'sh: /path with spaces/script.sh: not found'
+  - '/path/with: not found'
+root_cause: |
+  The GitHub Actions runner bash/sh script handler does not quote the script path
+  placeholder when building the shell invocation. The default bash arguments in
+  ScriptHandlerHelpers.cs are:
+    --noprofile --norc -e -o pipefail {0}
+  When {0} is replaced with a path containing spaces — e.g.,
+    /Volumes/My Shared Files/hook.sh
+  bash receives the path as two separate arguments due to word splitting:
+    bash --noprofile --norc -e -o pipefail /Volumes/My Shared Files/hook.sh
+  This causes a "No such file or directory" error for the first word-split token.
+
+  By contrast, the PowerShell and cmd handlers correctly quote the path:
+    pwsh:       -command "& '{0}'"
+    powershell: -command ". '{0}'"
+    cmd:        /D /E:ON /V:OFF /S /C "CALL "{0}""
+  Only bash and sh are affected (runner#4404, unresolved as of June 2026).
+
+  Practical impact:
+  - Job hooks (ACTIONS_RUNNER_HOOK_JOB_STARTED, ACTIONS_RUNNER_HOOK_JOB_COMPLETED) placed in
+    shared directories with spaces — common on macOS Tart VMs mounted at /Volumes/My Shared Files/
+  - Self-hosted runner workspaces on paths containing spaces (less common but possible)
+  - Any run: step using a working-directory with spaces in the resolved path
+fix: |
+  Ensure hook script paths and runner working directories never contain spaces.
+  On macOS Tart VMs, place hook scripts under a path without spaces (e.g., /Users/runner/hooks/).
+
+  Use a wrapper script at a space-free path that exec-delegates to the actual script if
+  it must reside under a shared mount with spaces in its path.
+
+  Monitor actions/runner#4404 for the upstream fix and upgrade when a patched runner ships.
+fix_code:
+  - language: yaml
+    label: 'Configure job hook at a space-free path (environment variable)'
+    code: |
+      # In the runner .env file (e.g., /home/runner/actions-runner/.env):
+      # Point hook variables to a path WITHOUT spaces
+      ACTIONS_RUNNER_HOOK_JOB_STARTED=/Users/runner/hooks/job-started.sh
+      ACTIONS_RUNNER_HOOK_JOB_COMPLETED=/Users/runner/hooks/job-completed.sh
+      #
+      # Avoid paths like:
+      # /Volumes/My Shared Files/hooks/  ← spaces cause bash word-splitting error
+  - language: yaml
+    label: 'Wrapper script at space-free path delegates to actual hook in shared mount'
+    code: |
+      #!/bin/bash
+      # /Users/runner/hooks/job-started.sh  (space-free path — registered as the hook)
+      #
+      # Exec-delegates to the actual hook that lives under a shared volume with spaces.
+      # Using exec preserves exit codes and avoids a subprocess layer.
+      exec "/Volumes/My Shared Files/hooks/actual-job-started.sh" "$@"
+prevention:
+  - 'Never place runner hooks, workspace paths, or working-directories in paths containing spaces'
+  - 'On macOS Tart VMs, configure shared mounts to use space-free mount points (e.g., /Volumes/SharedFiles)'
+  - 'Test runner hook invocations explicitly on macOS or Windows deployments with shared mounts'
+  - 'Watch actions/runner#4404 for the upstream fix; upgrade the runner version when it ships'
+docs:
+  - url: 'https://github.com/actions/runner/issues/4404'
+    label: 'actions/runner#4404: Bash script handler does not quote script path — breaks with spaces'
+  - url: 'https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/running-scripts-before-or-after-a-job'
+    label: 'GitHub Docs: Running scripts before or after a job (hooks)'
+  - url: 'https://github.com/actions/runner/blob/main/src/Runner.Worker/Handlers/ScriptHandlerHelpers.cs'
+    label: 'Runner source: ScriptHandlerHelpers.cs (unquoted bash path template)'

package/errors/runner-environment/immutable-actions-pkg-domain-not-allowlisted.yml

@@ -0,0 +1,97 @@
+id: 'runner-environment-085'
+title: 'Self-hosted runner fails to download immutable actions — `pkg.actions.githubusercontent.com` not in network allowlist'
+category: runner-environment
+severity: error
+tags:
+  - self-hosted-runner
+  - immutable-actions
+  - network
+  - allowlist
+  - firewall
+  - pkg.actions.githubusercontent.com
+  - action-download
+patterns:
+  - regex: 'Failed to download action.*pkg\.actions\.githubusercontent\.com'
+    flags: 'i'
+  - regex: 'Unable to locate executable.*pkg\.actions\.githubusercontent\.com'
+    flags: 'i'
+  - regex: 'Error: An error occurred while loading the action.*pkg\.actions'
+    flags: 'i'
+  - regex: 'connect(?:ion)? (?:refused|timed? ?out).*pkg\.actions\.githubusercontent\.com'
+    flags: 'i'
+error_messages:
+  - "Error: Failed to download action 'actions/checkout@v4'. Actions requiring immutable action downloads from pkg.actions.githubusercontent.com are blocked."
+  - "Error: An error occurred while loading the action. Connection refused: pkg.actions.githubusercontent.com"
+root_cause: |
+  Starting February 2025, GitHub began migrating GitHub-hosted runners to use
+  "Immutable Actions" — a system where action code is downloaded from a new dedicated
+  CDN host (`pkg.actions.githubusercontent.com`) rather than being cloned directly from
+  the action's GitHub repository.
+
+  Self-hosted runners behind corporate firewalls or with strict network egress allowlists
+  fail to download actions when this new domain is not permitted, causing the job to fail
+  immediately during the action download phase before any user step runs.
+
+  The failure is distinct from a runtime error: the runner itself cannot fetch the action
+  code, so no build output is produced. Logs show a network-level failure during the
+  "Getting action download info" or "Download action repository" phase.
+
+  Organizations that previously configured their allowlist with `*.github.com`,
+  `codeload.github.com`, or `github.com` for action downloads must now also add
+  `pkg.actions.githubusercontent.com`.
+
+  Note: If your allowlist already includes `*.actions.githubusercontent.com`, no change
+  is required — the wildcard matches the new subdomain.
+fix: |
+  Add `pkg.actions.githubusercontent.com` to your self-hosted runner's outbound network
+  allowlist. Runners that already allow `*.actions.githubusercontent.com` via wildcard
+  do not require any change.
+
+  For Azure private networking, also update your NSG template with the additional IP
+  ranges published by GitHub in the February 2025 changelog.
+
+  For GitHub Enterprise Server customers using GitHub Connect: update your self-hosted
+  runner allowlists to include the new domain before enabling immutable actions.
+fix_code:
+  - language: yaml
+    label: 'Required network allowlist domains for self-hosted runners (as of Feb 2025)'
+    code: |
+      # Ensure these domains/IPs are allowed for outbound HTTPS (443) from your runners:
+      #
+      # Existing required domains (unchanged):
+      #   github.com
+      #   api.github.com
+      #   *.actions.githubusercontent.com   <- wildcard covers new subdomain too
+      #   codeload.github.com
+      #   results-receiver.actions.githubusercontent.com
+      #
+      # New domain required for immutable actions (Feb 2025):
+      #   pkg.actions.githubusercontent.com
+      #
+      # If you use domain-specific (not wildcard) allowlists, add:
+      #   pkg.actions.githubusercontent.com
+  - language: yaml
+    label: 'Verify immutable actions network access with a diagnostic step'
+    code: |
+      jobs:
+        network-check:
+          runs-on: [self-hosted]
+          steps:
+            - name: Check immutable actions domain reachability
+              run: |
+                curl -sSf --max-time 10 \
+                  https://pkg.actions.githubusercontent.com \
+                  -o /dev/null -w "HTTP %{http_code}\n" \
+                  || echo "BLOCKED: pkg.actions.githubusercontent.com unreachable"
+prevention:
+  - 'Use wildcard domain entries (`*.actions.githubusercontent.com`) in your network allowlist rather than enumerating specific subdomains'
+  - 'Subscribe to GitHub Changelog (github.blog/changelog) to catch new domain requirements before they cause outages'
+  - 'Periodically run network reachability checks against all required GitHub Actions domains from your runner environment'
+  - 'Document your runner network requirements in runbooks and tie allowlist updates to a change management process'
+docs:
+  - url: 'https://github.blog/changelog/2025-02-12-notice-of-upcoming-deprecations-and-breaking-changes-for-github-actions/'
+    label: 'GitHub Changelog 2025-02-12: Immutable Actions migration and network allowlist updates'
+  - url: 'https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners#communication-between-self-hosted-runners-and-github'
+    label: 'GitHub Docs: Self-hosted runner network communication requirements'
+  - 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-stuck-between-jobs.yml

@@ -0,0 +1,109 @@
+id: 'runner-environment-082'
+title: 'Self-hosted runner gets stuck "Waiting for a runner to pick up this job" between jobs in the same workflow'
+category: runner-environment
+severity: error
+tags:
+  - self-hosted
+  - runner
+  - multi-job
+  - queued
+  - stuck
+  - windows
+  - auto-update
+patterns:
+  - regex: 'Waiting for a runner to pick up this job'
+    flags: 'i'
+error_messages:
+  - 'Waiting for a runner to pick up this job...'
+root_cause: |
+  After completing the first job in a multi-job workflow, a self-hosted runner sometimes
+  fails to pick up subsequent jobs in the same workflow run. The subsequent jobs remain
+  in queued status indefinitely, with no timeout and no automatic retry.
+
+  Common root causes:
+  - Runner auto-update race condition: when the runner auto-updates between jobs, the post-job
+    cleanup of the first job can leave the runner in a state where it reports idle to the
+    broker but cannot accept new job messages
+  - Windows service restart latency: on Windows hosts, if the runner was auto-updated or
+    the service restarted between jobs, the new process may not have fully re-registered
+    with the GitHub Actions broker before the second job is dispatched
+  - JIT token expiry: in ephemeral/JIT runner setups, the registration token can expire
+    between jobs if the first job runs for a long time, and the runner cannot re-register
+  - Broker disconnect: a transient network interruption between jobs severs the long-poll
+    connection; the runner reconnects but the already-dispatched job message is missed
+
+  Manually cancelling and re-running the workflow, or restarting the runner service,
+  resolves the issue immediately, confirming the runner is functional but lost broker contact.
+fix: |
+  Immediate workaround: cancel the stuck workflow run and re-trigger it, or restart the
+  runner service:
+    Windows: Restart-Service "actions.runner.*"
+    Linux:   sudo systemctl restart actions.runner.*.<name>.service
+
+  Long-term fixes:
+  - Disable runner auto-update during active workflows by setting RUNNER_ALLOW_RUNASROOT
+    environment variable and pinning a specific runner version
+  - Use ephemeral runners (--ephemeral flag) so each job dispatches a fresh runner that
+    registers anew with the broker, eliminating the between-job reconnect window
+  - Split long workflows into separate workflow files triggered via workflow_run or
+    repository_dispatch so each workflow gets an independent runner session
+  - On Windows: ensure the runner service account has the "Log on as a service" right
+    and that antivirus is not blocking runner binary updates
+fix_code:
+  - language: yaml
+    label: 'Use ephemeral runners to avoid stuck-between-jobs on self-hosted'
+    code: |
+      # When configuring the runner, use the --ephemeral flag:
+      # ./config.sh --url https://github.com/OWNER/REPO --token TOKEN --ephemeral
+      #
+      # For ARC (Actions Runner Controller), set runnerScaleSetSettings:
+      # spec:
+      #   template:
+      #     metadata:
+      #       labels:
+      #         ephemeral: 'true'
+      #
+      # Each job gets a freshly-registered runner; no between-job broker reconnect issues.
+  - language: yaml
+    label: 'Split multi-job workflow into two workflows triggered by workflow_run'
+    code: |
+      # phase1.yml
+      on:
+        push:
+      jobs:
+        build:
+          runs-on: [self-hosted, linux]
+          steps:
+            - uses: actions/checkout@v4
+            - run: make build
+            - uses: actions/upload-artifact@v4
+              with:
+                name: build-output
+                path: dist/
+
+      # phase2.yml (fresh runner registration — no stuck-between-jobs risk)
+      on:
+        workflow_run:
+          workflows: [phase1.yml]
+          types: [completed]
+      jobs:
+        test:
+          if: ${{ github.event.workflow_run.conclusion == 'success' }}
+          runs-on: [self-hosted, linux]
+          steps:
+            - uses: actions/download-artifact@v4
+              with:
+                name: build-output
+            - run: make test
+prevention:
+  - 'Use ephemeral runners (--ephemeral) to ensure each job gets a fresh broker registration'
+  - 'Configure the runner service with Restart=on-failure to auto-recover from crashes between jobs'
+  - 'Pin runner versions and suppress auto-updates in production to prevent mid-workflow upgrades'
+  - 'Monitor for stuck runs via the GitHub Actions API and alert or auto-cancel them'
+docs:
+  - url: 'https://github.com/actions/runner/issues/3609'
+    label: 'actions/runner#3609: Self-hosted runner stuck on "Waiting for a runner to pick up this job"'
+  - 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'
+  - url: 'https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/autoscaling-with-self-hosted-runners'
+    label: 'GitHub Docs: Autoscaling with self-hosted runners'

package/errors/silent-failures/github-ref-full-path-comparison-always-false.yml

@@ -0,0 +1,97 @@
+id: 'silent-failures-036'
+title: '`if: github.ref == ''main''` silently never matches — ref contains full `refs/heads/main` path'
+category: silent-failures
+severity: silent-failure
+tags:
+  - github-ref
+  - ref-name
+  - branch-comparison
+  - if-condition
+  - refs/heads
+  - silent-skip
+patterns:
+  - regex: 'github\.ref\s*[!=]=\s*[''"](?:main|master|develop|release|staging)[''"]'
+    flags: 'i'
+  - regex: 'github\.ref\s*[!=]=\s*[''"][a-z][a-z0-9_/-]*[^/][''"](?!\s*#.*refs/heads)'
+    flags: 'i'
+error_messages:
+  - "Step was skipped because the condition was false: github.ref == 'main'"
+  - "Job skipped: if: github.ref == 'master'"
+root_cause: |
+  `github.ref` always returns the full Git reference path, never just the branch name:
+  - Push to `main` branch: `refs/heads/main`
+  - Pull request: `refs/pull/123/merge`
+  - Tag push: `refs/tags/v1.0.0`
+
+  When a developer writes `if: github.ref == 'main'`, the condition always evaluates
+  to false because `'main'` != `'refs/heads/main'`. The step or job is silently skipped
+  with no error — only a "skipped" indicator in the UI, which is easy to overlook.
+
+  This is the most-viewed GitHub Actions question on Stack Overflow (SO #58033366,
+  478,000+ views), confirming how frequently developers encounter this mismatch.
+
+  Common variants:
+  - `if: github.ref == 'main'` → always false
+  - `if: github.ref == 'master'` → always false
+  - `if: github.ref != 'main'` → always true (everything runs)
+  - `if: github.ref == 'refs/heads/main' && github.ref == 'refs/tags/v*'` → impossible
+    (a ref cannot be both)
+  - On tag push: `if: github.ref == 'refs/heads/main'` → always false (it is `refs/tags/…`)
+fix: |
+  Option 1 — Use `github.ref_name` (recommended, available since runner 2.276.0 / Jan 2022):
+  `github.ref_name` returns just the branch or tag name without the `refs/heads/` or
+  `refs/tags/` prefix, making comparisons intuitive.
+
+  Option 2 — Compare against the full ref path:
+  Use `github.ref == 'refs/heads/main'` instead of `github.ref == 'main'`.
+
+  Option 3 — Match on event type:
+  Use `github.event_name == 'push'` to restrict steps to push (not PR) events, which is
+  often the underlying intent.
+fix_code:
+  - language: yaml
+    label: 'Use github.ref_name for simple branch/tag name comparison'
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Deploy to production
+              # github.ref_name returns 'main', 'v1.0.0', etc. (no refs/ prefix)
+              if: github.ref_name == 'main'
+              run: echo "Deploying"
+  - language: yaml
+    label: 'Use full ref path if you need github.ref specifically'
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Only on main branch push (not tags or PRs)
+              if: github.ref == 'refs/heads/main'
+              run: echo "Deploying"
+            - name: Only on version tags
+              if: startsWith(github.ref, 'refs/tags/v')
+              run: echo "Releasing"
+  - language: yaml
+    label: 'Use event_name to distinguish push from pull_request'
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Only on direct pushes, not PRs
+              if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+              run: echo "Deploying"
+prevention:
+  - 'Never compare `github.ref` to a bare branch name — it always includes the `refs/heads/` prefix'
+  - 'Prefer `github.ref_name` for branch/tag name comparisons when using runner 2.276.0+ (Jan 2022)'
+  - 'Verify your `if:` logic by inspecting the actual `github.ref` value in a debug step: `run: echo "${{ github.ref }}"`'
+  - 'Use the GitHub Actions context documentation to confirm which format each context variable uses'
+docs:
+  - url: 'https://docs.github.com/en/actions/learn-github-actions/contexts#github-context'
+    label: 'GitHub Docs: github context — github.ref and github.ref_name'
+  - url: 'https://stackoverflow.com/questions/58033366/how-to-get-the-current-branch-within-github-actions'
+    label: 'Stack Overflow #58033366 (428 votes, 478K views): How to get the current branch within GitHub Actions'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-conditions-to-control-job-execution'
+    label: 'GitHub Docs: Using conditions to control job execution'

package/errors/silent-failures/head-commit-null-on-pull-request.yml

@@ -0,0 +1,121 @@
+id: 'silent-failures-037'
+title: '`github.event.head_commit` is null on `pull_request` and `workflow_dispatch` events — commit message access silently fails'
+category: silent-failures
+severity: silent-failure
+tags:
+  - head-commit
+  - commit-message
+  - pull-request
+  - workflow-dispatch
+  - event-payload
+  - null-context
+  - silent-skip
+patterns:
+  - regex: 'github\.event\.head_commit\.(?:message|author|id|timestamp)'
+    flags: 'i'
+  - regex: 'github\.event\.head_commit\s+is\s+null'
+    flags: 'i'
+error_messages:
+  - "Error: Unhandled error: TypeError: Cannot read properties of null (reading 'message')"
+  - "Expression evaluation failed: github.event.head_commit is null"
+  - "Step was skipped because the condition was false: contains(github.event.head_commit.message, '[skip ci]')"
+root_cause: |
+  `github.event.head_commit` is only populated on `push` events. It is `null` (not an
+  empty object) on all other event types, including:
+  - `pull_request` and `pull_request_target`
+  - `workflow_dispatch`
+  - `workflow_call`
+  - `schedule`
+  - `release`
+  - `repository_dispatch`
+
+  This causes several silent failure patterns:
+  1. **Silent [skip ci] bypass**: A common pattern is
+     `if: "!contains(github.event.head_commit.message, '[skip ci]')"`.
+     On a `pull_request` event, `github.event.head_commit` is null, so the expression
+     evaluates as `!contains(null, '[skip ci]')` → `!false` → `true`. Every PR run
+     executes unconditionally, ignoring any [skip ci] intent.
+  2. **Runtime crash in scripts**: GitHub Script or shell steps that access
+     `${{ github.event.head_commit.message }}` on PR events receive an empty string
+     silently, or throw a TypeError if accessed via JavaScript.
+  3. **Commit metadata loss in multi-event workflows**: Workflows triggered by both
+     `push` and `pull_request` may use `head_commit` data in notifications or logs;
+     the PR trigger silently produces empty/null values for all commit fields.
+
+  This is documented in Stack Overflow question #63441440 (Score: 95, 100,000+ views).
+fix: |
+  Use a multi-event compatible approach to access commit messages:
+  - For `pull_request`: use `github.event.pull_request.head.sha` and fetch the commit
+    via the API, or use `github-script` with `octokit.rest.repos.getCommit()`
+  - For `push`: `github.event.head_commit.message` works directly
+  - For a robust cross-event solution: use `actions/checkout` with fetch-depth and
+    run `git log -1 --format=%s` in a shell step — this works regardless of event type
+  - For [skip ci] detection: use the `github.event.commits` array (available on `push`)
+    or check PR body/title instead of commit message for multi-event workflows
+fix_code:
+  - language: yaml
+    label: 'Guard head_commit access with event_name check'
+    code: |
+      steps:
+        - name: Get commit message (push events only)
+          if: github.event_name == 'push'
+          run: echo "Commit: ${{ github.event.head_commit.message }}"
+
+        - name: Get HEAD commit message (all events via shell)
+          run: |
+            MSG=$(git log -1 --format='%s')
+            echo "Commit: $MSG"
+  - language: yaml
+    label: 'Cross-event [skip ci] detection using shell git log'
+    code: |
+      jobs:
+        check-skip:
+          runs-on: ubuntu-latest
+          outputs:
+            skip: ${{ steps.skip-check.outputs.skip }}
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                fetch-depth: 2
+            - id: skip-check
+              run: |
+                MSG=$(git log -1 --format='%s')
+                if echo "$MSG" | grep -q '\[skip ci\]'; then
+                  echo "skip=true" >> "$GITHUB_OUTPUT"
+                else
+                  echo "skip=false" >> "$GITHUB_OUTPUT"
+                fi
+
+        build:
+          needs: check-skip
+          if: needs.check-skip.outputs.skip != 'true'
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Building"
+  - language: yaml
+    label: 'Fetch commit message via API for pull_request events'
+    code: |
+      steps:
+        - name: Get PR head commit message
+          if: github.event_name == 'pull_request'
+          uses: actions/github-script@v7
+          with:
+            script: |
+              const { data } = await github.rest.repos.getCommit({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                ref: context.payload.pull_request.head.sha
+              });
+              console.log('Commit message:', data.commit.message);
+prevention:
+  - 'Always guard `github.event.head_commit` access with `if: github.event_name == ''push''`'
+  - 'For multi-event workflows needing commit messages, use `git log -1 --format=%s` after checkout rather than the event context'
+  - 'Do not use `github.event.head_commit.message` for [skip ci] detection — it silently fails on PRs and dispatches'
+  - 'Add `run: echo "${{ toJSON(github.event) }}"` to debug which event fields are available for each trigger'
+docs:
+  - url: 'https://docs.github.com/en/webhooks/webhook-events-and-payloads#push'
+    label: 'GitHub Docs: push event payload — head_commit field'
+  - url: 'https://docs.github.com/en/webhooks/webhook-events-and-payloads#pull_request'
+    label: 'GitHub Docs: pull_request event payload (no head_commit field)'
+  - url: 'https://stackoverflow.com/questions/63441440/get-github-commit-message-in-pull-request-actions'
+    label: 'Stack Overflow #63441440 (95 votes, 100K views): Get GitHub commit message in pull request Actions'

package/package.json

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