@htekdev/actions-debugger 1.0.106 → 1.0.108

package/errors/caching-artifacts/cache-key-runner-os-insufficient-ubuntu-version-migration.yml

@@ -0,0 +1,90 @@
+id: caching-artifacts-063
+title: "runner.os insufficient in cache key after ubuntu-22.04 to ubuntu-24.04 migration — glibc-incompatible binaries silently restored"
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - cache-key
+  - runner.os
+  - ubuntu-24.04
+  - binary-compatibility
+  - glibc
+  - migration
+patterns:
+  - regex: 'symbol lookup error.*undefined symbol'
+    flags: 'i'
+  - regex: 'version.*GLIBC.*not found'
+    flags: 'i'
+  - regex: 'GLIBCXX.*not found'
+    flags: 'i'
+error_messages:
+  - "symbol lookup error: ./bin/app: undefined symbol: __libc_single_threaded"
+  - "version `GLIBC_2.38' not found (required by ./bin/app)"
+  - "GLIBCXX_3.4.32 not found in /usr/lib/x86_64-linux-gnu/libstdc++.so.6"
+root_cause: |
+  `runner.os` returns "Linux" for ALL Linux-based GitHub-hosted runners regardless of
+  Ubuntu distribution version: ubuntu-22.04 (glibc 2.35, GCC 11) and ubuntu-24.04
+  (glibc 2.39, GCC 13) both return "Linux".
+
+  When a workflow migrates from `runs-on: ubuntu-22.04` to `runs-on: ubuntu-latest`
+  (which became ubuntu-24.04 in March 2025), cache keys using only `${{ runner.os }}`
+  continue to match previously saved caches from ubuntu-22.04. Compiled native binaries
+  — Rust/Cargo target directories, CMake build outputs, Go CGO artifacts, Python
+  Cython-compiled extensions, pre-built Node.js native addons — are restored from
+  the ubuntu-22.04 cache onto an ubuntu-24.04 runner.
+
+  Because ubuntu-24.04 ships a newer glibc (2.39 vs 2.35) and updated libstdc++, binaries
+  compiled against the older ABI fail at runtime with dynamic linker errors:
+
+    symbol lookup error: ./bin/app: undefined symbol: __libc_single_threaded
+    version `GLIBC_2.38' not found (required by ./bin/app)
+
+  The cache restore step succeeds and shows a green checkmark. The failure surfaces only
+  when the restored binary is executed later in the pipeline, potentially hours into a
+  build. Because the compile step is skipped (cache hit), the error appears to come from
+  the execution step with no indication that a stale cross-version cache is the cause.
+fix: |
+  Add the runner image version to the cache key so that binary artifacts are not shared
+  across different Ubuntu distribution versions. GitHub-hosted runners expose the image
+  version as the `ImageVersion` environment variable (e.g. "20250312.1"). Alternatively,
+  hash `/etc/os-release` as a portable OS version fingerprint.
+fix_code:
+  - language: yaml
+    label: "Include ImageVersion in cache key to isolate per Ubuntu release"
+    code: |
+      - name: Cache Cargo build artifacts
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target/
+          # ImageVersion (e.g. "20250312.1") differs between ubuntu-22.04 and ubuntu-24.04
+          # Prevents restoring ubuntu-22.04 glibc-2.35 binaries on ubuntu-24.04 glibc-2.39
+          key: ${{ runner.os }}-${{ env.ImageVersion }}-cargo-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-${{ env.ImageVersion }}-cargo-
+  - language: yaml
+    label: "Alternative: hash /etc/os-release for portable OS version fingerprint"
+    code: |
+      - name: Cache compiled artifacts
+        uses: actions/cache@v4
+        with:
+          path: build/
+          key: >-
+            ${{ runner.os }}-
+            ${{ hashFiles('/etc/os-release') }}-
+            cmake-${{ hashFiles('CMakeLists.txt', '**/CMakeLists.txt') }}
+          restore-keys: |
+            ${{ runner.os }}-${{ hashFiles('/etc/os-release') }}-cmake-
+prevention:
+  - "After migrating `runs-on` from a specific ubuntu version to `ubuntu-latest`, bust existing caches by adding a new key prefix or bumping a cache version counter"
+  - "Include `${{ env.ImageVersion }}` in cache keys whenever the cached content contains compiled native binaries"
+  - "Use `runner.arch` for x64/ARM64 differences and `ImageVersion` for OS version differences together for complete binary cache isolation"
+  - "Prefer caching dependency manifests and source-level artifacts over compiled binaries when cross-version compatibility is uncertain"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows"
+    label: "GitHub Actions — caching dependencies"
+  - url: "https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2404-Readme.md"
+    label: "ubuntu-24.04 runner image specification (glibc and GCC versions)"
+  - url: "https://github.blog/changelog/2025-03-05-github-actions-ubuntu-latest-is-now-ubuntu-24-04/"
+    label: "GitHub Changelog — ubuntu-latest is now ubuntu-24.04 (March 2025)"

package/errors/permissions-auth/create-github-app-token-v2-default-single-repo-scope.yml

@@ -0,0 +1,70 @@
+id: permissions-auth-061
+title: "actions/create-github-app-token v2 — default token scope limited to current repository only"
+category: permissions-auth
+severity: error
+tags:
+  - github-app
+  - create-github-app-token
+  - multi-repo
+  - token-scope
+  - v2-migration
+patterns:
+  - regex: 'Resource not accessible by integration'
+    flags: 'i'
+  - regex: 'actions/create-github-app-token@v2'
+    flags: 'i'
+error_messages:
+  - "Resource not accessible by integration"
+  - "RequestError [HttpError]: Resource not accessible by integration"
+root_cause: |
+  actions/create-github-app-token underwent a breaking scope change in v2 (released 2024).
+
+  In v1: when no `repositories` input is specified, the generated token is scoped to ALL
+  repositories the GitHub App installation has access to.
+
+  In v2: when no `repositories` or `owner` input is specified, the token is scoped ONLY
+  to the current repository where the workflow is running. This matches the GitHub App
+  installation token API default behavior when requesting a per-repository token.
+
+  Workflows that used v1 and relied on the token to access other repositories (for
+  cross-repo clones, API calls, pushes, or artifact publishing) silently receive a
+  limited-scope token in v2. Operations on other repos return "Resource not accessible
+  by integration" or "HTTP 404 Not Found" with no clear indication that a v2 migration
+  caused the regression.
+fix: |
+  Explicitly declare the repositories the token should cover using the `repositories`
+  input (comma-separated repository names, without the org prefix). To grant access to
+  all repositories the app has access to within the same organization, use the `owner`
+  input instead.
+fix_code:
+  - language: yaml
+    label: "Explicit multi-repo token scope (v2)"
+    code: |
+      - name: Generate token
+        id: app-token
+        uses: actions/create-github-app-token@v2
+        with:
+          app-id: ${{ vars.APP_ID }}
+          private-key: ${{ secrets.PRIVATE_KEY }}
+          # List every repository the token needs access to
+          repositories: "repo-a,repo-b,infra-configs"
+  - language: yaml
+    label: "Org-wide token scope using owner input (v2)"
+    code: |
+      - name: Generate token
+        id: app-token
+        uses: actions/create-github-app-token@v2
+        with:
+          app-id: ${{ vars.APP_ID }}
+          private-key: ${{ secrets.PRIVATE_KEY }}
+          # Grants access to all repos the app has access to in the org
+          owner: ${{ github.repository_owner }}
+prevention:
+  - "When upgrading from v1 to v2, audit all usages for cross-repo operations and add an explicit `repositories:` or `owner:` input"
+  - "Pin to a major version tag and review the CHANGELOG before upgrading any action that generates authentication tokens"
+  - "Test cross-repo operations in a staging workflow immediately after a major version upgrade"
+docs:
+  - url: "https://github.com/actions/create-github-app-token/releases/tag/v2.0.0"
+    label: "actions/create-github-app-token v2.0.0 release notes (scope change)"
+  - url: "https://github.com/actions/create-github-app-token/blob/main/README.md#inputs"
+    label: "actions/create-github-app-token README — repositories and owner inputs"

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/github-event-head-commit-null-non-push-events.yml

@@ -0,0 +1,99 @@
+id: silent-failures-095
+title: "github.event.head_commit is null on non-push events — commit message checks silently return false"
+category: silent-failures
+severity: silent-failure
+tags:
+  - github-context
+  - head-commit
+  - workflow-dispatch
+  - event-context
+  - commit-message
+  - null-context
+patterns:
+  - regex: 'github\.event\.head_commit\.message'
+    flags: 'i'
+  - regex: 'github\.event\.head_commit\b'
+    flags: 'i'
+error_messages:
+  - "contains(github.event.head_commit.message, ...) returns false on workflow_dispatch"
+  - "github.event.head_commit is null"
+root_cause: |
+  The `github.event.head_commit` context object is only populated on `push` events.
+  On all other trigger types — `workflow_dispatch`, `pull_request`, `pull_request_target`,
+  `schedule`, `workflow_call`, `workflow_run`, `release`, and others — the property is
+  null, and all child fields evaluate to empty string `""` in expressions.
+
+  A very common workflow pattern is to gate deployment or release steps based on the
+  commit message:
+
+    if: contains(github.event.head_commit.message, '[deploy]')
+
+  When this condition is evaluated on a `workflow_dispatch` run, a scheduled run, or
+  any non-push trigger, `github.event.head_commit` is null and `contains()` receives
+  an empty string. The expression silently returns false and the step is skipped.
+
+  No error, no warning, and no indication in the workflow log that the condition was
+  never evaluated against real commit message data. Developers manually triggering the
+  workflow see their step silently skipped with no explanation.
+
+  This is particularly confusing because:
+  - The workflow completes successfully with a green checkmark
+  - The step appears in the log as skipped with no reason given
+  - Manual `workflow_dispatch` runs show no null-context warning
+fix: |
+  Guard the commit message check with an explicit event type condition, or provide a
+  workflow_dispatch input as an equivalent gate for manual runs.
+fix_code:
+  - language: yaml
+    label: "Guard commit message check to push events only"
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Deploy on tagged commit message
+              # Only evaluate head_commit.message on push events where it is defined
+              if: >-
+                github.event_name == 'push' &&
+                contains(github.event.head_commit.message, '[deploy]')
+              run: ./scripts/deploy.sh
+  - language: yaml
+    label: "Support push and manual dispatch with input fallback"
+    code: |
+      on:
+        push:
+          branches: [main]
+        workflow_dispatch:
+          inputs:
+            deploy:
+              description: 'Trigger deployment manually'
+              type: boolean
+              default: false
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Resolve deploy flag
+              id: flag
+              run: |
+                if [[ "${{ github.event_name }}" == "push" ]]; then
+                  MSG="${{ github.event.head_commit.message }}"
+                  echo "enabled=$([[ "$MSG" == *'[deploy]'* ]] && echo true || echo false)" >> $GITHUB_OUTPUT
+                else
+                  echo "enabled=${{ inputs.deploy }}" >> $GITHUB_OUTPUT
+                fi
+
+            - name: Deploy
+              if: steps.flag.outputs.enabled == 'true'
+              run: ./scripts/deploy.sh
+prevention:
+  - "Never use `github.event.head_commit.*` without first checking `github.event_name == 'push'`"
+  - "Use `workflow_dispatch` inputs with boolean type as the manual-trigger equivalent of commit-message gates"
+  - "Document which events activate each step — add inline comments explaining gating conditions"
+  - "Test multi-trigger workflows by manually running them and verifying steps behave as expected"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#push"
+    label: "GitHub Actions push event — head_commit availability"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/contexts#github-context"
+    label: "GitHub context reference — github.event object"

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/silent-failures/timeout-minutes-result-cancelled-not-failure.yml

@@ -0,0 +1,95 @@
+id: silent-failures-096
+title: "Job timeout-minutes sets result to 'cancelled' not 'failure' — if: failure() notification jobs silently skip timed-out jobs"
+category: silent-failures
+severity: silent-failure
+tags:
+  - timeout-minutes
+  - job-result
+  - if-failure
+  - notification
+  - cancelled
+  - cleanup-job
+patterns:
+  - regex: 'if:.*failure\(\)'
+    flags: 'i'
+  - regex: 'timeout-minutes:\s*\d+'
+    flags: 'i'
+error_messages:
+  - "This step was skipped because a previous step failed"
+  - "notification job skipped — upstream job timed out but result is 'cancelled' not 'failure'"
+root_cause: |
+  When a job exceeds its `timeout-minutes:` limit, GitHub Actions cancels the job and
+  sets its `result` to `"cancelled"` — NOT `"failure"`. This is a consistent but
+  widely misunderstood behavior.
+
+  A standard pattern is to add a notification or cleanup job that runs when builds fail:
+
+    notify:
+      needs: build
+      if: failure()
+      runs-on: ubuntu-latest
+
+  The `failure()` status check function returns true only when at least one upstream job
+  has result `"failure"`. It does NOT match `"cancelled"`. When `build` times out,
+  `needs.build.result` is `"cancelled"`, so `if: failure()` evaluates to false and
+  the notification job is silently skipped.
+
+  The four terminal job result values are: "success", "failure", "cancelled", "skipped".
+  The built-in functions map to:
+  - `failure()` → true when any upstream job result is "failure"
+  - `cancelled()` → true when any upstream job result is "cancelled"
+  - `success()` → true when all upstream jobs result in "success" (default)
+  - `always()` → always true regardless of upstream results
+
+  Developers are often surprised that a timed-out build does not trigger their alerting
+  job. The UI shows the timed-out job in orange ("Cancelled"), while the notification
+  job appears grey ("Skipped") — there is no direct indication that the skip is due to
+  the timeout rather than an unrelated condition.
+fix: |
+  Expand the notification job condition to explicitly cover both `failure` and `cancelled`
+  results, using `always()` to ensure the job runs regardless of upstream outcomes.
+fix_code:
+  - language: yaml
+    label: "Catch both failure and timeout (cancelled) in notification job"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          timeout-minutes: 30
+          steps:
+            - uses: actions/checkout@v4
+            - run: make build
+
+        notify:
+          needs: build
+          # Use always() so the job runs; then check for failure OR cancelled (timeout)
+          if: always() && (needs.build.result == 'failure' || needs.build.result == 'cancelled')
+          runs-on: ubuntu-latest
+          steps:
+            - name: Send alert
+              run: |
+                echo "Build result: ${{ needs.build.result }}"
+                # call your notification webhook here
+  - language: yaml
+    label: "Multi-job pipeline — catch any non-success terminal state"
+    code: |
+      jobs:
+        report:
+          needs: [build, test, deploy]
+          if: >-
+            always() &&
+            (contains(needs.*.result, 'failure') ||
+             contains(needs.*.result, 'cancelled'))
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Pipeline did not complete successfully"
+prevention:
+  - "Replace bare `if: failure()` with `if: always() && (needs.X.result == 'failure' || needs.X.result == 'cancelled')` whenever upstream jobs have `timeout-minutes:` set"
+  - "Treat `timeout-minutes` as a cancellation mechanism — timed-out jobs report `cancelled` not `failure`"
+  - "Test your notification path by temporarily reducing `timeout-minutes` to confirm the alerting logic fires on timeout"
+  - "Document in team runbooks that CI timeouts appear orange ('Cancelled') not red ('Failed') in the Actions UI"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/using-conditions-to-control-job-execution"
+    label: "GitHub Actions — status check functions (failure, cancelled, always)"
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idtimeout-minutes"
+    label: "GitHub Actions workflow syntax — timeout-minutes"

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.106",
+  "version": "1.0.108",
   "description": "65+ real GitHub Actions errors, queryable by agents. CLI + MCP server + Copilot skills + error database.",
   "type": "module",
   "main": "./dist/index.js",