@htekdev/actions-debugger 1.0.62 → 1.0.64

package/errors/caching-artifacts/cache-key-github-sha-no-restore.yml

@@ -0,0 +1,72 @@
+id: caching-artifacts-042
+title: "Cache key containing github.sha always misses on restore — cache is saved but never reused"
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - cache
+  - cache-key
+  - github-sha
+  - cache-miss
+  - restore-keys
+  - performance
+patterns:
+  - regex: 'Cache not found for input keys: .*\b[0-9a-f]{40}\b'
+    flags: i
+  - regex: 'Warning: Cache not found for.*sha.*\.'
+    flags: i
+  - regex: 'Cache restored from key: .*\b[0-9a-f]{40}\b'
+    flags: i
+error_messages:
+  - "Cache not found for input keys: Linux-node-a3f2b1c9d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9"
+  - "Warning: Cache not found for key: ubuntu-latest-npm-abc1234def5678901234567890abcdef12345678"
+root_cause: |
+  When a cache key includes ${{ github.sha }}, every commit produces a unique key. The cache is
+  saved successfully at the end of the workflow, but on the very next run the sha is different,
+  so the restore step finds no matching cache entry and declares a miss. This pattern ensures
+  the cache is written once and thrown away — it provides no performance benefit.
+
+  This mistake is common because github.sha is a readily available context value and its use
+  in cache keys looks reasonable at first glance. The cache action's restore-keys fallback
+  mechanism would normally rescue a miss, but developers often omit restore-keys when using
+  sha-based keys, expecting the primary key to match.
+fix: |
+  Replace github.sha with a hash of the files that determine cache validity, such as
+  hashFiles('**/package-lock.json') for npm or hashFiles('**/go.sum') for Go. Use github.sha
+  only as a restore-keys fallback prefix if you want a per-commit cache layer on top of a
+  stable base cache. The cache key should be stable across commits unless the relevant
+  dependency manifest changes.
+fix_code:
+  - language: yaml
+    label: "Correct cache key using hashFiles instead of github.sha"
+    code: |
+      - name: Cache node modules
+        uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-node-
+  - language: yaml
+    label: "Per-commit layer on top of a stable base cache (advanced)"
+    code: |
+      # Stable key hits on re-runs; sha layer saves per-commit installs
+      - name: Cache node modules
+        uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-node-${{ github.sha }}
+          restore-keys: |
+            ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+            ${{ runner.os }}-node-
+prevention:
+  - "Never use github.sha as a primary cache key unless you explicitly want a per-commit cache that never restores"
+  - "Use hashFiles() over the relevant lock file or manifest as the stable portion of the cache key"
+  - "Always add restore-keys with progressively broader prefixes to benefit from partial cache hits"
+  - "Check the cache hit rate in the Actions UI — 0% hit rate on restore is a sign the key is too unique"
+docs:
+  - url: https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows#using-the-cache-action
+    label: "GitHub Docs: Using the cache action"
+  - url: https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows#matching-a-cache-key
+    label: "GitHub Docs: Matching a cache key"
+  - url: https://stackoverflow.com/questions/59435153/github-actions-cache-miss-every-run
+    label: "Stack Overflow: GitHub Actions cache miss every run"

package/errors/known-unsolved/service-containers-not-supported-macos-windows.yml

@@ -0,0 +1,88 @@
+id: known-unsolved-041
+title: "services: Block Not Supported on macOS and Windows Runners — Silently Ignored"
+category: known-unsolved
+severity: limitation
+tags:
+  - services
+  - service-containers
+  - macos
+  - windows
+  - linux-only
+patterns:
+  - regex: 'services\s*:'
+    flags: 'im'
+  - regex: 'runs-on\s*:\s*(macos|windows)'
+    flags: 'i'
+error_messages:
+  - "Connection refused 127.0.0.1:5432"
+  - "Unable to connect to the database server"
+  - "ECONNREFUSED"
+  - "connect ECONNREFUSED 127.0.0.1:6379"
+root_cause: |
+  GitHub Actions `services:` containers are only supported on Linux (Ubuntu) runners.
+  On macOS and Windows GitHub-hosted runners, the `services:` block is silently ignored
+  — the job starts without the service containers, and no warning or error is emitted
+  at the workflow syntax level.
+
+  This happens because the runner agent's service container feature requires Docker
+  to be integrated at the runner daemon level. GitHub-hosted macOS and Windows runners
+  do not have a running Docker daemon available to the runner agent by default, making
+  the `services:` lifecycle management impossible.
+
+  The failure is deceptive: the job starts normally, all steps run, but any step that
+  tries to connect to the service (e.g., PostgreSQL on port 5432, Redis on port 6379)
+  receives a connection refused error. The `services:` block produces no visible error
+  of its own.
+
+  There is no GitHub Actions built-in mechanism to make `services:` work on macOS or
+  Windows runners. This is a permanent platform limitation.
+fix: |
+  Use a Linux (ubuntu-*) runner for any job that requires service containers. If macOS
+  or Windows testing is required alongside a service dependency, start the service
+  manually as workflow steps within the job instead of using the `services:` block.
+fix_code:
+  - language: yaml
+    label: "services: block — only works on Linux runners"
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-latest  # services: requires Linux
+          services:
+            postgres:
+              image: postgres:15
+              env:
+                POSTGRES_PASSWORD: postgres
+              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
+  - language: yaml
+    label: "macOS/Windows: start service manually as a workflow step"
+    code: |
+      jobs:
+        test-macos:
+          runs-on: macos-latest
+          # services: is NOT supported here — start the service manually instead
+          steps:
+            - uses: actions/checkout@v4
+            - name: Start PostgreSQL (services: not supported on macOS)
+              run: |
+                brew install postgresql@15
+                brew services start postgresql@15
+                sleep 5
+            - run: npm test
+prevention:
+  - "Always pair the `services:` block with a Linux (ubuntu-*) runner — treat this as a hard rule in code review"
+  - "If cross-platform testing needs a service dependency, isolate the service-dependent tests into a Linux-only job"
+  - "Add a comment near the `services:` block to document that this job must run on Linux"
+docs:
+  - url: "https://docs.github.com/en/actions/use-cases-and-examples/using-containerized-services/about-service-containers"
+    label: "GitHub Docs: About service containers (Linux-only requirement)"
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idservices"
+    label: "GitHub Docs: jobs.<job_id>.services syntax reference"

package/errors/permissions-auth/github-token-fork-pr-read-only.yml

@@ -0,0 +1,114 @@
+id: permissions-auth-045
+title: "GITHUB_TOKEN has read-only access in pull_request workflows from forks — write operations return 403"
+category: permissions-auth
+severity: error
+tags:
+  - github-token
+  - fork
+  - pull-request
+  - read-only
+  - permissions
+  - resource-not-accessible
+  - write-access
+patterns:
+  - regex: 'Resource not accessible by integration'
+    flags: i
+  - regex: 'HttpError: Resource not accessible by integration'
+    flags: i
+  - regex: 'Error: HttpError: Not Found.*token.*forked'
+    flags: i
+  - regex: 'refused.*write.*403.*pull_request.*fork'
+    flags: i
+error_messages:
+  - "Error: Resource not accessible by integration"
+  - "RequestError [HttpError]: Resource not accessible by integration"
+  - "Error: HttpError: Resource not accessible by integration"
+root_cause: |
+  When a pull_request workflow is triggered by a PR from a forked repository, GitHub
+  automatically restricts the GITHUB_TOKEN to read-only permissions. This security measure
+  prevents malicious PRs from using the token to modify the base repository — the token
+  cannot create issues, post comments, create releases, trigger deployments, or write to
+  the repository. Workflows see a token that behaves as if all write permissions were denied.
+
+  This restriction applies even if the workflow YAML has explicit permissions: write entries.
+  The fork security boundary takes precedence. The workflow still runs (unlike pull_request_target
+  which runs with base repo permissions), but the token scope is silently reduced.
+
+  Common victims include: posting PR comments with github-script, uploading artifacts to
+  releases, creating check runs, and updating commit statuses.
+fix: |
+  Use the pull_request_target event if the workflow must write to the base repo. Be aware
+  that pull_request_target checks out the base branch by default (not the PR head) and carries
+  security implications — never checkout and execute untrusted PR code with write-permission
+  tokens (see pwn request attacks). For safe comment posting, split into two workflows:
+  a read-only pull_request workflow that uploads results as an artifact, and a
+  pull_request_target or workflow_run workflow with write access that downloads the artifact
+  and posts the comment.
+fix_code:
+  - language: yaml
+    label: "Split pattern — upload results in pull_request, post comment in workflow_run"
+    code: |
+      # Workflow 1: pr-test.yml — runs on pull_request (fork-safe, read-only token)
+      on: pull_request
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - name: Run tests and save results
+              run: npm test > test-results.txt 2>&1 || true
+            - name: Upload PR number for downstream workflow
+              uses: actions/upload-artifact@v4
+              with:
+                name: pr-results
+                path: |
+                  test-results.txt
+  - language: yaml
+    label: "Workflow 2 — post comment using workflow_run (has write token)"
+    code: |
+      # Workflow 2: pr-comment.yml — runs after pr-test.yml completes (has write token)
+      on:
+        workflow_run:
+          workflows: ["PR Tests"]
+          types: [completed]
+
+      permissions:
+        pull-requests: write
+
+      jobs:
+        comment:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Download test results artifact
+              uses: actions/download-artifact@v4
+              with:
+                name: pr-results
+                run-id: ${{ github.event.workflow_run.id }}
+                github-token: ${{ secrets.GITHUB_TOKEN }}
+            - name: Post PR comment
+              uses: actions/github-script@v7
+              with:
+                script: |
+                  const fs = require('fs');
+                  const results = fs.readFileSync('test-results.txt', 'utf8');
+                  await github.rest.issues.createComment({
+                    owner: context.repo.owner,
+                    repo: context.repo.repo,
+                    issue_number: context.payload.workflow_run.pull_requests[0].number,
+                    body: '## Test Results\n```\n' + results + '\n```'
+                  });
+prevention:
+  - "Know that GITHUB_TOKEN is read-only for PR workflows from forks — this is a security feature, not a misconfiguration"
+  - "Never use pull_request_target to run PR head code with write-permission tokens — this creates a pwn request vulnerability"
+  - "Use the upload-artifact + workflow_run split pattern for safe cross-fork write operations"
+  - "Test workflows with a fork PR specifically if they perform write operations — the token scope difference won't appear in same-repo PRs"
+docs:
+  - url: https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#pull_request
+    label: "GitHub Docs: pull_request event — fork permission restrictions"
+  - url: https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication#permissions-for-the-github_token
+    label: "GitHub Docs: GITHUB_TOKEN permissions"
+  - url: https://securitylab.github.com/research/github-actions-preventing-pwn-requests/
+    label: "GitHub Security Lab: Preventing pwn requests (pull_request_target risks)"
+  - url: https://stackoverflow.com/questions/70435286/resource-not-accessible-by-integration-on-github-pull-request-event
+    label: "Stack Overflow: Resource not accessible by integration on pull_request"

package/errors/silent-failures/cache-hit-output-empty-string-not-false.yml

@@ -0,0 +1,87 @@
+id: silent-failures-063
+title: "actions/cache cache-hit output is empty string on miss, not 'false' — equality checks silently never match"
+category: silent-failures
+severity: silent-failure
+tags:
+  - actions-cache
+  - cache-hit
+  - output
+  - empty-string
+  - if-condition
+  - false-comparison
+patterns:
+  - regex: 'steps\.\w+\.outputs\.cache-hit\s*==\s*[''"]false[''"]'
+    flags: i
+  - regex: "cache-hit.*==.*'false'"
+    flags: i
+error_messages:
+  - "cache-hit output comparison to 'false' always evaluates to false — use != 'true' instead"
+root_cause: |
+  The actions/cache action sets the cache-hit output to the string 'true' when a cache is
+  restored from an exact key match, and to an empty string '' when the cache is not found
+  (including when restored from a restore-keys fallback, which returns '' for cache-hit in v3
+  and 'false' only in some v4 configurations). This means that
+  `if: steps.cache.outputs.cache-hit == 'false'` evaluates to false on a cache miss because
+  '' != 'false', so the step or job it guards is silently skipped.
+
+  This is one of the most upvoted GitHub Actions questions on Stack Overflow. Developers
+  naturally expect a boolean-like output to be 'true' or 'false', but the cache action uses
+  'true' vs '' (empty) semantics. The step appears to run successfully; nothing in the logs
+  indicates the if condition did not match as expected.
+fix: |
+  Check for cache miss using != 'true' instead of == 'false'. An empty string and 'false'
+  both evaluate to not-equal-to-'true', so this pattern correctly handles all cache miss
+  cases across cache action versions. Alternatively, use the boolean expression
+  `steps.cache.outputs.cache-hit != 'true'` or omit the check and rely on the cache action's
+  lookup-only: true parameter combined with a separate save step.
+fix_code:
+  - language: yaml
+    label: "Use != 'true' to reliably detect cache miss (works across all cache action versions)"
+    code: |
+      - name: Cache dependencies
+        id: cache-deps
+        uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+
+      # WRONG — silently never runs on cache miss:
+      # - name: Install deps
+      #   if: steps.cache-deps.outputs.cache-hit == 'false'
+
+      # CORRECT — matches both '' and 'false':
+      - name: Install dependencies
+        if: steps.cache-deps.outputs.cache-hit != 'true'
+        run: npm ci
+  - language: yaml
+    label: "Lookup-only + explicit save pattern (cache@v4) to avoid output ambiguity"
+    code: |
+      - name: Restore cache (lookup only, no auto-save)
+        id: cache-restore
+        uses: actions/cache/restore@v4
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+
+      - name: Install dependencies
+        if: steps.cache-restore.outputs.cache-hit != 'true'
+        run: npm ci
+
+      - name: Save cache
+        if: steps.cache-restore.outputs.cache-hit != 'true'
+        uses: actions/cache/save@v4
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+prevention:
+  - "Always use != 'true' to check for cache miss — never use == 'false' on cache action outputs"
+  - "Review the cache action version changelog: v3 uses '' on miss, v4 behavior depends on exact/partial hit"
+  - "Add a debug step that echoes cache-hit output to make cache behavior visible in logs during development"
+  - "Consult the cache action README for the exact semantics of cache-hit, cache-primary-key, and cache-matched-key"
+docs:
+  - url: https://github.com/actions/cache#outputs
+    label: "actions/cache README: Outputs"
+  - url: https://stackoverflow.com/questions/62754195/github-actions-cache-hit-is-true-but-id-expect-false
+    label: "Stack Overflow: cache-hit is empty string, not 'false'"
+  - url: https://github.com/actions/cache/issues/1699
+    label: "actions/cache#1699: cache-hit output '' vs 'false' confusion"

package/errors/silent-failures/workflow-run-github-sha-is-default-branch.yml

@@ -0,0 +1,78 @@
+id: silent-failures-064
+title: "workflow_run Trigger: github.sha Points to Default Branch HEAD, Not Triggering Workflow's Commit"
+category: silent-failures
+severity: silent-failure
+tags:
+  - workflow_run
+  - github-sha
+  - checkout
+  - wrong-commit
+  - cross-workflow
+patterns:
+  - regex: 'on\s*:\s*\n\s+workflow_run'
+    flags: 'im'
+  - regex: 'github\.sha'
+    flags: 'i'
+error_messages:
+  - "Unexpected checkout SHA — does not match pull request head commit"
+  - "Tests passing on default branch but failing on PR commit"
+root_cause: |
+  When a workflow is triggered by `on: workflow_run`, the `github.sha` and `github.ref`
+  context variables point to the HEAD of the **default branch** at the time the trigger
+  fires, NOT to the commit that triggered the upstream workflow. This is by design: the
+  `workflow_run` event executes in the context of the base repository's default branch.
+
+  Workflows that use `actions/checkout` without specifying a `ref` will silently check
+  out the default branch — running against entirely different code than the PR or branch
+  that triggered the original CI workflow. CI results, security scans, and deployments
+  end up referencing the wrong commit with no visible error.
+
+  The correct commit SHA from the triggering workflow is available in the event payload
+  as `github.event.workflow_run.head_sha`.
+fix: |
+  Use `github.event.workflow_run.head_sha` as the `ref` in `actions/checkout` within
+  any `workflow_run` triggered workflow. When the triggering workflow originates from a
+  fork PR, also supply `github.event.workflow_run.head_repository.full_name` as the
+  `repository` input so the correct fork is checked out.
+fix_code:
+  - language: yaml
+    label: "Wrong: default checkout uses github.sha (default branch HEAD)"
+    code: |
+      on:
+        workflow_run:
+          workflows: ["CI"]
+          types: [completed]
+
+      jobs:
+        process:
+          runs-on: ubuntu-latest
+          steps:
+            # Silently checks out default branch, NOT the triggering commit
+            - uses: actions/checkout@v4
+  - language: yaml
+    label: "Correct: use workflow_run event payload for the right commit"
+    code: |
+      on:
+        workflow_run:
+          workflows: ["CI"]
+          types: [completed]
+
+      jobs:
+        process:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                repository: ${{ github.event.workflow_run.head_repository.full_name }}
+                ref: ${{ github.event.workflow_run.head_sha }}
+                token: ${{ secrets.GITHUB_TOKEN }}
+prevention:
+  - "Always set `ref: ${{ github.event.workflow_run.head_sha }}` in checkout steps inside workflow_run triggered workflows"
+  - "Log both `github.sha` and `github.event.workflow_run.head_sha` at workflow start to verify they match when expected"
+  - "For fork-originated PRs, also set `repository: ${{ github.event.workflow_run.head_repository.full_name }}`"
+  - "Add a comment in the workflow explaining why head_sha is used instead of github.sha to avoid future confusion"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_run"
+    label: "GitHub Docs: workflow_run event (context behavior)"
+  - url: "https://securitylab.github.com/resources/github-actions-preventing-pwn-requests/"
+    label: "GitHub Security Lab: Preventing pwn requests (workflow_run checkout patterns)"

package/errors/triggers/push-commits-truncated-20-limit.yml

@@ -0,0 +1,78 @@
+id: triggers-046
+title: "github.event.commits Array Truncated to 20 Commits on Large Pushes"
+category: triggers
+severity: silent-failure
+tags:
+  - push
+  - commits
+  - github-event
+  - truncated
+  - commit-messages
+patterns:
+  - regex: 'github\.event\.commits'
+    flags: 'i'
+error_messages:
+  - "Only processing 20 of N commits"
+  - "Missing commits in push event payload"
+root_cause: |
+  When a push event triggers a workflow, the `github.event.commits` array is capped at
+  a maximum of 20 commit objects, regardless of how many commits were included in the
+  push. This limit applies to the webhook payload that populates the `github.event`
+  context and is documented in the GitHub webhook specification.
+
+  Workflows that iterate over `github.event.commits` to extract commit messages for
+  changelog generation, enforce commit message formatting (Conventional Commits, etc.),
+  or trigger conditional logic based on commit content will silently miss any commits
+  beyond the 20th. The job completes successfully with no indication that commits were
+  dropped from the payload.
+
+  Commonly affected use cases:
+  - Automated changelog or release note generation from push commit messages
+  - Commit message linting or conventional commits enforcement
+  - Workflows triggered by specific keywords in commit messages
+  - Security scanning workflows that enumerate all modified files from commit diffs
+fix: |
+  Use `git log` with the push SHA range (`github.event.before..github.event.after`) to
+  enumerate all commits in the push, regardless of count. This requires checking out
+  the repository with `fetch-depth: 0` (full history) or at minimum enough depth to
+  span the push range. Guard against the `before` SHA being all zeros (first push to
+  a new branch).
+fix_code:
+  - language: yaml
+    label: "Wrong: iterating github.event.commits silently misses commits beyond 20"
+    code: |
+      - name: Lint commit messages
+        run: |
+          # Silently processes only up to 20 commits even on large pushes
+          echo '${{ toJSON(github.event.commits) }}' \
+            | jq -r '.[].message' \
+            | npx commitlint --from stdin
+  - language: yaml
+    label: "Correct: use git log with push range to enumerate all commits"
+    code: |
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # full history required for git log range
+
+      - name: Lint all commit messages in push
+        run: |
+          BEFORE="${{ github.event.before }}"
+          AFTER="${{ github.event.after }}"
+
+          # Guard: first push to a new branch has before = 000...000
+          if [ "$BEFORE" = "0000000000000000000000000000000000000000" ]; then
+            echo "First push to new branch — scanning tip commit only"
+            git log -1 --format="%s" "$AFTER"
+          else
+            git log --format="%s" "${BEFORE}..${AFTER}"
+          fi | npx commitlint --from stdin
+prevention:
+  - "Never rely on `github.event.commits` for exhaustive commit enumeration on pushes — use `git log` with the SHA range instead"
+  - "Always add `fetch-depth: 0` to checkout when your workflow needs to enumerate commits from the push range"
+  - "Guard against `github.event.before` being all zeros (new branch first push) before running `git log BEFORE..AFTER`"
+  - "If commit count matters, log a warning when `github.event.commits | length == 20` to detect truncation"
+docs:
+  - url: "https://docs.github.com/en/webhooks/webhook-events-and-payloads#push"
+    label: "GitHub Docs: Push webhook payload (20 commit limit)"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#push"
+    label: "GitHub Docs: push event trigger"

package/errors/triggers/push-paths-filter-no-effect-workflow-dispatch.yml

@@ -0,0 +1,81 @@
+id: triggers-045
+title: "on.push.paths filter has no effect on workflow_dispatch — manual trigger always runs regardless of changed files"
+category: triggers
+severity: silent-failure
+tags:
+  - workflow-dispatch
+  - push
+  - paths-filter
+  - triggers
+  - manual-trigger
+  - always-runs
+patterns:
+  - regex: 'workflow_dispatch'
+    flags: i
+error_messages:
+  - "Workflow ran unexpectedly when triggered via workflow_dispatch despite paths filter"
+root_cause: |
+  GitHub Actions evaluates on.push.paths (and on.push.paths-ignore) filters only for push
+  events. The filter is tied to the event type it is defined under. When workflow_dispatch is
+  added as a separate trigger, it has no paths context — there is no commit diff associated
+  with a manual dispatch. GitHub therefore runs the workflow unconditionally when dispatched.
+
+  This surprises developers who add workflow_dispatch: to an existing push-triggered workflow
+  for convenience and expect the paths filter to still gate the run. The workflow_dispatch
+  event has no paths or branches key at all; any such keys would be silently ignored if added.
+
+  A related confusion: paths filters on pull_request or push do not protect against
+  workflow_dispatch, so adding a workflow_dispatch trigger effectively creates an unfiltered
+  entry point into the workflow.
+fix: |
+  Accept that workflow_dispatch runs unconditionally — this is intentional GitHub behavior.
+  If you want to restrict what the dispatched workflow does based on inputs, use
+  workflow_dispatch inputs to pass a flag and gate steps with if: conditions. If the goal is
+  to limit accidental runs, remove workflow_dispatch from workflows where paths-gating is
+  critical, or add a required input that must be confirmed before proceeding.
+fix_code:
+  - language: yaml
+    label: "Separate push-only workflow (with paths filter) from a dispatch-friendly workflow"
+    code: |
+      # Option 1: keep push and dispatch as separate workflow files
+      # push-filtered.yml — only triggered on relevant path changes
+      on:
+        push:
+          paths:
+            - 'src/**'
+
+      # dispatch-build.yml — no paths filter needed; always intentional
+      on:
+        workflow_dispatch:
+  - language: yaml
+    label: "Use a workflow_dispatch input to require confirmation before running"
+    code: |
+      on:
+        push:
+          paths:
+            - 'src/**'
+        workflow_dispatch:
+          inputs:
+            confirm:
+              description: 'Type YES to run regardless of changed files'
+              required: true
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Proceed only if push triggered by path change OR dispatch confirmed
+              if: github.event_name == 'push' || inputs.confirm == 'YES'
+              run: echo "Running build"
+prevention:
+  - "Understand that paths/branches filters are per-event-type — workflow_dispatch has no file diff context"
+  - "Document in the workflow file that workflow_dispatch runs unconditionally to avoid future confusion"
+  - "Use workflow_dispatch inputs to gate critical steps when a manual trigger is added to a path-filtered workflow"
+  - "Review which workflows have both push.paths filters and workflow_dispatch before adding the dispatch trigger"
+docs:
+  - url: https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_dispatch
+    label: "GitHub Docs: workflow_dispatch event"
+  - url: https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/triggering-a-workflow#using-filters-to-target-specific-branches-or-tags-for-push-events
+    label: "GitHub Docs: Using filters to target specific paths"
+  - url: https://stackoverflow.com/questions/65900201/workflow-dispatch-ignores-paths-filter
+    label: "Stack Overflow: workflow_dispatch ignores paths filter"

package/errors/yaml-syntax/runs-on-env-context-unavailable.yml

@@ -0,0 +1,82 @@
+id: yaml-syntax-043
+title: "env Context Not Available in runs-on Expression — Job Waits for Non-Existent Runner"
+category: yaml-syntax
+severity: error
+tags:
+  - runs-on
+  - env-context
+  - context-availability
+  - runner-selection
+  - expression
+patterns:
+  - regex: 'runs-on\s*:.*\$\{\{.*env\.'
+    flags: 'i'
+error_messages:
+  - "No runner matching the specified labels was found"
+  - "Context access might be invalid: env"
+  - "Evaluates to empty string in runs-on"
+root_cause: |
+  The `env` context is not available in `jobs.<job_id>.runs-on` expressions. GitHub
+  Actions documents an explicit context availability table, and `env` is excluded from
+  the `runs-on` field. Only the `github`, `needs`, `strategy`, `matrix`, `vars`, and
+  `inputs` contexts are available for `runs-on` expressions.
+
+  When a developer writes `runs-on: ${{ env.RUNNER_LABEL }}`, the expression evaluates
+  to an empty string (since `env` is not accessible at that evaluation point). GitHub
+  Actions may emit the warning "Context access might be invalid: env" during workflow
+  parsing. The job then queues waiting for a runner matching an empty or literal label,
+  which never matches, and the job hangs until it times out.
+
+  This is a common mistake when setting a custom self-hosted runner label as a
+  workflow-level or job-level `env:` variable and trying to reference it in `runs-on`
+  for DRY configuration.
+fix: |
+  Use the `vars` context (repository, organization, or environment variables) instead of
+  `env` for dynamic runner label selection. Repository variables can be set in the
+  repository's Settings > Secrets and variables > Variables and referenced as
+  `${{ vars.RUNNER_LABEL }}`. The `vars` context IS available in `runs-on` expressions.
+
+  Alternatively, use `inputs` context for `workflow_dispatch` triggered workflows to
+  allow callers to specify the runner label.
+fix_code:
+  - language: yaml
+    label: "Wrong: env context is not available in runs-on"
+    code: |
+      env:
+        RUNNER_LABEL: self-hosted-prod  # This env var cannot be used in runs-on
+
+      jobs:
+        deploy:
+          # ERROR: env context unavailable — expression evaluates to empty string
+          runs-on: ${{ env.RUNNER_LABEL }}
+  - language: yaml
+    label: "Correct: use vars context (repository/org variable)"
+    code: |
+      # Set RUNNER_LABEL in Settings > Secrets and variables > Variables (repo or org level)
+      jobs:
+        deploy:
+          runs-on: ${{ vars.RUNNER_LABEL || 'ubuntu-latest' }}
+  - language: yaml
+    label: "Correct: use inputs for workflow_dispatch dynamic runner selection"
+    code: |
+      on:
+        workflow_dispatch:
+          inputs:
+            runner:
+              description: 'Runner label'
+              default: 'ubuntu-latest'
+              type: string
+
+      jobs:
+        deploy:
+          runs-on: ${{ inputs.runner }}
+prevention:
+  - "Check GitHub's context availability table before using any context in `runs-on` — `env` is NOT available there"
+  - "Use `vars.*` (repository or org variables) not `env.*` for dynamic runner label configuration"
+  - "Add `|| 'ubuntu-latest'` as a fallback in `runs-on` expressions to avoid jobs that queue indefinitely"
+  - "If the job hangs immediately after queuing with no runner assignment, check `runs-on` expressions for invalid context usage"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/contexts#context-availability"
+    label: "GitHub Docs: Context availability table (runs-on allowed contexts)"
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on"
+    label: "GitHub Docs: jobs.<job_id>.runs-on expressions"

package/package.json

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