@htekdev/actions-debugger 1.0.40 → 1.0.42

package/errors/caching-artifacts/setup-node-npm-cache-monorepo-lockfile-not-found.yml

@@ -0,0 +1,118 @@
+id: caching-artifacts-032
+title: 'setup-node cache: npm silently skips caching in monorepos — lockfile not at workspace root'
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - setup-node
+  - npm
+  - cache
+  - monorepo
+  - lockfile
+  - cache-dependency-path
+  - silent-failure
+patterns:
+  - regex: "Warning: No file found for: package-lock\\.json"
+    flags: 'i'
+  - regex: 'No file found for.*No cache will be (saved|restored)'
+    flags: 'i'
+  - regex: 'cache-dependency-path.*not found|No lockfile found'
+    flags: 'i'
+error_messages:
+  - "Warning: No file found for: package-lock.json"
+  - "Warning: No file found for: yarn.lock"
+  - "Warning: No file found for: pnpm-lock.yaml"
+  - "No file found for: package-lock.json. No cache will be saved."
+root_cause: |
+  actions/setup-node with cache: 'npm' (or 'yarn' / 'pnpm') searches for the
+  package manager lockfile at the workspace root ($GITHUB_WORKSPACE) by default.
+
+  In monorepos where the lockfile lives in a subdirectory (apps/frontend/,
+  packages/api/, etc.), or when the workflow uses working-directory: to change
+  the build context, setup-node logs a warning and continues WITHOUT configuring
+  a cache. The step exits 0, making this a silent failure.
+
+  The result: npm ci (or yarn install / pnpm install) downloads all dependencies
+  from the network on every workflow run, as though no cache were configured.
+  Build times are identical to runs with no cache setting at all.
+
+  The warning message ("No file found for: package-lock.json") is easily missed
+  in long step logs and does not fail the step, so developers often go weeks
+  without noticing the cache was never active.
+
+  The same behavior applies when:
+  - yarn.lock is not at workspace root
+  - pnpm-lock.yaml is not at workspace root
+  - Multiple lockfiles exist across packages (only the first match is used
+    unless cache-dependency-path is explicitly set to a glob)
+fix: |
+  Use the cache-dependency-path input to specify the path to the lockfile
+  relative to the workspace root. Supports glob patterns for monorepos.
+
+  Single package in subdirectory:
+    cache-dependency-path: 'frontend/package-lock.json'
+
+  Multiple lockfiles across a monorepo:
+    cache-dependency-path: '**/package-lock.json'
+
+  Using a glob creates a combined cache key from all matched lockfiles. Any
+  change to any package lockfile invalidates the shared cache — this is
+  correct behavior for a monorepo where cross-package installs are common.
+fix_code:
+  - language: yaml
+    label: 'Single package in subdirectory — point cache-dependency-path at lockfile'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - uses: actions/setup-node@v4
+              with:
+                node-version: '22'
+                cache: 'npm'
+                # WRONG (omitted): setup-node looks at $GITHUB_WORKSPACE/package-lock.json
+                # and silently skips caching when not found there
+
+                # CORRECT: path relative to $GITHUB_WORKSPACE
+                cache-dependency-path: 'frontend/package-lock.json'
+
+            - name: Install dependencies
+              working-directory: frontend
+              run: npm ci
+  - language: yaml
+    label: 'Monorepo — cache all packages using glob pattern'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - uses: actions/setup-node@v4
+              with:
+                node-version: '22'
+                cache: 'npm'
+                # Glob matches all package-lock.json files anywhere in the repo
+                # Combined hash from all matched lockfiles forms the cache key
+                cache-dependency-path: '**/package-lock.json'
+
+            - name: Install root dependencies
+              run: npm ci
+
+            - name: Install frontend dependencies
+              working-directory: packages/frontend
+              run: npm ci
+prevention:
+  - 'Always set cache-dependency-path when the lockfile is not in the repository root'
+  - 'Use **/package-lock.json glob in monorepos to cover all packages with a single cache configuration'
+  - 'Verify caching is active by checking setup-node logs for "Cache restored successfully" or "Cache saved"'
+  - 'Check for "No file found for: package-lock.json" warnings as early signal that caching is silently disabled'
+  - 'When using working-directory: on install steps, ensure cache-dependency-path is also adjusted to match'
+docs:
+  - url: 'https://github.com/actions/setup-node#caching-global-packages-data'
+    label: 'actions/setup-node: Caching global packages data — cache-dependency-path input'
+  - url: 'https://github.com/actions/setup-node/issues/530'
+    label: 'actions/setup-node#530: cache: npm silently skips in monorepos without cache-dependency-path'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows'
+    label: 'GitHub Docs: Caching dependencies to speed up workflows — lockfile path configuration'

package/errors/concurrency-timing/cancel-in-progress-queued-run-status-never-posts.yml

@@ -0,0 +1,111 @@
+id: concurrency-timing-027
+title: 'Queued run cancelled by cancel-in-progress before any job starts — required status check never posts, PR permanently blocked'
+category: concurrency-timing
+severity: silent-failure
+tags:
+  - concurrency
+  - cancel-in-progress
+  - required-status-check
+  - branch-protection
+  - pr-blocked
+  - status-check
+patterns:
+  - regex: 'This run was cancelled because another run in the same concurrency group'
+    flags: 'i'
+  - regex: 'Waiting for.*status.*reported|Expected.*Waiting'
+    flags: 'i'
+error_messages:
+  - "This run was cancelled because another run in the same concurrency group is in progress."
+  - "Waiting for status to be reported"
+root_cause: |
+  When cancel-in-progress: true cancels a workflow run that was queued but had
+  not yet started any job, GitHub does NOT post a status (pending, cancelled, or
+  failure) to the commit SHA. The run silently disappears from the run list.
+
+  Branch protection rules that require a specific status check (e.g., "CI / test")
+  only observe statuses that were posted. A run cancelled before its first job
+  starts never posts any status — not even "pending".
+
+  Impact on PRs with high push frequency:
+  1. Developer opens PR, pushes commit A — run starts, posts "pending"
+  2. Developer pushes fix commit B — run for A is cancelled, run for B is queued
+  3. Developer pushes commit C before B's run starts — B's run cancelled (never
+     started), run for C queued
+  4. Run for C finally starts and posts statuses
+  5. But if C is also cancelled before starting, the commit has NO status
+  6. Branch protection shows the required check as "Expected" forever
+  7. PR cannot be merged — the Merge button stays disabled indefinitely
+
+  This condition is self-healing if a new commit is pushed (starting a fresh
+  run that won't be cancelled), but in rapid-push scenarios the window persists
+  for many minutes and developers mistakenly believe the CI is broken.
+fix: |
+  Option 1 — Queue instead of cancel (safest):
+    concurrency:
+      group: "${{ github.workflow }}-${{ github.ref }}"
+      cancel-in-progress: false
+
+  Runs queue behind one another; every commit eventually gets a status posted.
+
+  Option 2 — Status anchor job:
+  Add a minimal first job that completes instantly. Its "queued" + "in_progress"
+  status is posted to the commit SHA immediately, ensuring GitHub registers the
+  run before any cancellation can remove the status.
+
+  Option 3 — GitHub Actions recommended pattern:
+  Use cancel-in-progress: true for the expensive test jobs only, and have a
+  separate fast-posting job that always runs (not subject to concurrency group).
+fix_code:
+  - language: yaml
+    label: 'Queue runs instead of cancelling — every commit gets a status'
+    code: |
+      on:
+        pull_request:
+
+      concurrency:
+        # Queue instead of cancel — latest run waits, but always posts status
+        group: '${{ github.workflow }}-${{ github.ref }}'
+        cancel-in-progress: false
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm test
+  - language: yaml
+    label: 'Status anchor job — posts status immediately before cancel window'
+    code: |
+      on:
+        pull_request:
+
+      concurrency:
+        group: '${{ github.workflow }}-${{ github.ref }}'
+        cancel-in-progress: true    # OK — anchor ensures status is posted first
+
+      jobs:
+        # Minimal job: completes in seconds, ensuring a status is recorded on the SHA
+        anchor:
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "CI registered for ${{ github.sha }}"
+
+        # Expensive test job that is safe to cancel
+        test:
+          needs: anchor
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm test
+prevention:
+  - 'Avoid cancel-in-progress: true on workflows whose jobs are required status checks for branch protection'
+  - 'Use cancel-in-progress: false with queuing semantics when PR mergeability must be preserved on every commit'
+  - 'Add a lightweight anchor job as the first required job to ensure a status posts before any cancel window closes'
+  - 'Monitor PRs stuck with Expected required checks — check whether recent commits had all their runs cancelled before starting'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/using-concurrency'
+    label: 'GitHub Actions: Using concurrency — cancel-in-progress behavior'
+  - url: 'https://github.com/orgs/community/discussions/21280'
+    label: 'GitHub Community: Required status check never posts when run cancelled before start (120+ reactions)'
+  - url: 'https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-status-checks-before-merging'
+    label: 'GitHub Docs: Required status checks — how commit statuses are evaluated for branch protection'

package/errors/concurrency-timing/step-timeout-not-supported-job-holds-runner.yml

@@ -0,0 +1,101 @@
+id: concurrency-timing-025
+title: 'No step-level timeout — a hung step holds the runner slot for up to 6 hours'
+category: concurrency-timing
+severity: limitation
+tags:
+  - timeout
+  - hung-step
+  - runner-slot
+  - step
+  - limitation
+  - self-hosted-runner
+patterns:
+  - regex: 'The runner has received a shutdown signal'
+    flags: 'i'
+  - regex: 'Error: The process.*timed out after \d+ minutes'
+    flags: 'i'
+  - regex: 'Canceling since the workflow was cancelled'
+    flags: 'i'
+error_messages:
+  - "The runner has received a shutdown signal. This can happen when the runner service is stopped, or a manually started runner is canceled."
+  - "Error: The process '/usr/bin/bash' failed with exit code 124"
+  - "Canceling since the workflow was cancelled."
+root_cause: |
+  GitHub Actions supports timeout-minutes at the job level only. There is no
+  per-step timeout. A single run: step that hangs (network call blocked, test
+  suite deadlocked, subprocess waiting on stdin) holds the entire job until
+  the job-level timeout fires.
+
+  The default job timeout is 6 hours (360 minutes) for GitHub-hosted runners
+  and 35 days (unlimited in practice) for self-hosted runners. A single hung
+  step therefore silently consumes 6 hours of runner minutes and one complete
+  runner slot before GitHub kills the job.
+
+  Runner slot starvation is the secondary effect: while the hung job occupies a
+  runner, queued jobs wait. On self-hosted runners with limited capacity one
+  hung step can block an entire team's CI queue indefinitely.
+
+  This is a documented platform limitation tracked in actions/runner#1120
+  (220+ reactions, open since 2020) with no scheduled fix date.
+fix: |
+  Apply one of these workarounds depending on operating system:
+
+  Linux/macOS: Wrap the command with the system timeout utility (seconds):
+    run: timeout 300 ./integration-test.sh
+
+  Cross-platform: Use curl/Invoke-RestMethod built-in timeout options for
+  network calls, and test-runner native timeouts for test suites.
+
+  Always set timeout-minutes explicitly on every job to establish a hard upper
+  bound regardless of which step hangs.
+fix_code:
+  - language: yaml
+    label: 'Set explicit job timeout and use OS timeout for individual steps'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          timeout-minutes: 30    # explicit ceiling — never rely on 6h default
+
+          steps:
+            - uses: actions/checkout@v4
+
+            # Linux/macOS: system timeout (in seconds)
+            - name: Run integration tests
+              run: timeout 180 ./scripts/integration-test.sh
+
+            # Network call with built-in timeout
+            - name: Fetch external resource
+              run: |
+                curl --max-time 60 --retry 3 https://api.example.com/data -o data.json
+  - language: yaml
+    label: 'Self-hosted runner — conservative timeout prevents slot starvation'
+    code: |
+      jobs:
+        deploy:
+          runs-on: [self-hosted, production]
+          timeout-minutes: 45    # critical on self-hosted — hung jobs block all runners
+
+          steps:
+            - name: Deploy with timeout guard
+              shell: pwsh
+              run: |
+                $job = Start-Job { ./deploy.ps1 }
+                if (-not (Wait-Job $job -Timeout 120)) {
+                  Stop-Job $job
+                  throw "Deploy script timed out after 120s"
+                }
+                Receive-Job $job
+prevention:
+  - 'Always set explicit timeout-minutes on every job — never rely on the 6-hour GitHub-hosted default'
+  - 'Use OS-level timeout utilities (timeout on Linux/macOS) for individual network calls and scripts'
+  - 'Configure test-runner-native timeouts for test suites — they are more granular than job timeouts'
+  - 'Monitor runner queue depth on self-hosted runners — sudden growth often signals a hung step holding a slot'
+  - 'Set timeout-minutes: 5 on jobs you know should complete quickly to catch regressions early'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idtimeout-minutes'
+    label: 'GitHub Actions: jobs.<id>.timeout-minutes — job-level timeout (no step-level equivalent)'
+  - url: 'https://github.com/actions/runner/issues/1120'
+    label: 'actions/runner#1120: Feature request — step-level timeout (220+ reactions, open since 2020)'
+  - url: 'https://docs.github.com/en/actions/administering-github-actions/usage-limits-billing-and-administration#usage-limits'
+    label: 'GitHub Actions usage limits — default job timeout values per runner type'

package/errors/concurrency-timing/workflow-dispatch-push-shared-concurrency-silent-cancel.yml

@@ -0,0 +1,104 @@
+id: concurrency-timing-026
+title: 'workflow_dispatch run silently cancelled when push to same branch shares the concurrency group'
+category: concurrency-timing
+severity: silent-failure
+tags:
+  - concurrency
+  - workflow-dispatch
+  - cancel-in-progress
+  - push
+  - manual-trigger
+  - silent-cancel
+patterns:
+  - regex: 'This run was cancelled because another run in the same concurrency group'
+    flags: 'i'
+  - regex: 'Canceling run due to.*concurrency group'
+    flags: 'i'
+  - regex: 'This run has been canceled'
+    flags: 'i'
+error_messages:
+  - "This run was cancelled because another run in the same concurrency group is in progress."
+  - "Canceling run due to a newer request for the same concurrency group."
+  - "This run has been canceled."
+root_cause: |
+  A common concurrency pattern groups runs by workflow name and ref:
+
+    concurrency:
+      group: "${{ github.workflow }}-${{ github.ref }}"
+      cancel-in-progress: true
+
+  workflow_dispatch and push events on the same branch share identical
+  github.workflow and github.ref values, so they are placed in the same
+  concurrency slot.
+
+  A developer manually triggers a workflow_dispatch run (e.g., to deploy to
+  staging, run a migration, or kick off a release). While it is running, any
+  push to that branch — including a small documentation fix or revert — creates
+  a new run in the same concurrency slot and immediately cancels the in-progress
+  manual dispatch with no notification.
+
+  The developer discovers this only when checking on the deployment minutes
+  later to find it was cancelled mid-run. The automatic push run that replaced
+  it may be completely irrelevant to the manual operation.
+fix: |
+  Include github.event_name in the concurrency group key to give workflow_dispatch
+  and push events separate concurrency slots:
+
+    concurrency:
+      group: "${{ github.workflow }}-${{ github.event_name }}-${{ github.ref }}"
+      cancel-in-progress: true
+
+  workflow_dispatch runs now share a slot only with other workflow_dispatch runs
+  on the same branch, and push runs share a slot only with other push runs.
+
+  For deployment or migration workflows where even manual-vs-manual cancellation
+  is undesirable, use cancel-in-progress: false and let runs queue.
+fix_code:
+  - language: yaml
+    label: 'Include event_name in concurrency group — isolates manual from automatic triggers'
+    code: |
+      on:
+        push:
+          branches: [main]
+        workflow_dispatch:
+
+      concurrency:
+        # event_name isolates push and workflow_dispatch into separate concurrency slots
+        group: '${{ github.workflow }}-${{ github.event_name }}-${{ github.ref_name }}'
+        cancel-in-progress: true
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: ./deploy.sh
+  - language: yaml
+    label: 'Separate workflow file for manual operations — no cancel-in-progress'
+    code: |
+      # deploy-manual.yml — only triggered by workflow_dispatch
+      on:
+        workflow_dispatch:
+          inputs:
+            environment:
+              description: 'Target environment'
+              required: true
+              type: choice
+              options: [staging, production]
+
+      # No shared concurrency group with push workflows
+      concurrency:
+        group: 'manual-deploy-${{ github.event.inputs.environment }}'
+        # cancel-in-progress defaults to false — manual deploys queue, not cancel
+prevention:
+  - 'Always include github.event_name in concurrency group keys for workflows triggered by both push and workflow_dispatch'
+  - 'Use separate workflow files for manual deployment operations to avoid shared concurrency with automated triggers'
+  - 'Add a summary step or Telegram/Slack notification in the cleanup phase to alert when a run is cancelled mid-execution'
+  - 'Audit all concurrency group patterns when adding workflow_dispatch to an existing automated workflow'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/using-concurrency'
+    label: 'GitHub Actions: Using concurrency — group patterns and cancel-in-progress'
+  - url: 'https://github.com/orgs/community/discussions/5435'
+    label: 'GitHub Community: workflow_dispatch cancelled by push with same concurrency group'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#github-context'
+    label: 'GitHub context: github.event_name property'

package/errors/runner-environment/runner-workspace-vs-github-workspace-parent-directory.yml

@@ -0,0 +1,100 @@
+id: runner-environment-098
+title: "runner.workspace is the parent of the repo root — not the checked-out repo"
+category: runner-environment
+severity: silent-failure
+tags:
+  - runner.workspace
+  - github.workspace
+  - path
+  - working-directory
+  - context
+patterns:
+  - regex: 'runner\.workspace'
+    flags: i
+  - regex: '\$\{\{\s*runner\.workspace\s*\}\}'
+    flags: i
+error_messages:
+  - "No such file or directory"
+  - "Error: Path does not exist"
+  - "ENOENT: no such file or directory"
+root_cause: |
+  Two similarly-named contexts point to DIFFERENT directories on GitHub-hosted
+  runners:
+
+    github.workspace  = /home/runner/work/REPO/REPO   ← the checked-out repo root
+    runner.workspace  = /home/runner/work/REPO        ← one level ABOVE the repo root
+
+  runner.workspace is the "runner work directory" that CONTAINS the repo clone
+  folder, not the repo itself. The official documentation describes this distinction,
+  but the names are confusingly similar and many developers assume runner.workspace
+  is equivalent to "where my code is" — which is github.workspace.
+
+  Consequences:
+  - working-directory: ${{ runner.workspace }} silently points one level above
+    the repo, causing file-not-found errors on relative paths inside the repo.
+  - Path-building expressions like runner.workspace + '/src' resolve to a
+    path that doesn't exist.
+  - The error surfaces as "No such file or directory" or a missing file, not as
+    a context resolution failure, making the root cause hard to identify.
+
+  On some self-hosted runner configurations both paths may resolve to the same
+  directory, masking the bug until the workflow runs on a GitHub-hosted runner.
+
+  Source: GitHub Actions contexts documentation; GitHub Community/15327;
+  Stack Overflow path confusion questions with 100K+ combined views.
+fix: |
+  Replace runner.workspace with github.workspace (or the $GITHUB_WORKSPACE
+  environment variable) when the intent is to reference the checked-out repo root.
+
+  Use runner.workspace only when intentionally targeting the parent directory
+  that contains the repo clone — for example, creating a sibling directory for
+  build artifacts that should live outside the repo tree.
+fix_code:
+  - language: yaml
+    label: "Use github.workspace for the repo root"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            # ❌ WRONG — runner.workspace is one level ABOVE the repo
+            # - name: Wrong path
+            #   working-directory: ${{ runner.workspace }}
+
+            # ✅ CORRECT — github.workspace is the repo root
+            - name: List repo files
+              run: ls ${{ github.workspace }}
+
+            # ✅ ALSO CORRECT — $GITHUB_WORKSPACE env var is identical
+            - name: Build from repo root
+              working-directory: ${{ github.workspace }}
+              run: ls .
+
+            # ✅ Intentional use of runner.workspace — sibling dir outside repo
+            - name: Create output dir alongside repo
+              run: mkdir ${{ runner.workspace }}/build-output
+  - language: yaml
+    label: "Directory layout reference"
+    code: |
+      # GitHub-hosted runner path layout:
+      #
+      # /home/runner/work/
+      # └── my-repo/                 ← runner.workspace  (${{ runner.workspace }})
+      #     └── my-repo/             ← github.workspace  (${{ github.workspace }})
+      #         ├── src/
+      #         ├── package.json
+      #         └── .github/
+      #
+      # $GITHUB_WORKSPACE == ${{ github.workspace }} (same value, two access methods)
+prevention:
+  - "Always use github.workspace (or $GITHUB_WORKSPACE) to reference the checked-out repo root"
+  - "Reserve runner.workspace for intentional parent-directory operations such as sibling build directories"
+  - "When debugging path issues, print both: echo $GITHUB_WORKSPACE and echo ${{ runner.workspace }}"
+  - "Self-hosted runner paths may differ from GitHub-hosted runners — use named contexts rather than hardcoded absolute paths"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#github-context"
+    label: "GitHub Actions — github context (workspace)"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#runner-context"
+    label: "GitHub Actions — runner context (workspace)"

package/errors/silent-failures/actions-runner-debug-wrong-secret-name.yml

@@ -0,0 +1,90 @@
+id: silent-failures-045
+title: "ACTIONS_RUNNER_DEBUG / ACTIONS_STEP_DEBUG typo — debug logging silently disabled"
+category: silent-failures
+severity: silent-failure
+tags:
+  - debug
+  - ACTIONS_RUNNER_DEBUG
+  - ACTIONS_STEP_DEBUG
+  - secrets
+  - diagnostic
+patterns:
+  - regex: 'RUNNER_DEBUG'
+    flags: ''
+  - regex: 'ACTIONS_DEBUG'
+    flags: i
+error_messages: []
+root_cause: |
+  GitHub Actions debug logging is controlled by two specific repository secrets
+  (or repository variables since October 2023):
+
+    ACTIONS_RUNNER_DEBUG = "true"  — runner diagnostic logs (runner.diag.log,
+      Worker_*.log files attached to the run as a downloadable zip)
+    ACTIONS_STEP_DEBUG = "true"    — verbose step-level debug output shown
+      inline in each step log section
+
+  When developers set secrets with incorrect names such as RUNNER_DEBUG, DEBUG,
+  ACTIONS_DEBUG, or ENABLE_DEBUG, GitHub silently ignores them. The workflow
+  runs normally with no indication that debug logging was never activated.
+  The developer sees only standard log output and assumes there is nothing more
+  to inspect.
+
+  A secondary failure mode: setting these as workflow-level env: variables has
+  no effect — debug logging requires them as repository secrets or repository
+  variables, not env: entries.
+
+  Source: GitHub Docs — Enabling debug logging; GitHub Community recurring
+  reports of debug logs not appearing despite secrets being set.
+fix: |
+  Set repository secrets or repository variables with the EXACT names:
+    ACTIONS_RUNNER_DEBUG  (value: true)
+    ACTIONS_STEP_DEBUG    (value: true)
+
+  Path: Repository Settings → Secrets and variables → Actions → New repository secret.
+
+  These can also be set at the organization level to apply across all repos.
+
+  Runner diagnostic logs from ACTIONS_RUNNER_DEBUG are available as a
+  downloadable zip file attached to the workflow run — not shown inline.
+  Step debug logs from ACTIONS_STEP_DEBUG appear inline in each step as
+  collapsed "##[debug]" lines.
+fix_code:
+  - language: yaml
+    label: "workflow_dispatch input to enable debug for a single run without changing secrets"
+    code: |
+      on:
+        workflow_dispatch:
+          inputs:
+            debug_enabled:
+              type: boolean
+              description: 'Enable step debug logging for this run'
+              default: false
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Enable step debug mode
+              if: ${{ inputs.debug_enabled }}
+              run: echo "ACTIONS_STEP_DEBUG=true" >> $GITHUB_ENV
+
+            - name: Build step (verbose when debug enabled)
+              run: echo "Build running"
+  - language: yaml
+    label: "Check which debug secrets are active"
+    code: |
+      - name: Show debug context
+        run: |
+          echo "Runner debug: $ACTIONS_RUNNER_DEBUG"
+          echo "Step debug:   $ACTIONS_STEP_DEBUG"
+          # If these print empty string, the secrets are not set or named incorrectly
+prevention:
+  - "Use exactly 'ACTIONS_RUNNER_DEBUG' and 'ACTIONS_STEP_DEBUG' as the secret names — no other names work"
+  - "Set these as repository secrets or repository variables, not as env: in workflow YAML"
+  - "ACTIONS_RUNNER_DEBUG logs are in a separate zip download — check the run's uploaded artifacts section"
+  - "Both secrets can be enabled simultaneously; they control independent output streams"
+docs:
+  - url: "https://docs.github.com/en/actions/monitoring-and-troubleshooting-workflows/troubleshooting-workflows/enabling-debug-logging"
+    label: "GitHub Docs — Enabling debug logging"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables"
+    label: "GitHub Docs — Storing information in variables"

package/errors/silent-failures/github-env-vars-not-shared-across-jobs.yml

@@ -0,0 +1,96 @@
+id: silent-failures-047
+title: "GITHUB_ENV variables are job-scoped — not shared with downstream needs: jobs"
+category: silent-failures
+severity: silent-failure
+tags:
+  - GITHUB_ENV
+  - environment-variables
+  - job-outputs
+  - cross-job
+  - silent-failure
+patterns:
+  - regex: 'GITHUB_ENV'
+    flags: ''
+  - regex: 'echo\s+".+=.+"\s*>>\s*\$GITHUB_ENV'
+    flags: i
+error_messages: []
+root_cause: |
+  Environment variables written to $GITHUB_ENV are scoped to the CURRENT JOB
+  only. They persist across all subsequent steps within that job, but are NOT
+  propagated to any other job — including jobs that depend on the producing
+  job via needs:.
+
+  This is a silent failure because:
+  1. The producing step exits 0 with no warning
+  2. The downstream job runs normally with no error message
+  3. The variable evaluates to empty string in the downstream job
+  4. Steps that depend on the value produce wrong results or silently skip
+     based on the empty string condition
+
+  Common scenario (silently broken):
+    Job A: echo "VERSION=1.2.3" >> $GITHUB_ENV
+    Job B (needs: job-a): echo $VERSION  → prints empty string
+
+  The correct mechanism for sharing values across job boundaries is job outputs
+  combined with the needs context. GITHUB_ENV is appropriate only for values
+  that need to persist across multiple steps within the same job.
+
+  Source: GitHub Docs — Passing information between jobs; GitHub Community and
+  Stack Overflow cross-job environment variable questions.
+fix: |
+  To pass a value from one job to a downstream job:
+
+  1. Write the value to $GITHUB_OUTPUT (not $GITHUB_ENV) in the producing step
+  2. Declare the step output in the producing job's outputs: block
+  3. Reference the value in the consuming job via ${{ needs.job-id.outputs.key }}
+
+  Continue using $GITHUB_ENV when the value only needs to be available to later
+  steps within the same job.
+fix_code:
+  - language: yaml
+    label: "Correct cross-job value sharing via GITHUB_OUTPUT and job outputs"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          outputs:
+            # Expose the step output as a job output
+            version: ${{ steps.get-version.outputs.version }}
+          steps:
+            - id: get-version
+              # Write to GITHUB_OUTPUT for cross-job sharing, not GITHUB_ENV
+              run: echo "version=1.2.3" >> $GITHUB_OUTPUT
+
+        deploy:
+          needs: build
+          runs-on: ubuntu-latest
+          steps:
+            - name: Use version from build job
+              run: echo "Deploying version ${{ needs.build.outputs.version }}"
+  - language: yaml
+    label: "GITHUB_ENV is correct for within-job cross-step sharing"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Set version for this job's steps
+              run: echo "VERSION=1.2.3" >> $GITHUB_ENV
+
+            - name: Step 2 in same job — $VERSION is available
+              run: echo "Building $VERSION"
+
+            - name: Step 3 in same job — $VERSION is still available
+              run: echo "Packaging $VERSION"
+
+            # $VERSION is NOT available in any other job
+prevention:
+  - "Use GITHUB_OUTPUT + job outputs: for any value that must cross a job boundary"
+  - "Use GITHUB_ENV only for values shared between steps within the same job"
+  - "Add a verification step in the consuming job that echoes the value and fails if empty"
+  - "Avoid setting both GITHUB_ENV and GITHUB_OUTPUT for the same value — use GITHUB_OUTPUT as the single source of truth"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/passing-information-between-jobs"
+    label: "GitHub Docs — Passing information between jobs"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables"
+    label: "GitHub Docs — Storing information in variables (GITHUB_ENV)"

package/errors/silent-failures/matrix-exclude-value-mismatch-silently-ignored.yml

@@ -0,0 +1,96 @@
+id: silent-failures-046
+title: "matrix.exclude silently ignored when value doesn't exactly match matrix dimension"
+category: silent-failures
+severity: silent-failure
+tags:
+  - matrix
+  - exclude
+  - strategy
+  - configuration
+  - silent-failure
+patterns:
+  - regex: 'exclude:'
+    flags: ''
+  - regex: 'strategy:\s*\n\s*matrix:'
+    flags: im
+error_messages: []
+root_cause: |
+  GitHub Actions matrix exclude: uses exact string equality. An exclude entry
+  removes a combination only when ALL specified key-value pairs exactly match
+  a generated matrix combination. If any pair fails to match, the combination
+  is silently kept.
+
+  Three common silent-failure patterns:
+
+  1. Value substring mismatch:
+       matrix: {os: [ubuntu-latest, windows-latest]}
+       exclude: [{os: ubuntu}]          # 'ubuntu' != 'ubuntu-latest' → ignored
+
+  2. Key not present in matrix dimensions:
+       matrix: {os: [ubuntu-latest], node: [18, 20]}
+       exclude: [{os: ubuntu-latest, version: 18}]   # 'version' not a matrix key → ignored
+
+  3. Type mismatch in some expression contexts:
+       matrix: {node: [18, 20]}
+       exclude: [{node: "18"}]           # string "18" may not equal integer 18
+
+  GitHub produces no warning when an exclude entry matches zero combinations.
+  The unwanted job continues to run, consuming CI minutes with no indication
+  that the exclude rule was ineffective.
+
+  Source: GitHub Docs matrix strategy; GitHub Community/26957; Stack Overflow
+  questions about matrix exclude not working as expected.
+fix: |
+  Use the exact string that appears in your matrix definition when writing
+  exclude entries. Run a matrix debug step to confirm the actual values
+  GitHub generates before relying on exclusions.
+
+  For complex exclusion logic involving substring matching or multiple
+  conditions, use the if: condition on the job instead of exclude:.
+  The if: condition can use contains(), startsWith(), and other expression
+  functions that exact-match exclude cannot.
+fix_code:
+  - language: yaml
+    label: "Correct exclude — exact value match required"
+    code: |
+      jobs:
+        test:
+          strategy:
+            matrix:
+              os: [ubuntu-latest, windows-latest, macos-latest]
+              node: [18, 20, 22]
+              exclude:
+                # Value must match EXACTLY what appears in the matrix list above
+                - os: windows-latest    # ✅ exact match
+                  node: 18
+                # Incorrect examples (silently ignored):
+                # - os: windows         # ❌ 'windows' != 'windows-latest'
+                # - os: windows-latest
+                #   version: 18         # ❌ 'version' not a matrix dimension key
+          runs-on: ${{ matrix.os }}
+          steps:
+            - name: Debug matrix combination
+              run: echo '${{ toJSON(matrix) }}'
+  - language: yaml
+    label: "Alternative — use if: for flexible exclusion"
+    code: |
+      jobs:
+        test:
+          # Use if: when you need startsWith / contains logic
+          if: >-
+            !(matrix.os == 'windows-latest' && matrix.node == 18)
+          strategy:
+            matrix:
+              os: [ubuntu-latest, windows-latest]
+              node: [18, 20]
+          runs-on: ${{ matrix.os }}
+prevention:
+  - "Use the exact strings from your matrix definition in exclude entries — copy-paste, do not retype"
+  - "Add a debug step printing toJSON(matrix) to verify which combinations GitHub actually generates"
+  - "Use if: conditions for substring matching, contains(), or multi-condition exclusion logic"
+  - "Test matrix changes on a branch and review the job list before merging to confirm excluded combinations are gone"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/running-variations-of-jobs-in-a-workflow#excluding-matrix-configurations"
+    label: "GitHub Docs — Excluding matrix configurations"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/using-conditions-to-control-job-execution"
+    label: "GitHub Docs — Using conditions to control job execution"

package/package.json

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