@htekdev/actions-debugger 1.0.105 → 1.0.107

package/errors/caching-artifacts/cache-save-restore-path-mismatch-silent-miss.yml

@@ -0,0 +1,93 @@
+id: caching-artifacts-062
+title: "actions/cache save and restore Separate Actions Silently Miss When Paths Differ"
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - cache
+  - cache-save
+  - cache-restore
+  - path-mismatch
+  - cache-miss
+  - silent
+patterns:
+  - regex: 'Cache not found for input keys'
+    flags: i
+error_messages:
+  - "Cache not found for input keys: my-cache-key"
+root_cause: |
+  When using actions/cache/save and actions/cache/restore as separate actions (split across
+  different jobs), the cache archive is indexed by BOTH the cache key AND the path provided
+  to the save action. The restore action must specify the EXACT same path as the save action
+  or no cache will be found, even when the key matches perfectly.
+
+  This is undocumented behaviour: the path is part of the cache version hash used to locate
+  the archive, not just the key. Using a relative vs absolute path, a trailing slash, or any
+  variation in path formatting between save and restore results in "Cache not found for input
+  keys" with no hint that path mismatch is the cause.
+
+  This differs from using the combined actions/cache action in a single job, where the path
+  is always consistent between save and restore. Reported in actions/cache#1444.
+fix: |
+  Ensure the path: value in actions/cache/restore exactly matches the path: value used in
+  actions/cache/save — including the same relative-vs-absolute format and no trailing slash
+  differences.
+
+  Best practice: extract the path into a shared env variable or workflow-level output, or
+  document the exact path string in both jobs.
+fix_code:
+  - language: yaml
+    label: "Wrong: different paths between save and restore jobs"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Create files
+              run: mkdir my-files && echo "data" > my-files/data.txt
+            - uses: actions/cache/save@v4
+              with:
+                path: my-files           # saved with relative path
+                key: my-cache-${{ github.run_id }}
+
+        deploy:
+          needs: build
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/cache/restore@v4
+              with:
+                path: ./my-files         # WRONG: './my-files' != 'my-files' -- cache not found
+                key: my-cache-${{ github.run_id }}
+  - language: yaml
+    label: "Correct: identical path strings in save and restore"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Create files
+              run: mkdir my-files && echo "data" > my-files/data.txt
+            - uses: actions/cache/save@v4
+              with:
+                path: my-files           # use identical path
+                key: my-cache-${{ github.run_id }}
+
+        deploy:
+          needs: build
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/cache/restore@v4
+              with:
+                path: my-files           # exact match — cache found
+                key: my-cache-${{ github.run_id }}
+prevention:
+  - "Copy the exact path: string from your save step into your restore step — do not retype it"
+  - "Avoid mixing relative (my-dir) and absolute (${{ github.workspace }}/my-dir) paths across jobs"
+  - "If in doubt, use the combined actions/cache@v4 action in a single job instead of split save/restore"
+  - "Print the cache key and path in both jobs to make debugging easier"
+docs:
+  - url: "https://github.com/actions/cache/issues/1444"
+    label: "actions/cache#1444 — Restore reports cache not found when path differs from save path"
+  - url: "https://github.com/actions/cache/tree/main/save"
+    label: "actions/cache/save — Split save/restore documentation"
+  - url: "https://github.com/actions/cache/tree/main/restore"
+    label: "actions/cache/restore — Split save/restore documentation"

package/errors/caching-artifacts/setup-java-gradle-windows-lock-files-device-busy.yml

@@ -0,0 +1,81 @@
+id: caching-artifacts-061
+title: "setup-java cache: 'gradle' Silently Corrupts Cache on Windows — Gradle Lock Files Device or Resource Busy"
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - setup-java
+  - gradle
+  - windows
+  - cache
+  - lock-files
+  - device-busy
+patterns:
+  - regex: '\.lock.*Read error.*Device or resource busy'
+    flags: i
+  - regex: 'fileContent\.lock.*Device or resource busy'
+    flags: i
+  - regex: '\.gradle/caches.*Read error.*byte 0'
+    flags: i
+error_messages:
+  - "/usr/bin/tar: C\\:/Users/runneradmin/.gradle/caches/8.7/fileContent/fileContent.lock: Read error at byte 0, while reading 38 bytes: Device or resource busy"
+  - "/usr/bin/tar: Exiting with failure status due to previous errors"
+  - "Warning: Failed to save: ... failed with exit code 2"
+root_cause: |
+  On Windows runners, actions/setup-java with cache: 'gradle' triggers a cache save in its
+  post-job step. At that point, the Gradle daemon process started during the build step may
+  still be running and holding open file locks on these cache directories:
+    - .gradle/caches/*/fileContent.lock
+    - .gradle/caches/*/fileHashes.lock
+    - .gradle/caches/*/generated-gradle-jars.lock
+    - .gradle/caches/*/javaCompile.lock
+    - .gradle/caches/journal-1/journal-1.lock
+    - .gradle/caches/modules-*/modules-*.lock
+
+  The GNU tar bundled with Git for Windows (used by the GitHub Actions runner) cannot read
+  Windows-locked files and exits with code 2. Despite this failure, setup-java logs
+  "Cache saved with the key: ..." because the cache service accepted a partial archive.
+
+  The silent failure: subsequent runs restore the partial cache, missing the locked files.
+  Gradle then redownloads dependencies on every run, and the cache save repeats the same
+  error. Cache size appears normal in the UI but the archive contents are incomplete.
+  Reported in actions/setup-java#633.
+fix: |
+  Stop the Gradle daemon explicitly before the post-job step fires. The setup-java
+  post-step runs after all workflow steps complete, so stopping the daemon in the last
+  step ensures no lock files are held when the post-step archives the cache:
+fix_code:
+  - language: yaml
+    label: "Fix: stop Gradle daemon before post-step cache save"
+    code: |
+      jobs:
+        build:
+          runs-on: windows-latest
+          steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-java@v4
+              with:
+                java-version: '21'
+                distribution: 'temurin'
+                cache: 'gradle'
+            - name: Build with Gradle
+              run: ./gradlew build
+            - name: Stop Gradle daemon before cache save
+              if: always()
+              run: ./gradlew --stop
+  - language: yaml
+    label: "Alternative: build with --no-daemon (no daemon started, no lock files)"
+    code: |
+      - name: Build with Gradle (no daemon)
+        run: ./gradlew build --no-daemon
+prevention:
+  - "Always add a './gradlew --stop' step (with if: always()) after your build step on Windows runners"
+  - "Use --no-daemon for Gradle builds in CI to avoid daemon lock file issues entirely"
+  - "Verify cache usefulness by checking whether Gradle redownloads dependencies on runs after cache save"
+  - "Consider using the official gradle/actions/setup-gradle action which handles daemon lifecycle better"
+docs:
+  - url: "https://github.com/actions/setup-java/issues/633"
+    label: "actions/setup-java#633 — Gradle caching post-task fails on Windows with 'device or resource busy'"
+  - url: "https://docs.gradle.org/current/userguide/gradle_daemon.html"
+    label: "Gradle Daemon documentation — stopping and disabling"
+  - url: "https://github.com/gradle/actions/blob/main/docs/setup-gradle.md"
+    label: "gradle/actions — recommended Gradle CI caching action"

package/errors/runner-environment/checkout-lfs-double-authorization-header-non-github-host.yml

@@ -0,0 +1,70 @@
+id: runner-environment-175
+title: "checkout@v4 LFS with Non-GitHub Host Sends Double Authorization Header -- 400 Bad Request"
+category: runner-environment
+severity: error
+tags:
+  - checkout
+  - lfs
+  - git-lfs
+  - non-github-host
+  - authorization-header
+  - submodule
+patterns:
+  - regex: 'Authorization.*Authorization'
+    flags: i
+  - regex: 'HTTP.*400.*lfs'
+    flags: i
+error_messages:
+  - "trace git-lfs: HTTP: 400"
+  - "batch request failed with status 400"
+root_cause: |
+  When actions/checkout is used with lfs: true and the repository contains submodules
+  pointing to a non-GitHub host (Gitea, Bitbucket, self-hosted GitLab, etc.), the checkout
+  action writes an HTTP Authorization header into .git/config via http.<url>.extraheader.
+  For GitHub.com remotes this works correctly. However, for submodule remotes on other hosts,
+  the git-lfs client then sends BOTH this injected header AND its own credential-helper-derived
+  Authorization header in the same LFS batch request.
+
+  Most non-GitHub servers reject duplicate Authorization headers with HTTP 400 Bad Request,
+  as the HTTP spec treats repeated Authorization headers as ambiguous. GitHub.com silently
+  deduplicates them, hiding the problem. Only non-GitHub hosts expose this bug.
+
+  Diagnosed by enabling GIT_CURL_VERBOSE: 1 and GIT_TRACE: 1 in the workflow environment,
+  which reveals two Authorization: Basic lines in the same LFS request headers.
+  Reported in actions/checkout#1830 (15 reactions).
+fix: |
+  Use SSH key authentication for the non-GitHub submodule remote — no HTTP Authorization
+  header is injected for SSH remotes, eliminating the conflict:
+fix_code:
+  - language: yaml
+    label: "Recommended: use ssh-key for non-GitHub submodule host"
+    code: |
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+          lfs: true
+          ssh-key: ${{ secrets.SUBMODULE_SSH_KEY }}
+  - language: yaml
+    label: "Alternative: disable lfs on checkout and pull LFS per-host manually"
+    code: |
+      steps:
+        - uses: actions/checkout@v4
+          with:
+            submodules: recursive
+            lfs: false   # prevents checkout from injecting LFS auth header
+        - name: Clear injected extraheader and pull LFS for non-GitHub host
+          env:
+            GIT_CURL_VERBOSE: "1"
+          run: |
+            cd path/to/non-github-submodule
+            git config --unset http.https://your-host.example.com/.extraheader || true
+            git lfs pull
+prevention:
+  - "Use SSH keys for non-GitHub submodule remotes to avoid HTTP credential injection conflicts"
+  - "Enable GIT_CURL_VERBOSE=1 to diagnose duplicate Authorization headers in LFS requests"
+  - "Test LFS workflows after upgrading checkout to a new major version"
+docs:
+  - url: "https://github.com/actions/checkout/issues/1830"
+    label: "actions/checkout#1830 -- LFS fails with double auth header on non-GitHub host"
+  - url: "https://github.com/actions/checkout#readme"
+    label: "actions/checkout -- lfs and submodules input documentation"

package/errors/runner-environment/hashfiles-fails-on-macos-fail-to-hash-files-under-directory.yml

@@ -0,0 +1,116 @@
+id: runner-environment-176
+title: "hashFiles() fails on macOS with 'Fail to hash files under directory'"
+category: runner-environment
+severity: error
+tags:
+  - hashfiles
+  - macos
+  - runner-images
+  - cache
+  - expression
+  - image-regression
+patterns:
+  - regex: 'hashFiles\(.+\) failed\. Fail to hash files under directory'
+    flags: 'i'
+  - regex: 'The template is not valid.*hashFiles.*Fail to hash files'
+    flags: 'is'
+error_messages:
+  - "Error: The template is not valid. /Users/runner/work/.../action.yml (Line: 48, Col: 12): hashFiles('**/go.sum') failed. Fail to hash files under directory '/Users/runner/work/...'"
+  - "hashFiles('**/package-lock.json') failed. Fail to hash files under directory '/Users/runner/work/...'"
+root_cause: |
+  Certain macOS runner image versions (including macos-15-arm64 image
+  20251119.0020 through approximately 20251122) introduced a regression
+  where the hashFiles() expression function fails to enumerate files
+  under the workspace directory on macOS. The same workflow succeeds on
+  Linux and Windows runners.
+
+  The failure manifests whenever hashFiles() is used in any expression
+  context — strategy.matrix, cache key, conditional — on the affected
+  macOS runner image versions. The underlying cause is a filesystem
+  enumeration permission or path-resolution change introduced by the
+  runner image update (see actions/runner-images #13341). The issue was
+  not present in the previous macOS image version and reappeared without
+  workflow changes.
+
+  Root cause in runner-images: the runner image update changed system
+  configuration in a way that prevented the runner process from
+  recursively listing files under the workspace directory on macOS. The
+  fix was a runner image rollback / patch released around December 12,
+  2025.
+
+  This failure is a runner-image regression, not a workflow bug. It can
+  recur if future macOS runner image updates introduce similar filesystem
+  configuration changes.
+fix: |
+  If you encounter this error on macOS:
+
+  1. Wait for GitHub to release a patched macOS runner image — runner
+     image regressions are typically resolved within days. Monitor
+     actions/runner-images for the fix.
+
+  2. Pin your workflow to a specific macOS runner image version that
+     predates the regression while waiting for the fix.
+
+  3. As a temporary workaround, replace hashFiles() with a manual
+     hash computation step using sha256sum or similar:
+
+       - name: Compute hash manually (macOS workaround)
+         id: hash
+         run: |
+           echo "hash=$(find . -name 'go.sum' -exec sha256sum {} \; | sha256sum | cut -d' ' -f1)" >> $GITHUB_OUTPUT
+       - uses: actions/cache@v4
+         with:
+           path: ~/go/pkg/mod
+           key: ${{ runner.os }}-go-${{ steps.hash.outputs.hash }}
+
+  4. After the runner image is updated to a fixed version, remove the
+     workaround and restore hashFiles().
+fix_code:
+  - language: yaml
+    label: "Manual hash workaround for macOS hashFiles() regression"
+    code: |
+      jobs:
+        build:
+          runs-on: macos-latest
+
+          steps:
+            - uses: actions/checkout@v4
+
+            # Workaround: compute cache key hash manually when hashFiles() fails on macOS
+            - name: Compute go.sum hash
+              id: hash
+              run: |
+                echo "hash=$(find . -name 'go.sum' | sort | xargs sha256sum | sha256sum | cut -d' ' -f1)" \
+                  >> "$GITHUB_OUTPUT"
+
+            - uses: actions/cache@v4
+              with:
+                path: ~/go/pkg/mod
+                key: ${{ runner.os }}-go-${{ steps.hash.outputs.hash }}
+
+            - run: go build ./...
+  - language: yaml
+    label: "Pin to a known-good macOS runner image while waiting for fix"
+    code: |
+      jobs:
+        build:
+          # Pin to a specific macOS runner image version that predates the regression.
+          # Check https://github.com/actions/runner-images/releases for available versions.
+          runs-on: macos-15-arm64
+          # Alternatively, use an older pinned version: macos-14 or macos-15-xlarge
+          # when the current macos-latest image has the regression.
+prevention:
+  - "Subscribe to actions/runner-images release notifications to detect image regressions early."
+  - "When hashFiles() fails only on macOS (Linux/Windows succeed), suspect a runner image regression
+     rather than a workflow bug — check the actions/runner-images issue tracker for reports."
+  - "If CI budget allows, run a short nightly workflow that tests hashFiles() on all target OS
+     combinations to detect image regressions before they block your main CI."
+  - "When pinning a runner image version as a workaround, add a TODO comment and a link to the
+     upstream issue so the pin is removed once the fix is released."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/evaluate-expressions-in-workflows-and-actions#hashfiles"
+    label: "GitHub Actions: hashFiles() expression function"
+  - url: "https://github.com/actions/runner/issues/4134"
+    label: "actions/runner #4134: hashFiles on macOS fails with 'Fail to hash files under directory' (14 reactions, closed Dec 2025)"
+  - url: "https://github.com/actions/runner-images/issues/13341"
+    label: "actions/runner-images #13341: macOS hashFiles regression report (Nov 2025)"

package/errors/silent-failures/reusable-workflow-input-default-bypassed-by-empty-string.yml

@@ -0,0 +1,144 @@
+id: silent-failures-094
+title: "Reusable workflow input default: value silently ignored when caller passes empty string"
+category: silent-failures
+severity: silent-failure
+tags:
+  - reusable-workflow
+  - workflow-call
+  - inputs
+  - default
+  - empty-string
+  - silent-failure
+patterns:
+  - regex: 'on:\s*\n\s*workflow_call:'
+    flags: 'im'
+  - regex: 'inputs\.\w+\.default:'
+    flags: 'i'
+  - regex: 'with:\s*\n(?:\s+\w+:\s*\$\{\{[^}]+\}\}\s*\n)+'
+    flags: 'im'
+error_messages:
+  - "Reusable workflow input default value not used when caller passes empty string"
+  - "Expected default message, got empty string"
+  - "inputs.message is empty even though default is set"
+root_cause: |
+  The default: field in on.workflow_call.inputs is only applied when the input is
+  completely absent (not provided by the caller at all). It is NOT applied when the
+  caller explicitly passes an empty string "".
+
+  A very common pattern is a caller workflow that passes a workflow_dispatch input
+  directly to a reusable workflow:
+
+    # caller.yml
+    on:
+      workflow_dispatch:
+        inputs:
+          message:
+            type: string
+            required: false       # defaults to "" when not provided
+
+    jobs:
+      call:
+        uses: ./.github/workflows/reusable.yml
+        with:
+          message: ${{ inputs.message }}   # passes "" when dispatch runs without input
+
+    # reusable.yml
+    on:
+      workflow_call:
+        inputs:
+          message:
+            type: string
+            default: 'default message'
+
+  When a developer triggers the caller workflow_dispatch without providing the
+  message input, inputs.message resolves to "" (the workflow_dispatch default for
+  unset string inputs). The caller then passes "" to the reusable workflow. The
+  reusable workflow receives "" as an explicitly-provided value, so its own
+  default: 'default message' is never used. The job runs with message = "".
+
+  This is by design: GitHub Actions treats "" as a valid non-absent value. The
+  default: key only activates for truly absent inputs (when with: does not include
+  the key at all). Since ${{ inputs.message }} always resolves to some string (even
+  "", it is always present in the with: block, so the called workflow's default
+  is always bypassed.
+fix: |
+  Move the default value handling to the calling workflow rather than the reusable
+  workflow, using a conditional expression to fall back to the default:
+
+    # caller.yml — handle empty-string fallback here
+    jobs:
+      call:
+        uses: ./.github/workflows/reusable.yml
+        with:
+          message: ${{ inputs.message != '' && inputs.message || 'default message' }}
+
+  Alternatively, handle the fallback inside the reusable workflow steps using an
+  env variable substitution:
+
+    # reusable.yml
+    jobs:
+      run:
+        runs-on: ubuntu-latest
+        env:
+          EFFECTIVE_MESSAGE: ${{ inputs.message != '' && inputs.message || 'default message' }}
+        steps:
+          - run: echo "Message is $EFFECTIVE_MESSAGE"
+
+  Do NOT rely on default: in on.workflow_call.inputs when the caller may pass ""
+  via ${{ inputs.x }} from a workflow_dispatch input.
+fix_code:
+  - language: yaml
+    label: "Apply the default in the caller with a conditional expression (recommended)"
+    code: |
+      # caller.yml
+      on:
+        workflow_dispatch:
+          inputs:
+            message:
+              type: string
+              required: false
+
+      jobs:
+        call:
+          uses: ./.github/workflows/reusable.yml
+          with:
+            # Use || to fall back to default when inputs.message is empty
+            message: ${{ inputs.message != '' && inputs.message || 'default message' }}
+  - language: yaml
+    label: "Apply the fallback inside the reusable workflow using env:"
+    code: |
+      # reusable.yml
+      on:
+        workflow_call:
+          inputs:
+            message:
+              type: string
+              required: false
+              # Note: default: here is bypassed when caller passes ""
+
+      jobs:
+        run:
+          runs-on: ubuntu-latest
+          env:
+            # Handle empty string at job level — inputs.message may be "" not null
+            EFFECTIVE_MESSAGE: ${{ inputs.message != '' && inputs.message || 'default message' }}
+          steps:
+            - name: Use effective message
+              run: echo "Message is $EFFECTIVE_MESSAGE"
+prevention:
+  - "Never place default values only in on.workflow_call.inputs.default when the caller
+     passes the input via ${{ inputs.x }} from a workflow_dispatch — the empty string
+     will always bypass the default."
+  - "Place fallback logic in the caller using '${{ inputs.x != '''''' && inputs.x || ''default'' }}'
+     to handle both absent and empty-string cases."
+  - "If you need the reusable workflow to have its own default, handle it via env: fallback
+     inside the job steps, not via on.workflow_call.inputs.default."
+  - "This behavior stems from GitHub Actions treating \"\" as an explicitly provided string
+     value rather than an absent/null input. Document this distinction for your team."
+docs:
+  - url: "https://docs.github.com/en/actions/sharing-automations/reusing-workflows#using-inputs-and-secrets-in-a-reusable-workflow"
+    label: "GitHub Actions: Using inputs and secrets in a reusable workflow"
+  - url: "https://github.com/actions/runner/issues/2907"
+    label: "actions/runner #2907: Reusable workflow input default not used when caller passes empty string (16 reactions)"
+  - url: "https://github.com/actions/runner/issues/924"
+    label: "actions/runner #924: Differentiate between input parameter empty or not present (76 reactions, still open)"

package/errors/triggers/pull-request-paths-filter-evaluates-entire-pr-diff-not-latest-commit.yml

@@ -0,0 +1,137 @@
+id: triggers-068
+title: "pull_request paths/paths-ignore filter evaluates entire PR diff, not latest commit"
+category: triggers
+severity: silent-failure
+tags:
+  - paths-filter
+  - paths-ignore
+  - pull_request
+  - three-dot-diff
+  - silent-trigger
+  - monorepo
+patterns:
+  - regex: 'paths-ignore:'
+    flags: 'i'
+  - regex: 'on:\s*\n\s*pull_request:'
+    flags: 'im'
+error_messages:
+  - "Workflow triggers on push to README.md even though README.md is listed in paths-ignore"
+  - "paths-ignore not respected after one commit touches files outside the ignore list"
+  - "Workflow keeps running for all subsequent commits in PR even though only ignored files changed"
+root_cause: |
+  GitHub's paths and paths-ignore filters for pull_request (and pull_request_target)
+  events use a three-dot diff — a comparison between the most recent version of the
+  topic branch HEAD and the commit where the topic branch last diverged from the base
+  branch (the merge base). This diff encompasses ALL files changed across the entire
+  PR, not just the files changed in the most recent commit/push.
+
+  The practical consequence is: once any commit in the PR has touched a file that is
+  NOT in paths-ignore, the three-dot diff permanently includes that file for the
+  lifetime of the PR. All subsequent pushes to the same PR will also trigger the
+  workflow, even if those pushes only modify files listed in paths-ignore.
+
+  Example: a PR starts by pushing a Go source file (triggers the workflow). The
+  developer then pushes a README.md-only commit. Despite README.md being in
+  paths-ignore, the entire PR diff still includes the earlier Go change, so the
+  workflow fires again.
+
+  This behavior is documented under "Git diff comparisons" in the GitHub Actions
+  workflow syntax reference but is widely misunderstood.
+
+  Contrast with push events: push filters only examine files changed in the
+  individual push commit(s), so paths-ignore works as most developers expect.
+fix: |
+  Option 1 — Use dorny/paths-filter to gate job execution at the step/job level
+  based on files changed only in the current push (most reliable workaround):
+
+    jobs:
+      guard:
+        runs-on: ubuntu-latest
+        outputs:
+          changed: ${{ steps.filter.outputs.src }}
+        steps:
+          - uses: actions/checkout@v4
+          - uses: dorny/paths-filter@v3
+            id: filter
+            with:
+              filters: |
+                src:
+                  - 'src/**'
+                  - '!README.md'
+
+      build:
+        needs: guard
+        if: needs.guard.outputs.changed == 'true'
+        runs-on: ubuntu-latest
+        steps:
+          - run: echo "only runs if src changed in latest push"
+
+  Option 2 — Accept that pull_request paths filtering is PR-wide and use it only
+  for coarse-grained "should this workflow category run at all" decisions, not for
+  per-commit granularity.
+
+  Option 3 — Remove paths/paths-ignore from the pull_request trigger entirely and
+  use conditional job-level steps with dorny/paths-filter instead.
+fix_code:
+  - language: yaml
+    label: "Use dorny/paths-filter for per-commit path gating (recommended)"
+    code: |
+      on:
+        pull_request:
+          branches: [main]
+          # No paths/paths-ignore here — filter is done per-commit in the job
+
+      jobs:
+        check-changes:
+          runs-on: ubuntu-latest
+          outputs:
+            src_changed: ${{ steps.filter.outputs.src }}
+          steps:
+            - uses: actions/checkout@v4
+            - uses: dorny/paths-filter@v3
+              id: filter
+              with:
+                filters: |
+                  src:
+                    - 'src/**'
+                    - '*.go'
+                    - '!**/*.md'
+
+        build:
+          needs: check-changes
+          if: needs.check-changes.outputs.src_changed == 'true'
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: make build
+  - language: yaml
+    label: "What NOT to do — paths-ignore on pull_request silently fails after first non-ignored commit"
+    code: |
+      # This looks correct but DOES NOT work as expected for pull_request events:
+      on:
+        pull_request:
+          paths-ignore:
+            - '**.md'      # <-- evaluated against entire PR diff, not latest push
+            - 'docs/**'
+
+      # After any commit in the PR touches a non-md file, ALL subsequent commits
+      # trigger this workflow, even if those commits only change .md files.
+prevention:
+  - "Do not rely on paths-ignore to prevent a workflow from running on documentation-only
+     follow-up commits in a PR — it only works until any non-ignored file is committed to
+     the PR branch."
+  - "Use dorny/paths-filter or similar per-commit path detection actions instead of workflow-level
+     paths-ignore for pull_request events when per-commit granularity is needed."
+  - "For monorepos, consider separate workflows per component triggered by dorny/paths-filter
+     outputs rather than native paths filters."
+  - "paths-ignore works reliably for push events (single commit diff) — the behavior difference
+     between push and pull_request is a common source of confusion."
+docs:
+  - url: "https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#git-diff-comparisons"
+    label: "GitHub Actions workflow syntax: Git diff comparisons"
+  - url: "https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#onpushpull_requestpull_request_targetpathspaths-ignore"
+    label: "GitHub Actions: paths and paths-ignore filter syntax"
+  - url: "https://github.com/actions/runner/issues/2324"
+    label: "actions/runner #2324: on.pull_request.paths-ignore are not respected correctly (64 reactions, still open)"
+  - url: "https://github.com/dorny/paths-filter"
+    label: "dorny/paths-filter — per-commit path change detection action"

package/package.json

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