@htekdev/actions-debugger 1.0.11 → 1.0.13

package/errors/caching-artifacts/cache-path-exclusion-glob-silent-noop.yml

@@ -0,0 +1,83 @@
+id: caching-artifacts-014
+title: "actions/cache Exclusion Globs (! patterns) Silently Ignored"
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - cache
+  - glob
+  - exclusion
+  - negation
+  - silent-failure
+patterns:
+  - regex: "path:(?:[^#\\n]*\\n)+\\s*!\\S"
+    flags: "im"
+  - regex: "path:.*\\n.*!~/"
+    flags: "im"
+error_messages:
+  - "Cache saved with key"
+  - "Cache hit occurred on the primary key"
+root_cause: |
+  The `actions/cache` action uses `@actions/glob` with `implicitDescendants: false`
+  to resolve the `path:` input into a file list for `tar`. With this setting, each
+  pattern is matched only at the top level — subdirectory enumeration does not happen.
+  As a result, negation patterns like `!~/cache/temp` never find anything to exclude
+  because there are no implicitly enumerated descendants to match against.
+
+  The cache save and restore operations complete successfully with no error or warning.
+  The "excluded" directory is silently included in the archive, leading to:
+  - Larger caches than intended, consuming quota faster
+  - Sensitive or temporary files accidentally persisted across runs
+  - False-positive cache key hits (excluded dir content changes don't invalidate cache)
+
+  This is a long-standing known limitation of `actions/cache` that has been reported
+  since v1 and remains unfixed in v4.
+fix: |
+  `actions/cache` does not support exclusion globs. Restructure directories so the
+  content you want to cache lives in a dedicated subdirectory, and reference only that
+  path. If directory restructuring is not feasible, use a `run` step to create a
+  filtered `tar` archive before caching.
+fix_code:
+  - language: yaml
+    label: "BROKEN — exclusion pattern silently does nothing"
+    code: |
+      - uses: actions/cache@v4
+        with:
+          path: |
+            ~/cache
+            !~/cache/temp     # Silently ignored — temp/ is still cached
+          key: ${{ runner.os }}-cache-${{ hashFiles('**/package-lock.json') }}
+  - language: yaml
+    label: "CORRECT — restructure: cache only the subdirectory you need"
+    code: |
+      # Put persistent cache content in ~/cache/persistent/
+      # Put temp files in ~/cache/temp/  (not cached)
+      - uses: actions/cache@v4
+        with:
+          path: ~/cache/persistent   # Cache only the isolated subdirectory
+          key: ${{ runner.os }}-cache-${{ hashFiles('**/package-lock.json') }}
+  - language: yaml
+    label: "CORRECT — manual tar with --exclude for complex cases"
+    code: |
+      - name: Save cache with exclusion
+        run: |
+          tar --exclude='$HOME/cache/temp' \
+              --exclude='$HOME/cache/.git' \
+              -czf /tmp/my-cache.tar.gz \
+              ~/cache
+
+      - uses: actions/cache@v4
+        with:
+          path: /tmp/my-cache.tar.gz
+          key: ${{ runner.os }}-filtered-${{ hashFiles('**/package-lock.json') }}
+prevention:
+  - "Never rely on `!` negation patterns in `actions/cache` `path:` — they are silently ignored."
+  - "Audit cache paths to confirm no sensitive, secret, or large temporary files are included."
+  - "Isolate cacheable build artifacts into dedicated subdirectories at project setup time."
+  - "Set `enableCrossOsArchive: false` (default) and test on each OS independently."
+docs:
+  - url: "https://github.com/actions/toolkit/issues/713"
+    label: "actions/toolkit#713 — Cache: excluding files or folders with ! not working"
+  - url: "https://github.com/actions/cache/blob/main/tips-and-workarounds.md"
+    label: "actions/cache — Tips and workarounds"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows"
+    label: "Caching dependencies to speed up workflows"

package/errors/known-unsolved/composite-action-env-not-updated-on-reuse.yml

@@ -0,0 +1,114 @@
+id: known-unsolved-013
+title: "GITHUB_ENV Set in Composite Action Not Updated on Repeated Calls in Same Job"
+category: known-unsolved
+severity: silent-failure
+tags:
+  - composite-action
+  - GITHUB_ENV
+  - env-var
+  - repeated-calls
+  - known-limitation
+patterns:
+  - regex: "echo.*>>\\s*\\$GITHUB_ENV"
+    flags: "i"
+  - regex: "GITHUB_ENV.*composite"
+    flags: "i"
+error_messages:
+  - "environment variable not updated on second call"
+  - "variable retains value from first call"
+root_cause: |
+  When a composite action sets an environment variable by appending to $GITHUB_ENV,
+  that variable is propagated to the parent job context after the composite action
+  completes. On the first call this works correctly. However, if the same composite
+  action is called a second time in the same job, the GITHUB_ENV write succeeds
+  internally but the parent job environment variable retains the value from the
+  first call.
+
+  This is a known platform limitation: GITHUB_ENV writes from within composite
+  actions are processed at step-boundary transitions. On repeated calls to the
+  same composite action in the same job, the runner does not re-apply the env
+  file changes correctly for variables already set — the first written value
+  persists for the job duration.
+
+  The limitation affects parameterized composite actions used as reusable units
+  that produce environment state, especially when called in loops, matrices, or
+  sequential steps with different inputs.
+
+  GitHub has not fixed this behavior; the recommended migration path is to use
+  GITHUB_OUTPUT instead of GITHUB_ENV for composite action outputs.
+fix: |
+  Replace $GITHUB_ENV writes with $GITHUB_OUTPUT writes inside composite actions.
+  Step outputs are properly scoped per-invocation and do not have the repeated-call
+  limitation. Read the output in the calling workflow using steps.<id>.outputs.<name>.
+
+  If environment variables are strictly required at the job level, set them in the
+  calling workflow from the composite action outputs, not inside the composite action.
+fix_code:
+  - language: yaml
+    label: "BROKEN composite action — GITHUB_ENV silently not updated on 2nd call"
+    code: |
+      # my-action/action.yml
+      inputs:
+        label:
+          required: true
+      runs:
+        using: composite
+        steps:
+          - run: echo "MY_LABEL=${{ inputs.label }}" >> $GITHUB_ENV
+            shell: bash
+      # Calling workflow:
+      # steps:
+      #   - uses: ./my-action
+      #     with: { label: "first" }   # MY_LABEL = "first" ✓
+      #   - uses: ./my-action
+      #     with: { label: "second" }  # MY_LABEL still "first" — silent bug!
+  - language: yaml
+    label: "CORRECT composite action — use GITHUB_OUTPUT"
+    code: |
+      # my-action/action.yml
+      inputs:
+        label:
+          required: true
+      outputs:
+        label:
+          description: "The resolved label"
+          value: ${{ steps.set.outputs.label }}
+      runs:
+        using: composite
+        steps:
+          - id: set
+            run: echo "label=${{ inputs.label }}" >> $GITHUB_OUTPUT
+            shell: bash
+  - language: yaml
+    label: "CORRECT calling workflow — propagate to env if needed"
+    code: |
+      steps:
+        - id: first
+          uses: ./my-action
+          with:
+            label: build-${{ github.sha }}
+
+        - id: second
+          uses: ./my-action
+          with:
+            label: deploy-${{ github.sha }}
+
+        - name: Use outputs from both calls
+          env:
+            FIRST_LABEL: ${{ steps.first.outputs.label }}
+            SECOND_LABEL: ${{ steps.second.outputs.label }}
+          run: |
+            echo "First: $FIRST_LABEL"
+            echo "Second: $SECOND_LABEL"
+prevention:
+  - "Never use $GITHUB_ENV in composite actions that may be called more than once per job."
+  - "Migrate all composite action side effects from GITHUB_ENV to GITHUB_OUTPUT."
+  - "Test composite actions by calling them twice in the same job to catch this bug early."
+  - "Prefer outputs over env-var side effects for cleaner and predictable reuse semantics."
+docs:
+  - url: "https://docs.github.com/en/actions/sharing-automations/creating-actions/metadata-syntax-for-github-actions#outputs-for-composite-actions"
+    label: "Outputs for composite actions"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#setting-an-environment-variable"
+    label: "Workflow commands — setting an environment variable"
+  - url: "https://github.com/actions/runner/issues/789"
+    label: "actions/runner#789 — GITHUB_ENV does not update when running composite actions multiple times"

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/continue-on-error-failure-fn-bypassed.yml

@@ -0,0 +1,90 @@
+id: silent-failures-016
+title: "failure() Returns false After continue-on-error Step"
+category: silent-failures
+severity: silent-failure
+tags:
+  - continue-on-error
+  - failure
+  - status-functions
+  - error-handler
+  - silent-failure
+patterns:
+  - regex: "continue-on-error:\\s*true"
+    flags: "i"
+  - regex: "if:\\s*(\\$\\{\\{\\s*)?failure\\(\\)"
+    flags: "i"
+error_messages:
+  - "Skipping step: due to a failed condition"
+root_cause: |
+  When a step has `continue-on-error: true` and that step fails, GitHub Actions
+  records the step outcome as failure but immediately converts the job aggregate
+  status back to success before evaluating the next step. This means that
+  failure() in a subsequent step's if condition evaluates to false — the runner
+  sees the job as currently-successful, not currently-failed.
+
+  The continue-on-error flag was designed to allow a job to proceed past a failing
+  step, but the side effect is that it consumes the failure signal from all
+  status-check functions. Developers commonly write error-handler steps using
+  if: failure(), expecting them to trigger when the prior step fails, but this
+  pattern silently breaks when continue-on-error: true is present on that prior step.
+
+  The step individual outcome context (steps.<id>.outcome) is the only reliable
+  way to detect the specific step result after continue-on-error.
+fix: |
+  Replace if: failure() with if: steps.<step_id>.outcome == 'failure' when
+  writing error handlers for specific steps that use continue-on-error: true.
+  The steps.<id>.outcome context holds the actual step result regardless of
+  job-level status modifications.
+fix_code:
+  - language: yaml
+    label: "WRONG — failure() never triggers after continue-on-error"
+    code: |
+      steps:
+        - name: Risky operation
+          id: risky
+          continue-on-error: true
+          run: ./might-fail.sh
+
+        - name: Handle failure
+          if: failure()      # NEVER RUNS — job status was reset to success
+          run: ./notify-on-failure.sh
+  - language: yaml
+    label: "CORRECT — check specific step outcome"
+    code: |
+      steps:
+        - name: Risky operation
+          id: risky
+          continue-on-error: true
+          run: ./might-fail.sh
+
+        - name: Handle failure
+          if: steps.risky.outcome == 'failure'
+          run: ./notify-on-failure.sh
+
+        - name: Continue regardless
+          run: echo "Job continues either way"
+  - language: yaml
+    label: "CORRECT — combine with always() for comprehensive guards"
+    code: |
+      steps:
+        - name: Risky operation
+          id: risky
+          continue-on-error: true
+          run: ./might-fail.sh
+
+        - name: Handle step failure
+          if: always() && steps.risky.outcome == 'failure'
+          run: |
+            echo "::warning::Risky operation failed"
+            echo "## Failed" >> $GITHUB_STEP_SUMMARY
+prevention:
+  - "Never use if: failure() as handler for a step with continue-on-error: true — use steps.<id>.outcome."
+  - "Reserve failure() for handlers that should trigger on any upstream job failure."
+  - "Add step IDs to all continue-on-error steps so outcome checking is always possible."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-conditions-to-control-job-execution"
+    label: "Using conditions to control job execution"
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepscontinue-on-error"
+    label: "continue-on-error workflow syntax"
+  - url: "https://github.com/actions/toolkit/issues/1034"
+    label: "actions/toolkit#1034 — Wrong behaviour combining continue-on-error and failure()"

package/errors/silent-failures/if-mixed-expression-always-true.yml

@@ -0,0 +1,71 @@
+id: silent-failures-015
+title: "Mixing ${{ }} Interpolation Inside if: Condition Causes Step to Always Run"
+category: silent-failures
+severity: silent-failure
+tags:
+  - if-condition
+  - expression
+  - interpolation
+  - always-runs
+  - silent-failure
+patterns:
+  - regex: "if:.*==.*'[^']*\\$\\{\\{[^}]+\\}\\}[^']*'"
+    flags: "i"
+  - regex: "if:.*'[^']*\\$\\{\\{[^}]+\\}\\}[^']*'.*=="
+    flags: "i"
+error_messages:
+  - "step runs unexpectedly even when condition should be false"
+  - "if condition always evaluates true"
+root_cause: |
+  When the `if:` field contains BOTH bare comparison operators AND a `${{ }}`
+  interpolation fragment within a quoted string (e.g.,
+  `if: github.ref == 'refs/heads/${{ env.BRANCH }}'`), GitHub Actions wraps the
+  entire bare-string value in `${{ ... }}` for expression evaluation. This makes
+  the outer expression evaluate the literal string
+  `"github.ref == 'refs/heads/main'"` — a non-empty string — which is always truthy.
+
+  The runner does not parse the embedded `${{ }}` fragment as an inner expression;
+  it only processes the outer auto-wrap. The result is that the step runs on every
+  trigger regardless of the actual comparison result — a textbook silent failure
+  since the workflow file looks syntactically correct and no error is emitted.
+fix: |
+  Wrap the ENTIRE `if:` condition in `${{ }}` so the runner treats it as an
+  expression from the start. Use the `format()` function or direct context
+  comparisons instead of embedding `${{ }}` inside quoted strings.
+fix_code:
+  - language: yaml
+    label: "WRONG — mixed interpolation, step always runs"
+    code: |
+      env:
+        TARGET_BRANCH: main
+      steps:
+        - name: Deploy to production
+          # This ALWAYS runs — the string is truthy regardless of branch
+          if: github.ref == 'refs/heads/${{ env.TARGET_BRANCH }}'
+          run: ./deploy.sh
+  - language: yaml
+    label: "CORRECT — wrap entire condition in ${{ }}"
+    code: |
+      env:
+        TARGET_BRANCH: main
+      steps:
+        - name: Deploy to production
+          if: ${{ github.ref == format('refs/heads/{0}', env.TARGET_BRANCH) }}
+          run: ./deploy.sh
+  - language: yaml
+    label: "CORRECT — direct string literal comparison"
+    code: |
+      steps:
+        - name: Deploy to production
+          if: ${{ github.ref == 'refs/heads/main' }}
+          run: ./deploy.sh
+prevention:
+  - "Never embed `${{ }}` fragments inside quoted strings within `if:` — always wrap the entire condition."
+  - "Lint workflows with `actionlint` — it flags mixed expression/literal patterns in `if:` fields."
+  - "Prefer `format()` or direct context references over string interpolation in conditionals."
+  - "Test conditions on branches that should NOT match to verify they don't run."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/evaluate-expressions-in-workflows-and-actions"
+    label: "Evaluate expressions in workflows and actions"
+  - url: "https://github.com/actions/runner/issues/1173"
+    label: "actions/runner#1173 — If condition always evaluated as true when containing ${{ }} inside"

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/errors/yaml-syntax/needs-skipped-if-requires-always.yml

@@ -0,0 +1,100 @@
+id: yaml-syntax-018
+title: "Job if: Condition Skipped When Needed Job Is Skipped — Requires always() &&"
+category: yaml-syntax
+severity: error
+tags:
+  - needs
+  - skipped
+  - if-condition
+  - always
+  - job-level
+patterns:
+  - regex: "needs.*result.*skipped"
+    flags: "i"
+  - regex: "if:.*needs\\.[a-z_-]+\\.outputs"
+    flags: "i"
+error_messages:
+  - "Skipping job: due to job needs not meeting conditions"
+  - "Job was skipped"
+root_cause: |
+  When a job declares `needs: [job_a, job_b]` and any of those upstream jobs is in
+  a `skipped` state, GitHub Actions propagates the skip to the dependent job by
+  default — even when that job has its own `if:` condition that evaluates to `true`.
+
+  GitHub Actions imposes an implicit rule: all `needs` jobs must have
+  `result == 'success'` unless the dependent job's condition explicitly overrides
+  the check. A skipped upstream job does NOT satisfy the implicit success requirement.
+  The `if:` condition is NOT evaluated as a full override — it is only evaluated
+  AFTER the implicit needs-success check passes, so if that check fails the `if:`
+  is never reached.
+
+  The fix is `always() &&` at the start of the `if:` condition, which bypasses the
+  implicit needs-success requirement and forces the runner to evaluate the full condition.
+fix: |
+  Prepend `always() &&` to any job-level `if:` where an upstream `needs` job may be
+  legitimately skipped. Alternatively, explicitly allow skipped results:
+  `needs.job_name.result == 'success' || needs.job_name.result == 'skipped'`.
+fix_code:
+  - language: yaml
+    label: "WRONG — deploy skipped even though if evaluates true"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          outputs:
+            should_deploy: ${{ steps.check.outputs.deploy }}
+          steps:
+            - id: check
+              run: echo "deploy=true" >> $GITHUB_OUTPUT
+
+        integration-tests:
+          needs: build
+          if: ${{ needs.build.outputs.should_deploy == 'false' }}
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "optional integration tests"
+
+        deploy:
+          needs: [build, integration-tests]
+          # PROBLEM: integration-tests was skipped → deploy is also skipped
+          # even though the condition below is true
+          if: ${{ needs.build.outputs.should_deploy == 'true' }}
+          runs-on: ubuntu-latest
+          steps:
+            - run: ./deploy.sh
+  - language: yaml
+    label: "CORRECT — prepend always() to force evaluation"
+    code: |
+      jobs:
+        deploy:
+          needs: [build, integration-tests]
+          if: always() && needs.build.outputs.should_deploy == 'true'
+          runs-on: ubuntu-latest
+          steps:
+            - run: ./deploy.sh
+  - language: yaml
+    label: "CORRECT — explicit skipped result check"
+    code: |
+      jobs:
+        deploy:
+          needs: [build, integration-tests]
+          if: |
+            always() &&
+            needs.build.result == 'success' &&
+            (needs.integration-tests.result == 'success' ||
+             needs.integration-tests.result == 'skipped')
+          runs-on: ubuntu-latest
+          steps:
+            - run: ./deploy.sh
+prevention:
+  - "Add `always() &&` to any job `if:` condition where upstream `needs` jobs may be skipped."
+  - "Treat a skipped upstream need as equivalent to a failed need unless `always()` is used."
+  - "Map your workflow DAG — anywhere a branch is optionally skipped, downstream jobs need `always()`."
+  - "Use `actionlint` to surface potential needs/if interaction issues statically."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idif"
+    label: "jobs.<job_id>.if — Workflow syntax"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-conditions-to-control-job-execution#using-status-check-functions"
+    label: "Using status check functions (always, failure, success, cancelled)"
+  - url: "https://github.com/actions/runner/issues/491"
+    label: "actions/runner#491 — Job if condition not evaluated correctly if needs job is skipped"

package/package.json

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