@htekdev/actions-debugger 1.0.11 → 1.0.12

package/errors/known-unsolved/matrix-outputs-last-writer-wins.yml

@@ -0,0 +1,137 @@
+id: known-unsolved-011
+title: "Matrix Job Outputs Are Non-Deterministic — Only Last Completed Job's Value Is Used"
+category: known-unsolved
+severity: silent-failure
+tags:
+  - matrix
+  - outputs
+  - non-deterministic
+  - race-condition
+  - jobs-outputs
+  - strategy
+patterns:
+  - regex: "jobs\\.\\w+\\.outputs\\.\\w+"
+    flags: "i"
+  - regex: "matrix.*output.*overwrite"
+    flags: "i"
+  - regex: "only.*last.*matrix.*job.*output"
+    flags: "i"
+error_messages:
+  - "outputs from matrix returns only the last value"
+  - "matrix job output overwritten by later-completing job"
+root_cause: |
+  GitHub Actions does not support aggregating outputs across matrix jobs. When a job uses
+  `strategy: matrix:` and defines `outputs:`, all matrix instances write to the SAME
+  output key. The value that survives is whichever matrix job completes LAST — and
+  completion order is non-deterministic.
+
+  Example: a 3-element matrix writing `result` as an output. Job [A, B, C] may complete
+  in any order — the downstream job receives only the output from whichever finished last.
+  This can silently produce wrong results that vary between runs.
+
+  The underlying limitation: `jobs.<job_id>.outputs` maps to a single scalar value
+  per key, with no way to collect values from all matrix instances into a structured
+  result. The runner simply last-writes-wins with no conflict detection.
+
+  This is a long-standing limitation tracked in actions/runner#1835 (opened April 2022)
+  and actions/runner#2477. A partial improvement in runner v2.303.0 added `$matrix`
+  context to outputs expressions, but it is still not generally available and has known
+  bugs (runner#2499: workflow won't start with the new syntax on older runners).
+
+  Source: actions/runner#1835 (Outputs from matrix returns only the last value)
+  Source: Stack Overflow #70287603 (Dynamic outputs for job with strategy.matrix)
+fix: |
+  There is no native GitHub Actions solution for collecting all matrix job outputs into
+  a structured result. Use one of these workarounds:
+
+  Workaround 1 — Write to artifacts, aggregate downstream:
+    Each matrix job writes its result to a uniquely-named artifact file. A downstream
+    aggregator job downloads all artifacts and processes them.
+
+  Workaround 2 — Encode outputs in artifact JSON, then use as dynamic matrix:
+    Popularized by the `matrix-output` marketplace action. Each job appends a JSON row
+    to an artifact, and a reporting job downloads and merges them.
+
+  Workaround 3 — Use reusable workflows with known job indices:
+    Reusable workflows allow accessing specific job outputs via the caller's
+    `jobs.<reusable_workflow_job>.outputs` context.
+
+  Workaround 4 — Consolidate into a single non-matrix job:
+    If the matrix outputs must be consumed, consider restructuring to run the work
+    sequentially in one job or use a scripted loop.
+fix_code:
+  - language: yaml
+    label: "Workaround: write output to artifact file, aggregate in downstream job"
+    code: |
+      jobs:
+        build:
+          strategy:
+            matrix:
+              component: [api, web, worker]
+          runs-on: ubuntu-latest
+          steps:
+            - name: Build component
+              run: |
+                # ... build logic ...
+                echo "build_status=success" >> result-${{ matrix.component }}.txt
+
+            - name: Upload result artifact
+              uses: actions/upload-artifact@v4
+              with:
+                name: result-${{ matrix.component }}
+                path: result-${{ matrix.component }}.txt
+
+        aggregate:
+          needs: build
+          runs-on: ubuntu-latest
+          steps:
+            - name: Download all results
+              uses: actions/download-artifact@v4
+              with:
+                pattern: result-*
+                merge-multiple: true
+
+            - name: Aggregate results
+              run: |
+                for f in result-*.txt; do
+                  echo "=== $f ==="
+                  cat "$f"
+                done
+
+  - language: yaml
+    label: "Anti-pattern: matrix outputs — only one value survives (last writer wins)"
+    code: |
+      # ❌ WRONG — only last-completing job's output is used by downstream-job
+      jobs:
+        build:
+          strategy:
+            matrix:
+              component: [api, web, worker]
+          runs-on: ubuntu-latest
+          outputs:
+            status: ${{ steps.build.outputs.status }}   # ← non-deterministic!
+          steps:
+            - id: build
+              run: echo "status=done-${{ matrix.component }}" >> $GITHUB_OUTPUT
+
+        downstream-job:
+          needs: build
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "${{ needs.build.outputs.status }}"
+            # Prints ONE value (whichever matrix job finished last) — unpredictable
+
+prevention:
+  - "Never rely on matrix job outputs for per-job values — outputs are not aggregated."
+  - "Use upload-artifact/download-artifact with unique names per matrix dimension to collect per-job results."
+  - "If a downstream job needs all matrix results, prefer artifact-based aggregation over job outputs."
+  - "Document in your workflow comments that matrix outputs are single-valued and non-deterministic."
+docs:
+  - url: "https://github.com/actions/runner/issues/1835"
+    label: "actions/runner#1835: Outputs from matrix returns only the last value"
+  - url: "https://stackoverflow.com/questions/70287603/dynamic-outputs-for-job-with-strategy-matrix"
+    label: "Stack Overflow: Dynamic outputs for job with strategy.matrix"
+  - url: "https://github.com/marketplace/actions/matrix-output"
+    label: "Marketplace: matrix-output action (artifact-based aggregation workaround)"
+  - 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"

package/errors/known-unsolved/uses-key-no-expression-support.yml

@@ -0,0 +1,134 @@
+id: known-unsolved-012
+title: "uses: Key Does Not Support Expressions or Context Variables — Must Be a Static String"
+category: known-unsolved
+severity: error
+tags:
+  - uses
+  - expression
+  - context
+  - dynamic-action
+  - composite
+  - local-action
+patterns:
+  - regex: "uses:\\s*\\.?/\\$\\{\\{"
+    flags: "i"
+  - regex: "uses:\\s*['\"]?\\$\\{\\{"
+    flags: "i"
+  - regex: "Unrecognized named-value.*uses"
+    flags: "i"
+  - regex: "Invalid workflow file.*uses.*expression"
+    flags: "i"
+error_messages:
+  - "Invalid workflow file: .github/workflows/ci.yml — uses: does not support expression syntax"
+  - "The 'uses' field must be a literal string and cannot contain expressions"
+  - "Unrecognized named-value: 'env' at position 1 within expression in uses:"
+root_cause: |
+  GitHub Actions resolves all `uses:` references (actions and reusable workflows) BEFORE
+  the job starts executing — at workflow evaluation / job queue time. At that point,
+  no runtime contexts (env, inputs, github, matrix, steps, needs) are available.
+
+  As a result, you cannot use `${{ }}` expression syntax in a `uses:` key at any level:
+    - Step-level: `uses: ${{ env.MY_ACTION }}@${{ env.VERSION }}` ❌
+    - Local path with variable: `uses: ./${{ env.DIR }}/my-action` ❌
+    - Dynamic version pin: `uses: actions/setup-node@${{ inputs.node-version }}` ❌
+    - Reusable workflow: `uses: ${{ github.repository }}/.github/workflows/ci.yml@main` ❌
+
+  This is an architectural constraint: the runner must download and validate actions
+  (and reusable workflows) before any step code can run. Allowing runtime expressions
+  would break policy enforcement (org-level allowed-actions lists) and make workflow
+  graphs non-deterministic at parse time.
+
+  Note: `env:` and `with:` inputs to an action DO support expressions — only the `uses:`
+  key itself is restricted.
+
+  Source: actions/runner#1479 (Support context/matrix variables in steps of type 'uses')
+  Source: actions/runner#895 (Allow expressions in uses:)
+  Source: Stack Overflow #75373413 (Reference a variable in uses when pointing to a path)
+fix: |
+  There is no native GitHub Actions solution for dynamic `uses:` values.
+
+  Option 1 — Hard-code the version or path (recommended for most cases):
+    Pin versions explicitly in the workflow file. Use Dependabot or Renovate to keep
+    action versions updated automatically.
+
+  Option 2 — Use a composite action or script as a dispatcher:
+    Create a wrapper composite action that accepts an input and uses `if:` conditions
+    to call different static actions based on the input value.
+
+  Option 3 — Use step-security/dynamic-uses (third-party workaround):
+    The `dynamic-uses` action by step-security resolves and invokes actions dynamically
+    at runtime. This works around the limitation but adds a third-party dependency.
+
+  Option 4 — Restructure to not need dynamic action references:
+    If you're trying to select between local action paths, check out the repo first and
+    use a scripted approach instead of composite action dispatch.
+fix_code:
+  - language: yaml
+    label: "Anti-pattern — expressions in uses: cause parse error"
+    code: |
+      # ❌ WRONG — none of these are supported
+      steps:
+        - uses: ./${{ env.ACTION_DIR }}/my-action         # ← parse error
+        - uses: actions/setup-node@${{ inputs.version }}  # ← parse error
+        - uses: ${{ github.repository }}/.github/workflows/deploy.yml@main  # ← error
+
+  - language: yaml
+    label: "Fix: hard-code the version, use Dependabot to keep it updated"
+    code: |
+      # ✅ CORRECT — static string in uses:
+      steps:
+        - uses: actions/setup-node@v4          # pin to major version
+        - uses: actions/setup-node@11.0.0      # or exact version
+        - uses: ./.github/actions/my-action    # local action: always relative to repo root
+
+      # Keep versions current with Dependabot (.github/dependabot.yml):
+      # version: 2
+      # updates:
+      #   - package-ecosystem: "github-actions"
+      #     directory: "/"
+      #     schedule:
+      #       interval: "weekly"
+
+  - language: yaml
+    label: "Workaround: if-based dispatch when choosing between known static actions"
+    code: |
+      # ✅ Conditional dispatch using if: conditions on static uses:
+      steps:
+        - name: Setup Node (version from input)
+          uses: actions/setup-node@v4
+          with:
+            node-version: ${{ inputs.node-version }}   # ← with: supports expressions
+
+        # If you truly need different actions based on input:
+        - name: Use action for staging
+          if: inputs.environment == 'staging'
+          uses: ./actions/deploy-staging              # static path
+
+        - name: Use action for production
+          if: inputs.environment == 'production'
+          uses: ./actions/deploy-production           # static path
+
+  - language: yaml
+    label: "Workaround: step-security/dynamic-uses third-party action"
+    code: |
+      # Third-party workaround — resolves expressions in uses: at runtime
+      steps:
+        - uses: step-security/dynamic-uses@v1
+          with:
+            uses: actions/setup-node@${{ inputs.node-version }}
+            with: '{ "node-version": 18 }'
+
+prevention:
+  - "Always use static literal strings in `uses:` keys — no `${{ }}` expressions."
+  - "Use `with:` inputs (which DO support expressions) to pass dynamic values to actions."
+  - "Use Dependabot or Renovate to automate action version bumps so manual pinning stays current."
+  - "For environment-specific action selection, use `if:` conditions on separate steps with static `uses:` values."
+docs:
+  - url: "https://github.com/actions/runner/issues/1479"
+    label: "actions/runner#1479: Support context/matrix variables in steps of type 'uses'"
+  - url: "https://github.com/actions/runner/issues/895"
+    label: "actions/runner#895: Allow expressions in uses: key"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-pre-written-building-blocks-in-your-workflow"
+    label: "GitHub Docs: Using pre-written building blocks (actions)"
+  - url: "https://github.com/step-security/dynamic-uses"
+    label: "step-security/dynamic-uses: third-party workaround for dynamic uses:"

package/errors/runner-environment/windows-default-shell-powershell-not-bash.yml

@@ -0,0 +1,137 @@
+id: runner-environment-033
+title: "Windows Runner Default Shell Is PowerShell — Bash Scripts Silently Fail Without shell: bash"
+category: runner-environment
+severity: error
+tags:
+  - windows
+  - shell
+  - bash
+  - powershell
+  - default-shell
+  - run-step
+  - cross-platform
+patterns:
+  - regex: "shell:\\s*C:\\\\Windows\\\\system32\\\\bash\\.EXE"
+    flags: "i"
+  - regex: "The term '.*' is not recognized.*cmdlet.*function.*script"
+    flags: "i"
+  - regex: "pwsh.*noprofile.*noninteractive.*command"
+    flags: "i"
+  - regex: "bash.*error.*not.*recognized.*windows"
+    flags: "i"
+error_messages:
+  - "The term 'set' is not recognized as the name of a cmdlet, function, script file"
+  - "Unrecognized token '||' in pipeline"
+  - "shell: C:\\Windows\\system32\\bash.EXE --noprofile --norc -e -o pipefail {0}: No such file or directory"
+  - "export: The term 'export' is not recognized as the name of a cmdlet"
+root_cause: |
+  GitHub Actions uses a different default shell depending on the runner OS:
+    - Linux (ubuntu-*): bash
+    - macOS (macos-*): bash
+    - Windows (windows-*): PowerShell (pwsh)
+
+  When you write `run:` steps using bash syntax (e.g., `export VAR=value`, `set -e`,
+  `||`, `&&`, heredocs, `$(...)` subshells) without explicitly specifying `shell: bash`,
+  those steps will execute under PowerShell on Windows runners and fail with confusing
+  errors.
+
+  This is especially problematic in:
+    - Matrix workflows that include both Linux and Windows OS variants
+    - Composite actions where the shell is not explicitly set per step
+    - Reusable workflows called from both Linux and Windows jobs
+    - Migration from Linux-only workflows to cross-platform
+
+  A secondary issue: on Windows runners, if `C:\Windows\System32\bash.exe` exists
+  (WSL stub), specifying `shell: bash` may invoke the WSL stub instead of Git Bash
+  (`C:\Program Files\Git\bin\bash.EXE`). This causes "No such file or directory"
+  errors because the WSL stub requires a Linux distribution to be installed.
+  Since runner-images#12646, this is a known issue with no GitHub-side fix.
+
+  Source: actions/runner#1328 (Unable to run bash scripts on Windows runner)
+  Source: runner-images#12646 (Windows WSL bash.exe stub causes shell: bash failures)
+fix: |
+  Always explicitly set `shell: bash` on any `run:` step that uses bash syntax.
+
+  For cross-platform matrix workflows, there are three approaches:
+
+  1. Explicit shell per step — add `shell: bash` to every bash step.
+
+  2. Workflow-level default — set `defaults.run.shell: bash` to apply bash to ALL
+     run steps in the workflow (be consistent — all steps must then use bash syntax).
+
+  3. Job-level default — set `defaults.run.shell: bash` at the job level to scope it.
+
+  If you need PowerShell on Windows AND bash on Linux in the same matrix, use a
+  matrix-aware condition to selectively set the shell, or split into separate jobs.
+fix_code:
+  - language: yaml
+    label: "Fix: explicit shell: bash on individual steps"
+    code: |
+      jobs:
+        test:
+          strategy:
+            matrix:
+              os: [ubuntu-latest, windows-latest, macos-latest]
+          runs-on: ${{ matrix.os }}
+          steps:
+            - uses: actions/checkout@v4
+
+            # ✅ Always specify shell: bash for bash scripts
+            - name: Run build script
+              shell: bash         # required on Windows — default is PowerShell
+              run: |
+                export BUILD_ENV=production
+                set -euo pipefail
+                ./scripts/build.sh
+
+  - language: yaml
+    label: "Fix: workflow-level default shell (applies to all run steps)"
+    code: |
+      name: Cross-Platform CI
+
+      defaults:
+        run:
+          shell: bash    # override default — all run steps use bash on all OS
+
+      jobs:
+        test:
+          strategy:
+            matrix:
+              os: [ubuntu-latest, windows-latest, macos-latest]
+          runs-on: ${{ matrix.os }}
+          steps:
+            - uses: actions/checkout@v4
+            - name: Run tests
+              run: |
+                # This runs in bash on all platforms
+                ./scripts/run-tests.sh
+
+  - language: yaml
+    label: "Anti-pattern: bash syntax without shell: bash on Windows fails"
+    code: |
+      # ❌ WRONG on Windows — default shell is PowerShell, bash syntax breaks
+      jobs:
+        build:
+          runs-on: windows-latest
+          steps:
+            - name: Set env
+              run: |
+                export DEPLOY_ENV=production    # ← ERROR: 'export' not recognized
+                echo "env: $DEPLOY_ENV"         # ← ERROR: bash variable expansion
+                ls -la                          # ← ERROR: ls -la not valid in pwsh
+
+prevention:
+  - "Always specify `shell: bash` (or `shell: pwsh`) explicitly on every `run:` step in cross-platform workflows."
+  - "Use `defaults.run.shell: bash` at the workflow or job level to reduce repetition."
+  - "Test all matrix OS variants in CI — don't assume Linux behavior translates to Windows."
+  - "For PowerShell-specific steps on Windows, use `shell: pwsh` explicitly rather than relying on the default."
+  - "Avoid relying on the runner's WSL bash stub on Windows — it requires a WSL distribution installed."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/setting-a-default-shell-and-working-directory"
+    label: "GitHub Docs: Setting a default shell and working directory"
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsshell"
+    label: "GitHub Docs: jobs.<job_id>.steps[*].shell"
+  - url: "https://github.com/actions/runner/issues/1328"
+    label: "actions/runner#1328: Unable to run bash scripts on Windows runner"
+  - url: "https://github.com/actions/runner-images/issues/12646"
+    label: "runner-images#12646: Windows WSL bash.exe stub causes shell: bash failures"

package/errors/silent-failures/pull-request-ref-is-merge-ref.yml

@@ -0,0 +1,134 @@
+id: silent-failures-014
+title: "pull_request github.ref Is refs/pull/N/merge — Branch-Name Conditions Silently Evaluate to False"
+category: silent-failures
+severity: silent-failure
+tags:
+  - pull_request
+  - github-ref
+  - merge-ref
+  - branch-name
+  - if-condition
+  - head-ref
+  - base-ref
+patterns:
+  - regex: "github\\.ref\\s*==\\s*['\"]refs/heads/"
+    flags: "i"
+  - regex: "GITHUB_REF.*refs/pull/\\d+/merge"
+    flags: "i"
+  - regex: "github\\.ref.*startsWith.*refs/heads"
+    flags: "i"
+error_messages:
+  - "refs/pull/123/merge"
+  - "Conditional check 'github.ref == refs/heads/main' evaluated to false on pull_request event"
+  - "GITHUB_REF=refs/pull/47/merge"
+root_cause: |
+  When a workflow is triggered by the `pull_request` (or `pull_request_target`) event,
+  `github.ref` is set to `refs/pull/<number>/merge` — NOT the source branch name.
+
+  This `refs/pull/<N>/merge` is a synthetic Git reference created by GitHub representing
+  the prospective merge commit (the merge of the PR's head branch into the base branch).
+  It does not correspond to any named branch.
+
+  Developers commonly write conditions expecting `github.ref` to contain the branch name:
+    - `if: github.ref == 'refs/heads/feature-branch'`  → always false on PR events
+    - `if: startsWith(github.ref, 'refs/heads/')`       → always false on PR events
+    - `if: github.ref != 'refs/heads/main'`             → always true on PR events
+
+  These conditions silently pass or silently skip — no error is reported. The job
+  simply runs (or doesn't run) with no indication that the ref check was wrong.
+
+  The correct context variables for PR events are:
+    - `github.head_ref` — the source branch name (e.g., "feature/my-branch")
+    - `github.base_ref` — the target branch name (e.g., "main")
+    - `github.event.pull_request.head.ref` — same as head_ref
+    - `github.event.pull_request.base.ref` — same as base_ref
+
+  Note: `github.head_ref` and `github.base_ref` are ONLY set for pull_request events.
+  For push events, use `github.ref_name` instead.
+
+  Source: Stack Overflow #68708792 (what is github.ref when merging PR to master)
+  Source: Stack Overflow #78162051 (obtain branch name in github action on pull_request)
+  Docs: https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#github-context
+fix: |
+  Use the correct context variable depending on what information you need:
+
+  For the PR source branch:
+    Use `github.head_ref` (not `github.ref`)
+
+  For the PR target branch:
+    Use `github.base_ref` (not `github.ref`)
+
+  For branch-scoped conditions that need to work across BOTH push and pull_request:
+    Use `github.ref_name` (gives branch/tag name without refs/heads/ prefix)
+    Or use `github.event_name` to gate the condition by event type
+
+  To check if a push or PR targets the main branch:
+    - Push: `github.ref == 'refs/heads/main'`
+    - PR:   `github.base_ref == 'main'`
+    - Both: use separate conditions gated by `github.event_name`
+fix_code:
+  - language: yaml
+    label: "Fix: use github.head_ref for PR source branch, base_ref for target"
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            # ❌ WRONG: github.ref on pull_request is refs/pull/N/merge — never matches heads/*
+            - name: Wrong branch check
+              if: github.ref == 'refs/heads/feature-branch'  # always false on PR!
+              run: echo "this never runs on PR events"
+
+            # ✅ CORRECT: use head_ref for the source branch name
+            - name: Correct branch check
+              if: github.head_ref == 'feature-branch'
+              run: echo "this runs when PR source branch is feature-branch"
+
+            # ✅ CORRECT: use base_ref for the target branch name
+            - name: Check if targeting main
+              if: github.base_ref == 'main'
+              run: echo "this PR is targeting main"
+
+  - language: yaml
+    label: "Cross-event condition: works for both push and pull_request"
+    code: |
+      jobs:
+        conditional:
+          runs-on: ubuntu-latest
+          steps:
+            # Works for both push (github.ref_name) and PR (github.base_ref)
+            - name: Is this targeting/on main?
+              if: |
+                (github.event_name == 'push' && github.ref == 'refs/heads/main') ||
+                (github.event_name == 'pull_request' && github.base_ref == 'main')
+              run: echo "targeting or on main branch"
+
+            # Simpler: github.ref_name works for push; for PR it returns the merge ref number
+            # Best to keep push and pull_request logic separate with event_name guards
+
+  - language: yaml
+    label: "Debug step: print all relevant refs for troubleshooting"
+    code: |
+      - name: Debug refs
+        run: |
+          echo "event_name:  ${{ github.event_name }}"
+          echo "ref:         ${{ github.ref }}"
+          echo "ref_name:    ${{ github.ref_name }}"
+          echo "head_ref:    ${{ github.head_ref }}"
+          echo "base_ref:    ${{ github.base_ref }}"
+          # On push/branch: ref=refs/heads/main, head_ref='', base_ref=''
+          # On pull_request: ref=refs/pull/47/merge, head_ref=feature-x, base_ref=main
+
+prevention:
+  - "Never use `github.ref` to get the branch name in `pull_request` triggered workflows — it is not a branch ref."
+  - "Use `github.head_ref` for the PR source branch and `github.base_ref` for the target branch."
+  - "For conditions that span both push and pull_request events, gate on `github.event_name` first."
+  - "Add a debug step printing `github.ref`, `github.head_ref`, and `github.base_ref` when debugging trigger conditions."
+  - "Use `github.ref_name` (branch/tag name without prefix) for push events instead of stripping `refs/heads/` manually."
+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 Docs: github context (ref, head_ref, base_ref, ref_name)"
+  - url: "https://stackoverflow.com/questions/68708792/what-is-github-ref-when-merging-pr-to-master"
+    label: "Stack Overflow: What is github.ref when merging PR to master?"
+  - url: "https://stackoverflow.com/questions/78162051/obtain-branch-name-in-github-action-on-pull-request"
+    label: "Stack Overflow: Obtain branch name in github action on pull request"

package/errors/triggers/push-paths-filter-bypassed-by-tag.yml

@@ -0,0 +1,123 @@
+id: triggers-012
+title: "Tag Pushes Bypass paths: Filter — Workflow Fires on Every Tag Regardless of Changed Files"
+category: triggers
+severity: silent-failure
+tags:
+  - push
+  - tags
+  - paths-filter
+  - tag-push
+  - trigger
+  - branches
+patterns:
+  - regex: "on:\\s*\\n\\s*push:\\s*\\n\\s*(\\w[^\\n]*\\n\\s*)*paths:"
+    flags: "im"
+  - regex: "Triggered by refs/tags/"
+    flags: "i"
+  - regex: "push.*paths.*tags.*ignored"
+    flags: "i"
+error_messages:
+  - "Run triggered by push to refs/tags/v1.0.0"
+  - "Evaluation skipped: tag push does not evaluate path filters"
+root_cause: |
+  GitHub Actions evaluates `paths:` and `paths-ignore:` filters ONLY for branch pushes.
+  When a tag is pushed, path filters are completely bypassed — the workflow runs regardless
+  of which files were changed.
+
+  This means a workflow like:
+
+    on:
+      push:
+        paths:
+          - "src/**"
+
+  will fire on every tag push (e.g., `git push origin v1.2.3`) even if no files under
+  `src/` were modified in the tagged commit.
+
+  Additionally, if a workflow has `on: push:` with NO branches/tags filter, a tag push
+  produces a `push` webhook event that triggers the workflow. Developers expect tag pushes
+  to be governed by path filters, but the docs explicitly state path filters are not
+  evaluated for tag events.
+
+  Source: actions/runner#3933 (path filters not respected for tag pushes)
+  Source: Stack Overflow #76037078 (paths also triggered when pushing a new tag)
+  Docs: https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/triggering-a-workflow#using-filters-to-target-specific-paths-for-pull-request-or-push-events
+fix: |
+  If you want path-filtered push workflows to run ONLY on branch pushes (not tag pushes),
+  explicitly add a `tags-ignore: ["**"]` filter or restrict to branches explicitly.
+
+  Option A — Add `tags-ignore` to suppress all tag events:
+    on:
+      push:
+        paths:
+          - "src/**"
+        tags-ignore:
+          - "**"
+
+  Option B — Add an explicit `branches` filter (only branch pushes match):
+    on:
+      push:
+        branches:
+          - "**"         # all branches
+        paths:
+          - "src/**"
+
+  Note: Option B is equivalent — defining `branches` or `tags` implicitly excludes the
+  other git ref type from triggering the workflow.
+fix_code:
+  - language: yaml
+    label: "Add tags-ignore to prevent tag pushes from bypassing path filters"
+    code: |
+      on:
+        push:
+          # Path filter only works for branch pushes — add tags-ignore to prevent
+          # tag pushes from triggering this workflow unconditionally.
+          tags-ignore:
+            - "**"
+          paths:
+            - "src/**"
+            - "lib/**"
+
+  - language: yaml
+    label: "Restrict to all branches (implicitly excludes tags)"
+    code: |
+      on:
+        push:
+          branches:
+            - "**"         # matches all branch pushes, ignores tag pushes
+          paths:
+            - "src/**"
+
+  - language: yaml
+    label: "Separate workflows for branch CI vs tag release"
+    code: |
+      # ci.yml — triggered by branch pushes with path filtering
+      on:
+        push:
+          branches:
+            - main
+            - "feature/**"
+          paths:
+            - "src/**"
+
+      ---
+      # release.yml — triggered by version tags
+      on:
+        push:
+          tags:
+            - "v*.*.*"
+
+prevention:
+  - "Never rely on `paths:` filters to suppress tag-push triggers — they are not evaluated for tags."
+  - "Always add an explicit `branches:` or `tags-ignore: [\"**\"]` when your workflow is path-filtered and meant only for code changes."
+  - "Keep branch-CI workflows and release/tag workflows in separate files to avoid trigger ambiguity."
+  - "Test your trigger logic with `act` locally — push a tag and verify the workflow does not fire unexpectedly."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/triggering-a-workflow#using-filters-to-target-specific-paths-for-pull-request-or-push-events"
+    label: "GitHub Docs: Using filters to target specific paths"
+  - url: "https://github.com/actions/runner/issues/3933"
+    label: "actions/runner#3933: Path filters not respected for tag pushes"
+  - url: "https://stackoverflow.com/questions/76037078/why-is-my-github-action-on-paths-also-triggered-when-pushing-a-new-tag"
+    label: "Stack Overflow: Why is paths: also triggered when pushing a new tag?"
+  - url: "https://stackoverflow.com/questions/70743715/how-do-i-configure-a-github-actions-workflow-so-it-does-not-run-on-a-tag-push"
+    label: "Stack Overflow: How to prevent workflow from running on tag push"

package/package.json

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