@htekdev/actions-debugger 1.0.33 → 1.0.35

package/errors/caching-artifacts/cache-service-429-upload-ebadf-crash.yml

@@ -0,0 +1,108 @@
+id: 'caching-artifacts-030'
+title: "Cache Service 429 Rate Limit During Upload Causes EBADF File Stream Crash"
+category: caching-artifacts
+severity: error
+tags:
+  - cache
+  - rate-limit
+  - 429
+  - ebadf
+  - post-step
+  - upload
+  - toolkit
+patterns:
+  - regex: 'Cache service responded with 429'
+    flags: 'i'
+  - regex: 'Cache upload failed because file read failed with EBADF'
+    flags: 'i'
+  - regex: 'Failed to save:.*429'
+    flags: 'i'
+error_messages:
+  - "Warning: Failed to save: Cache service responded with 429 during upload chunk."
+  - "Error: Cache upload failed because file read failed with EBADF: bad file descriptor, read"
+root_cause: |
+  When the GitHub cache service rate-limits a cache upload request with HTTP 429
+  Too Many Requests, the actions/toolkit cache implementation does not cleanly
+  handle the rate-limit response. It emits a warning but continues attempting
+  to read from the underlying file stream. Because the HTTP upload connection was
+  already torn down after the 429, the file stream is left in a bad state. A
+  subsequent read on the orphaned stream raises EBADF (bad file descriptor), which
+  surfaces as a hard crash in the cleanup or post step of any action that uses
+  the toolkit cache library — including actions/setup-java, actions/setup-node,
+  actions/setup-python, and direct actions/cache usage.
+
+  The root cause is missing retry-with-backoff logic for 429 responses in the
+  toolkit's cache upload path. 429 responses include a Retry-After header that
+  the toolkit ignores entirely.
+
+  Most commonly triggered on large matrix builds (20+ concurrent jobs) where many
+  jobs save large caches simultaneously and collectively exhaust the cache service
+  rate limit. Individual jobs that hit the rate limit fail with the EBADF crash
+  rather than retrying or gracefully degrading.
+
+  Open since November 2023 (actions/toolkit#1589). Multiple large open-source
+  projects have reported it: apache/beam, techmatters/terraso-mobile-client,
+  synapsecns/sanguine, and others.
+fix: |
+  No upstream fix is available — this is an open bug in actions/toolkit since
+  November 2023. The rate-limit retry path is not implemented.
+
+  Workarounds:
+  1. Re-run the failed job from the GitHub Actions UI — on re-run, the cache
+     service rate limit has usually recovered and the upload succeeds.
+  2. Reduce concurrent cache saves: split large matrix builds into smaller
+     batches using strategy.max-parallel to stagger cache upload timing.
+  3. Pin to the latest patch version of actions/cache — GitHub occasionally
+     ships partial fixes. Keep the action version pinned to the latest release.
+  4. Use actions/cache/save with if: always() and accept that the step may
+     still warn on 429 — but it avoids the EBADF crash if the stream
+     handling is improved in a newer version.
+  5. Increase actions/cache version: v4+ has the most recent reliability fixes.
+fix_code:
+  - language: yaml
+    label: "Limit concurrent cache saves with max-parallel to avoid rate limiting"
+    code: |
+      jobs:
+        build:
+          strategy:
+            matrix:
+              os: [ubuntu-latest, macos-latest, windows-latest]
+              node: [18, 20, 22]
+            max-parallel: 4   # Stagger cache saves — avoid 20+ simultaneous uploads
+          runs-on: ${{ matrix.os }}
+          steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-node@v4
+              with:
+                node-version: ${{ matrix.node }}
+                cache: npm
+            - run: npm ci
+            - run: npm test
+  - language: yaml
+    label: "Accept cache-save failure gracefully with continue-on-error"
+    code: |
+      steps:
+        - uses: actions/cache/restore@v4
+          with:
+            path: ~/.m2/repository
+            key: ${{ runner.os }}-maven-${{ hashFiles('**/pom.xml') }}
+        - name: Build
+          run: mvn --batch-mode package
+        - name: Save cache (continue even if 429 occurs)
+          uses: actions/cache/save@v4
+          continue-on-error: true   # Prevents EBADF crash from failing the job
+          with:
+            path: ~/.m2/repository
+            key: ${{ runner.os }}-maven-${{ hashFiles('**/pom.xml') }}
+prevention:
+  - "Use strategy.max-parallel to limit concurrent matrix jobs and stagger cache upload timing."
+  - "Prefer actions/cache@v4 (latest) which includes the most recent reliability patches."
+  - "Add continue-on-error: true to explicit cache save steps to prevent EBADF from failing the workflow."
+  - "Monitor large matrix builds for recurring 429 errors — they indicate you need to reduce concurrency or shard differently."
+docs:
+  - url: "https://github.com/actions/toolkit/issues/1589"
+    label: "actions/toolkit#1589: Cache upload does not handle 429 error (open since Nov 2023, 6 reactions)"
+  - url: "https://github.com/actions/setup-java/issues/543"
+    label: "actions/setup-java#543: Transient 429 error fail upload cache cause workflow failure"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows"
+    label: "GitHub Docs: Caching dependencies to speed up workflows"

package/errors/known-unsolved/bulk-tag-push-over-three-silent-drop.yml

@@ -0,0 +1,115 @@
+id: 'known-unsolved-031'
+title: 'Pushing more than 3 tags simultaneously silently drops workflow runs for excess tags — GitHub platform limit'
+category: known-unsolved
+severity: silent-failure
+tags:
+  - push
+  - tags
+  - bulk-push
+  - webhook
+  - workflow-trigger
+  - limitation
+  - monorepo
+patterns:
+  - regex: 'push\s+--tags'
+    flags: 'i'
+  - regex: 'on:\s*\n\s*push:\s*\n\s*tags:'
+    flags: 'im'
+error_messages:
+  - 'No workflow runs created for some tags in bulk tag push'
+root_cause: |
+  GitHub's webhook delivery system has a documented hard limit: when more than 3 tags
+  are pushed simultaneously in a single push operation, push webhook events are only
+  created for the first 3 matching tags. Workflows for the remaining tags are silently
+  never triggered — no warning, no error, no failed run.
+
+  From the GitHub webhook events and payloads documentation:
+  "Events will not be created for tags when more than three tags are pushed at once."
+  (A similar limit of 5000 applies to branch pushes in a single operation, making the
+  3-tag threshold unexpectedly low by comparison.)
+
+  This is a platform-level constraint with no opt-out or configuration setting.
+
+  Common use cases affected:
+  - Monorepo release pipelines that tag multiple packages simultaneously
+    (e.g., package-a/v1.2.0, package-b/v1.0.0, package-c/v2.0.0, package-d/v0.5.0)
+  - Automated tooling that creates and pushes several version tags in one batch
+  - Release scripts using bulk push operations after creating several release tags
+  - Any CI pipeline where batch tagging is a normal part of the release flow
+
+  Source: actions/runner#3644 (7 reactions, Jan 2025, open), GitHub Docs push event.
+fix: |
+  No native fix — the 3-tag limit is a GitHub platform constraint. Workarounds:
+
+  Option 1: Push tags individually one at a time in a loop (slower but reliable).
+
+  Option 2: After a bulk tag operation, use the GitHub CLI to manually trigger
+  workflows for the tags that were silently skipped:
+    gh workflow run release.yml --ref tag-name
+
+  Option 3 (recommended for monorepos): Switch from push:tags triggered workflows to
+  repository_dispatch triggered release workflows. Use a coordination script that
+  pushes tags and then dispatches one workflow event per tag. This removes the
+  3-tag webhook constraint entirely.
+
+  Option 4: Use workflow_dispatch with a tag name input parameter and invoke it once
+  per tag from a release coordination script.
+fix_code:
+  - language: yaml
+    label: 'repository_dispatch-based release trigger bypassing the 3-tag limit'
+    code: |
+      # Release coordination script (run in CI or locally):
+      #
+      # For each tag you want to release, dispatch a repository_dispatch event:
+      #
+      #   for tag in package-a/v1.2.0 package-b/v1.0.0 package-c/v2.0.0; do
+      #     gh api repos/{owner}/{repo}/dispatches \
+      #       --field event_type=release \
+      #       --field "client_payload[tag]=$tag"
+      #   done
+
+      # Workflow triggered per tag via repository_dispatch:
+      on:
+        repository_dispatch:
+          types: [release]
+
+      jobs:
+        release:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                ref: ${{ github.event.client_payload.tag }}
+
+            - name: Build and publish
+              run: |
+                echo "Releasing ${{ github.event.client_payload.tag }}"
+                # add actual release steps here
+  - language: yaml
+    label: 'workflow_dispatch with tag input — invoke once per tag from release script'
+    code: |
+      on:
+        workflow_dispatch:
+          inputs:
+            tag:
+              description: 'Tag to release (e.g. package-a/v1.2.0)'
+              required: true
+              type: string
+
+      jobs:
+        release:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                ref: ${{ inputs.tag }}
+            - run: echo "Releasing ${{ inputs.tag }}"
+prevention:
+  - 'Never rely on bulk push operations to trigger per-tag workflows in monorepos — push tags individually or use repository_dispatch/workflow_dispatch patterns'
+  - 'Audit your release pipeline: if bulk tag operations are used and more than 3 tags are pushed at once, some workflow runs are silently missing'
+  - 'Add a post-release verification step that confirms a workflow run exists for each expected tag, alerting if any are missing'
+docs:
+  - url: 'https://docs.github.com/en/webhooks/webhook-events-and-payloads#push'
+    label: 'GitHub Docs: push webhook — 3-tag limit for simultaneous bulk tag pushes'
+  - url: 'https://github.com/actions/runner/issues/3644'
+    label: 'actions/runner#3644: Workflow fails to trigger on multiple tags push simultaneously (Jan 2025, open)'

package/errors/known-unsolved/merge-queue-ejected-pr-runs-not-auto-cancelled.yml

@@ -0,0 +1,144 @@
+id: 'known-unsolved-032'
+title: "Ejecting a PR from the Merge Queue Does Not Cancel Its Running Workflow Runs"
+category: known-unsolved
+severity: limitation
+tags:
+  - merge-queue
+  - merge_group
+  - cancellation
+  - orphaned-runs
+  - ci-minutes
+  - limitation
+  - waste
+patterns:
+  - regex: 'gh-readonly-queue/'
+    flags: 'i'
+  - regex: 'on:\s*\n\s*merge_group'
+    flags: 'im'
+error_messages:
+  - "Workflow run continues after PR is ejected from the merge queue"
+  - "No automatic cancellation for gh-readonly-queue/... runs on PR removal"
+root_cause: |
+  When GitHub's merge queue ejects a PR — due to a failing required check,
+  a merge conflict with another PR in the batch, or manual removal — GitHub
+  does NOT automatically cancel the workflow runs that were started for the
+  merge group batch that contained that PR.
+
+  Those runs continue to execute and consume CI minutes even though the
+  associated PR will never be merged via that queue entry. In active
+  repositories with large merge queues (especially monorepos or high-velocity
+  teams), a single failed check can cause a wave of orphaned runs as PRs are
+  rebatched and re-queued, multiplying wasted CI time.
+
+  Merge group workflow runs are triggered on ephemeral
+  `gh-readonly-queue/<base-branch>/pr-<number>-<sha>` refs. When the queue
+  ejects a PR, the ref is deleted but in-progress runs are not signalled.
+
+  GitHub has acknowledged this as working-as-designed behavior: workflow run
+  cancellation on merge queue ejection must be managed by the repository owner.
+
+  Source: dotCMS/core#34592 (GitHub merge queue orphaned workflow runs waste
+  CI resources, Feb 2026, open).
+fix: |
+  No built-in automatic cancellation mechanism exists. Available workarounds:
+
+  Option 1 — Scoped concurrency group per merge queue entry:
+  Set a concurrency group scoped to the workflow and the merge group ref. This
+  prevents a single PR from accumulating multiple parallel runs as it is
+  rebatched, but does NOT cancel runs when the PR is ejected.
+
+  Option 2 — Differentiated cancel-in-progress by event:
+  Use cancel-in-progress only for pull_request events (not merge_group events)
+  to avoid cancelling sibling PRs in the same batch while still cancelling
+  redundant PR-branch runs.
+
+  Option 3 — External cleanup script:
+  A separate monitoring workflow on schedule or repository_dispatch can call
+  the Actions API to cancel in-progress runs on refs that no longer exist.
+  This is operationally complex but achieves true cleanup.
+fix_code:
+  - language: yaml
+    label: "Differentiated concurrency — cancel PR runs but not merge queue runs"
+    code: |
+      on:
+        push:
+          branches: [main]
+        pull_request:
+        merge_group:
+
+      concurrency:
+        # Include workflow name to avoid cross-workflow cancellation
+        group: ${{ github.workflow }}-${{ github.ref }}
+        # Cancel duplicate PR branch runs, but do NOT cancel merge queue runs
+        # (cancelling merge_group runs ejects sibling PRs from the queue)
+        cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+      jobs:
+        ci:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm test
+  - language: yaml
+    label: "Monitoring workflow to cancel orphaned merge queue runs (advanced)"
+    code: |
+      # This workflow runs periodically and cancels in-progress runs
+      # on merge queue refs that no longer exist as active queue entries.
+      # Requires: contents: read, actions: write
+      on:
+        schedule:
+          - cron: '*/15 * * * *'   # Every 15 minutes
+        workflow_dispatch:
+
+      permissions:
+        actions: write
+        contents: read
+
+      jobs:
+        cleanup-orphaned-runs:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Cancel orphaned merge queue runs
+              uses: actions/github-script@v7
+              with:
+                script: |
+                  const runs = await github.rest.actions.listWorkflowRunsForRepo({
+                    owner: context.repo.owner,
+                    repo: context.repo.repo,
+                    status: 'in_progress',
+                    per_page: 100,
+                  });
+                  for (const run of runs.data.workflow_runs) {
+                    if (run.head_branch?.startsWith('gh-readonly-queue/')) {
+                      // Verify the queue ref still exists
+                      try {
+                        await github.rest.git.getRef({
+                          owner: context.repo.owner,
+                          repo: context.repo.repo,
+                          ref: `heads/${run.head_branch}`,
+                        });
+                      } catch (e) {
+                        if (e.status === 404) {
+                          // Ref gone — cancel the orphaned run
+                          await github.rest.actions.cancelWorkflowRun({
+                            owner: context.repo.owner,
+                            repo: context.repo.repo,
+                            run_id: run.id,
+                          });
+                          console.log(`Cancelled orphaned run ${run.id} for ${run.head_branch}`);
+                        }
+                      }
+                    }
+                  }
+prevention:
+  - "Accept that some CI minutes will be wasted on ejected PRs — this is a known platform constraint with no first-class solution."
+  - "Monitor total merge queue depth in high-velocity repos; if the queue frequently rebatches, orphaned runs accumulate quickly."
+  - "Use differentiated cancel-in-progress (disabled for merge_group events) to at least avoid accidentally ejecting sibling PRs while managing PR-branch redundancy."
+  - "Consider a periodic cleanup workflow using the Actions API to cancel in-progress runs on deleted merge queue refs."
+docs:
+  - url: "https://github.com/dotCMS/core/issues/34592"
+    label: "dotCMS/core#34592: Merge queue orphaned workflow runs waste CI resources (open, Feb 2026)"
+  - url: "https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-a-merge-queue"
+    label: "GitHub Docs: Managing a merge queue"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#merge_group"
+    label: "GitHub Docs: merge_group event"

package/errors/runner-environment/checkout-detached-head-git-push-fail.yml

@@ -0,0 +1,104 @@
+id: 'runner-environment-089'
+title: '`actions/checkout` leaves repository in detached HEAD state — subsequent `push` operations fail with "You are not currently on a branch"'
+category: runner-environment
+severity: error
+tags:
+  - checkout
+  - detached-head
+  - push
+  - pull-request
+  - branch
+  - git-operations
+patterns:
+  - regex: 'fatal: You are not currently on a branch\.'
+    flags: 'i'
+  - regex: 'To push the history leading to the current \(detached HEAD\)'
+    flags: 'i'
+  - regex: 'detached HEAD.*\d+\].*fatal'
+    flags: 'i'
+error_messages:
+  - 'fatal: You are not currently on a branch.'
+  - 'To push the history leading to the current (detached HEAD) state now, use'
+  - '    git push origin HEAD:<name-of-remote-branch>'
+  - 'Process completed with exit code 128.'
+root_cause: |
+  actions/checkout performs a detached HEAD checkout by default for pull_request events.
+  For pull_request triggers, GitHub provides a synthetic merge ref
+  (refs/pull/N/merge) rather than a real branch ref, so the action checks out
+  this merge commit without creating or tracking a local branch.
+
+  When subsequent workflow steps attempt to commit and push changes back to the
+  repository — for example, auto-formatting, documentation builds, coverage report
+  generation, or generated file updates — the operation fails because no remote
+  branch can be determined from a detached HEAD state.
+
+  This affects any workflow step that:
+  - Runs push operations after making commits in the workflow
+  - Uses tools that internally run push operations (e.g., auto-commit, changelog tools,
+    version bumpers)
+  - Expects to push back to the PR branch after making modifications
+
+  On push events, the checkout is also detached if ref: is not specified with the
+  branch name, because the default ref is github.sha (a commit SHA, not a branch name).
+
+  Tracked: actions/checkout#317 (44 reactions, ongoing since 2020, still receiving
+  comments in 2025).
+fix: |
+  Specify ref: in the checkout step to check out the branch name rather than a
+  commit SHA or merge ref. Once on a named branch, push-back operations work normally.
+
+  For pull_request events: use github.event.pull_request.head.ref
+  For push events: use github.ref_name (available since Runner 2.294.0)
+  For workflows triggered by multiple event types: branch the ref selection by
+  event name as shown in the third example below.
+fix_code:
+  - language: yaml
+    label: 'Fix for pull_request-triggered workflows that push back to the PR branch'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                # Check out the actual PR branch, not the detached merge ref
+                ref: ${{ github.event.pull_request.head.ref }}
+  - language: yaml
+    label: 'Fix for push-triggered workflows that commit and push back'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                # Checks out the branch name (e.g. main) instead of the commit SHA
+                ref: ${{ github.ref_name }}
+  - language: yaml
+    label: 'Universal fix for workflows triggered by multiple event types'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Checkout (pull_request)
+              if: github.event_name == 'pull_request'
+              uses: actions/checkout@v4
+              with:
+                ref: ${{ github.event.pull_request.head.ref }}
+
+            - name: Checkout (push or workflow_dispatch)
+              if: github.event_name != 'pull_request'
+              uses: actions/checkout@v4
+              with:
+                ref: ${{ github.ref_name }}
+prevention:
+  - 'Always specify ref: in checkout steps for workflows that push changes back to the repository'
+  - 'Use github.ref_name (not github.sha) for push-triggered workflows to get the branch name rather than a detached commit SHA'
+  - 'Test push-back workflows on both pull_request and push triggers to detect detached HEAD issues before they reach production'
+  - 'If using actions/checkout@v4, prefer explicit ref: values over relying on defaults when the workflow modifies and pushes files'
+docs:
+  - url: 'https://github.com/actions/checkout/issues/317'
+    label: 'actions/checkout#317: fatal: You are not currently on a branch (44 reactions, 2020–2025)'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#pull_request'
+    label: 'GitHub Docs: pull_request event — uses synthetic merge ref by default'

package/errors/silent-failures/cache-restore-fail-on-cache-miss-silent-bug.yml

@@ -0,0 +1,115 @@
+id: 'silent-failures-040'
+title: '`actions/cache/restore` `fail-on-cache-miss: true` silently does not halt the workflow in v3.3.2–v3.3.3 — subsequent steps execute despite cache miss'
+category: silent-failures
+severity: silent-failure
+tags:
+  - cache
+  - fail-on-cache-miss
+  - cache-restore
+  - silent-failure
+  - regression
+  - cache-v3
+  - cache-v4
+patterns:
+  - regex: 'Failed to restore cache entry\. Exiting as fail-on-cache-miss is set\.'
+    flags: 'i'
+  - regex: 'fail-on-cache-miss.*true'
+    flags: 'i'
+error_messages:
+  - 'Error: Failed to restore cache entry. Exiting as fail-on-cache-miss is set.'
+  - 'Warning: Cache not found for keys:'
+root_cause: |
+  actions/cache@v3.3.2 and v3.3.3 contain a bug in the actions/cache/restore sub-action
+  where fail-on-cache-miss: true does not actually halt the workflow when no cache entry
+  is found.
+
+  The bug has two components (tracked in PR#1327):
+
+  1. Logic error: restoreImpl.ts initializes earlyExit to undefined (falsy) regardless
+     of whether fail-on-cache-miss is set. The conditional `if (earlyExit)` check always
+     evaluates to false, so process.exit(1) is never called on a miss.
+
+  2. Exit code conflict: even when process.exit(1) is called, it overwrites the exit
+     code previously set by core.setFailed(), causing the runner to record the step
+     outcome as 'success' despite the logged error message.
+
+  Observable behavior in affected versions:
+  - The step log shows: "Error: Failed to restore cache entry. Exiting as
+    fail-on-cache-miss is set."
+  - The step is marked with a red X in the UI but step.outcome is 'success'
+  - All subsequent steps execute normally as if no error occurred
+  - Jobs that should have stopped at the cache guard proceed to completion
+
+  This silently undermines workflows that use fail-on-cache-miss to enforce a
+  warm-cache-required pattern (e.g., a build artifact must exist from a prior job).
+
+  Fixed in: actions/cache@v3.3.4 and actions/cache@v4.0.2+ via PR#1327 (merged March 2024).
+  Affected: actions/cache@v3.3.2, v3.3.3 and the corresponding actions/cache/restore versions.
+
+  Source: actions/cache#1265 (11 reactions), actions/cache PR#1327 (merged March 2024).
+fix: |
+  Option 1 (recommended): Update to actions/cache@v4 (v4.0.2+) or actions/cache@v3.3.4+
+  where the earlyExit logic and exit code handling are corrected.
+
+  Option 2: Roll back to actions/cache@v3.3.1 — the last version before the regression
+  was introduced.
+
+  Option 3 (belt-and-suspenders, any version): Add an explicit guard step after the
+  restore that checks the cache-hit output and exits manually. This works regardless
+  of the action version and is the most robust approach.
+fix_code:
+  - language: yaml
+    label: 'Upgrade to fixed actions/cache version (v3.3.4+ or v4.0.2+)'
+    code: |
+      jobs:
+        downstream:
+          needs: build
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            # v4.0.2+ correctly fails the step AND stops the job on cache miss
+            - name: Restore build artifacts
+              uses: actions/cache/restore@v4
+              with:
+                path: dist/
+                key: build-${{ github.sha }}
+                fail-on-cache-miss: true
+
+            - name: Run tests against build
+              run: make test-dist
+  - language: yaml
+    label: 'Belt-and-suspenders explicit guard (works on all cache versions)'
+    code: |
+      jobs:
+        downstream:
+          needs: build
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Restore build artifacts
+              id: cache-restore
+              uses: actions/cache/restore@v4
+              with:
+                path: dist/
+                key: build-${{ github.sha }}
+                fail-on-cache-miss: false   # Do not rely on this alone
+
+            - name: Abort if build cache missing
+              if: steps.cache-restore.outputs.cache-hit != 'true'
+              run: |
+                echo "::error::Build artifacts not found in cache — run the build job first."
+                exit 1
+
+            - name: Run tests against build
+              run: make test-dist
+prevention:
+  - 'Pin actions/cache and actions/cache/restore to v3.3.4+ or v4.0.2+ when using fail-on-cache-miss'
+  - 'Add an explicit guard step checking steps.ID.outputs.cache-hit alongside fail-on-cache-miss for critical cache gates'
+  - 'Verify that a failed cache restore truly stops downstream steps by running a workflow with a known cache miss before relying on fail-on-cache-miss in production'
+docs:
+  - url: 'https://github.com/actions/cache/issues/1265'
+    label: 'actions/cache#1265: fail-on-cache-miss not failing the workflow (11 reactions, Oct 2023)'
+  - url: 'https://github.com/actions/cache/pull/1327'
+    label: 'actions/cache PR#1327: Fix fail-on-cache-miss not working (merged March 2024)'

package/errors/triggers/issue-comment-default-branch-context-no-pr-checkout.yml

@@ -0,0 +1,132 @@
+id: 'triggers-029'
+title: "issue_comment Trigger Runs in Default Branch Context — PR Code Not Checked Out"
+category: triggers
+severity: silent-failure
+tags:
+  - issue_comment
+  - pull_request
+  - checkout
+  - default-branch
+  - context
+  - ref
+  - pr-comment
+patterns:
+  - regex: 'on:\s*\n\s*issue_comment'
+    flags: 'im'
+  - regex: 'github\.event\.issue\.pull_request'
+    flags: 'i'
+error_messages:
+  - "Warning: This commit is not necessarily the head of this branch."
+  - "issue_comment event fires in the default branch context, not the PR branch"
+root_cause: |
+  When a comment is posted on a pull request, GitHub fires the `issue_comment`
+  event in the **default branch context**, not in the PR branch context.
+  Specifically:
+  - github.ref = refs/heads/main (or the repo default branch)
+  - github.sha = the HEAD commit of the default branch
+  - github.event.pull_request is undefined (issue_comment doesn't include PR data)
+
+  A workflow triggered by `issue_comment` that runs `actions/checkout` without
+  an explicit `ref:` will silently check out the **default branch**, not the
+  PR's code. The workflow appears to succeed — but it ran against stale or
+  unrelated code, not the PR changes being discussed.
+
+  This is a well-known footgun documented in 67-reaction issues. Developers
+  commonly add /deploy, /test, or /approve slash command workflows on PR comments,
+  expecting the workflow to run against the PR's code.
+
+  A second consequence: `github.event.pull_request` is undefined in this context.
+  Workflows that assume `github.event.pull_request.head.sha` exists will error
+  with "Cannot read properties of undefined (reading 'head')".
+
+  Source: actions/checkout#331 (67 reactions, open since Aug 2020).
+fix: |
+  Explicitly retrieve the PR details from the GitHub API and check out the PR
+  head commit using the pull request number from the issue comment event payload.
+
+  The PR number is available at: github.event.issue.number
+  (issue_comment events on PRs use the issue number, which matches the PR number)
+
+  Two approaches:
+  1. Use actions/github-script to fetch the PR head SHA, then checkout with
+     that explicit ref.
+  2. Use pull_request_target instead of issue_comment for workflows that need
+     to run on PR code — but be aware of the security implications (pull_request_target
+     runs with write permissions in the base repo context, even for fork PRs).
+
+  Always gate on `github.event.issue.pull_request` in an if: condition to
+  distinguish PR comments from plain issue comments.
+fix_code:
+  - language: yaml
+    label: "Checkout PR head commit from issue_comment event"
+    code: |
+      on:
+        issue_comment:
+          types: [created]
+
+      jobs:
+        run-on-pr-comment:
+          runs-on: ubuntu-latest
+          # Only run on PR comments, not plain issue comments
+          if: github.event.issue.pull_request != null
+          steps:
+            - name: Get PR head SHA
+              id: pr
+              uses: actions/github-script@v7
+              with:
+                script: |
+                  const pr = await github.rest.pulls.get({
+                    owner: context.repo.owner,
+                    repo: context.repo.repo,
+                    pull_number: context.issue.number,
+                  });
+                  core.setOutput('head_sha', pr.data.head.sha);
+                  core.setOutput('head_ref', pr.data.head.ref);
+
+            - uses: actions/checkout@v4
+              with:
+                ref: ${{ steps.pr.outputs.head_sha }}
+
+            - name: Run tests on PR code
+              run: npm test
+  - language: yaml
+    label: "Slash command pattern — only act on specific PR comment text"
+    code: |
+      on:
+        issue_comment:
+          types: [created]
+
+      jobs:
+        slash-command:
+          runs-on: ubuntu-latest
+          if: |
+            github.event.issue.pull_request != null &&
+            contains(github.event.comment.body, '/deploy')
+          steps:
+            - name: Get PR head SHA
+              id: pr
+              uses: actions/github-script@v7
+              with:
+                script: |
+                  const pr = await github.rest.pulls.get({
+                    owner: context.repo.owner,
+                    repo: context.repo.repo,
+                    pull_number: context.issue.number,
+                  });
+                  core.setOutput('head_sha', pr.data.head.sha);
+            - uses: actions/checkout@v4
+              with:
+                ref: ${{ steps.pr.outputs.head_sha }}
+            - run: ./scripts/deploy.sh
+prevention:
+  - "Always add `if: github.event.issue.pull_request != null` to distinguish PR comments from issue comments."
+  - "Never rely on github.ref or github.sha in issue_comment workflows — they point to the default branch, not the PR."
+  - "Use actions/github-script to fetch the PR head SHA via the pulls.get API, then pass it to actions/checkout as ref."
+  - "Consider pull_request_target for PR-triggered workflows, but audit for untrusted code execution risk first."
+docs:
+  - url: "https://github.com/actions/checkout/issues/331"
+    label: "actions/checkout#331: Any way to checkout PR from issue_comment event? (67 reactions)"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#issue_comment"
+    label: "GitHub Docs: issue_comment event trigger"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#pull_request_target"
+    label: "GitHub Docs: pull_request_target event — alternative with write access"

package/errors/triggers/pull-request-ready-for-review-type-not-listed.yml

@@ -0,0 +1,101 @@
+id: 'triggers-028'
+title: 'Converting a draft PR to ready-for-review does not trigger `pull_request` workflow unless `ready_for_review` is explicitly listed in `types:`'
+category: triggers
+severity: silent-failure
+tags:
+  - pull-request
+  - draft
+  - ready-for-review
+  - types
+  - trigger
+  - silent-failure
+patterns:
+  - regex: 'ready_for_review'
+    flags: 'i'
+  - regex: 'pull_request\.draft\s*==\s*false'
+    flags: 'i'
+error_messages:
+  - 'Workflow not triggered when draft PR converted to ready for review'
+  - 'No workflow runs appeared after marking PR as ready for review'
+root_cause: |
+  GitHub fires a distinct pull_request event type — ready_for_review — when a draft PR
+  is converted to ready. This event type is NOT included in the default types list
+  of [opened, synchronize, reopened].
+
+  Two common misconfigured patterns that silently fail:
+
+  Pattern 1 — draft filter with default types:
+    A workflow uses `if: github.event.pull_request.draft == false` with default types.
+    The if: condition filters jobs correctly on synchronize/opened events, but the
+    ready_for_review conversion event is never fired because ready_for_review is not
+    in the types list. Result: a PR opened as draft, then converted to ready, will
+    never have had CI run against its commits.
+
+  Pattern 2 — only ready_for_review type:
+    A workflow lists only `types: [ready_for_review]`. This fires once when the draft
+    is converted, but never on subsequent commits to the PR (synchronize is not listed).
+
+  The correct pattern combines all four types AND adds the draft check condition so
+  that draft-state pushes are skipped while draft-to-ready conversion and subsequent
+  synchronize events all trigger the workflow.
+
+  Source: Stack Overflow #73948443 (score 8, 4,466 views), GitHub Docs pull_request
+  event types documentation.
+fix: |
+  Combine all required event types including ready_for_review in the types: list, and
+  add a job-level if: condition to skip workflow runs while the PR is still in draft.
+
+  This ensures:
+  - Draft PRs do not run CI (filtered by the if: condition)
+  - Converting a draft to ready fires the workflow against the current HEAD commit
+  - Subsequent commits to a ready PR trigger the workflow via synchronize events
+fix_code:
+  - language: yaml
+    label: 'Correct configuration: all four types plus draft guard condition'
+    code: |
+      on:
+        pull_request:
+          types:
+            - opened
+            - synchronize
+            - reopened
+            - ready_for_review   # Must be explicit — not included in default types
+
+      jobs:
+        ci:
+          # Skip while PR is in draft state — fires for all non-draft PR events above
+          if: '! github.event.pull_request.draft'
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: echo "CI running on non-draft PR"
+  - language: yaml
+    label: 'Alternative: run on all PR events, annotate draft runs as informational'
+    code: |
+      on:
+        pull_request:
+          types:
+            - opened
+            - synchronize
+            - reopened
+            - ready_for_review
+
+      jobs:
+        ci:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Annotate draft status
+              if: github.event.pull_request.draft == true
+              run: echo "::notice::Running on draft PR — results are informational"
+
+            - uses: actions/checkout@v4
+            - run: make test
+prevention:
+  - 'Always explicitly list all four pull_request types when your workflow must run on draft-to-ready conversions'
+  - 'Validate your trigger configuration by: opening a draft PR, pushing a commit to it, then converting to ready — all three events should behave as expected'
+  - 'Use github.event.pull_request.draft in job-level if: conditions rather than filtering by type alone, so the same workflow handles draft and non-draft PRs correctly'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#pull_request'
+    label: 'GitHub Docs: pull_request event types including ready_for_review'
+  - url: 'https://stackoverflow.com/questions/73948443/github-actions-running-a-workflow-on-non-draft-prs'
+    label: 'Stack Overflow #73948443: Running a workflow on non-draft PRs (score 8, 4,466 views)'

package/errors/yaml-syntax/workflow-call-outputs-jobs-result-empty.yml

@@ -0,0 +1,125 @@
+id: 'yaml-syntax-032'
+title: "jobs.<id>.result Always Returns Empty String in on.workflow_call.outputs..value"
+category: yaml-syntax
+severity: silent-failure
+tags:
+  - reusable-workflow
+  - workflow_call
+  - outputs
+  - jobs-context
+  - result
+  - expression
+  - empty-string
+patterns:
+  - regex: 'jobs\.\w+\.result'
+    flags: 'i'
+  - regex: 'on:\s*\n\s*workflow_call:\s*\n[\s\S]*?outputs:'
+    flags: 'im'
+error_messages:
+  - "jobs.<job_id>.result evaluates to empty string in on.workflow_call.outputs value"
+  - "needs.<reusable_workflow>.outputs.<output> is empty string instead of success/failure/skipped"
+root_cause: |
+  In a reusable workflow, the expression `${{ jobs.<id>.result }}` silently
+  evaluates to an empty string when referenced inside an
+  `on.workflow_call.outputs.<output_name>.value` expression.
+
+  Despite the GitHub documentation stating that the `jobs` context is available
+  in that expression scope, direct property access to the `.result` field of a
+  job object returns empty string rather than the expected outcome value
+  (`success`, `failure`, `cancelled`, or `skipped`).
+
+  This causes downstream caller workflows that test the reusable workflow's
+  output (e.g., `needs.reusable.outputs.my-result == 'skipped'`) to silently
+  receive an empty string. Conditions that gate follow-up jobs on the result
+  of the reusable workflow never evaluate to true.
+
+  Open since January 2024 (actions/runner#3087, 11 reactions). The issue
+  affects all GitHub-hosted runners. A workaround exists using
+  `fromJSON(toJSON(jobs.<id>)).result` which forces the expression through JSON
+  serialization and correctly surfaces the result value.
+
+  Note: This is distinct from the more common mistake of referencing outputs
+  without declaring them in the job's outputs: block. The bug occurs even when
+  the job produces no step outputs and you simply want to surface whether the
+  job ran, was skipped, or failed.
+fix: |
+  Two approaches:
+
+  Option 1 — fromJSON/toJSON workaround (quickest):
+  Replace `${{ jobs.build.result }}` with
+  `${{ fromJSON(toJSON(jobs.build)).result }}`. The JSON round-trip forces
+  full evaluation of the jobs context object and correctly returns the result
+  string.
+
+  Option 2 — Surface result via step output (most reliable):
+  Add an explicit step with `if: always()` that writes `job.status` to
+  GITHUB_OUTPUT. Reference the step output in the job's outputs block and
+  in the top-level workflow_call outputs. This avoids the expression evaluation
+  quirk entirely.
+fix_code:
+  - language: yaml
+    label: "Broken pattern vs fromJSON/toJSON workaround"
+    code: |
+      # BROKEN: jobs.build.result returns empty string
+      on:
+        workflow_call:
+          outputs:
+            job-result:
+              value: ${{ jobs.build.result }}   # Always empty string
+
+      # FIXED: fromJSON/toJSON forces expression evaluation
+      on:
+        workflow_call:
+          outputs:
+            job-result:
+              value: ${{ fromJSON(toJSON(jobs.build)).result }}   # Returns success/failure/skipped
+  - language: yaml
+    label: "Preferred fix — surface result via explicit step output"
+    code: |
+      on:
+        workflow_call:
+          outputs:
+            job-result:
+              description: "The build job outcome"
+              value: ${{ jobs.build.outputs.result }}
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          outputs:
+            result: ${{ steps.capture-result.outputs.result }}
+          steps:
+            - uses: actions/checkout@v4
+            - name: Build
+              run: npm run build
+
+            - name: Capture job result
+              id: capture-result
+              if: always()
+              run: echo "result=${{ job.status }}" >> $GITHUB_OUTPUT
+  - language: yaml
+    label: "Caller workflow checking reusable output"
+    code: |
+      jobs:
+        reusable:
+          uses: ./.github/workflows/build.yml
+          secrets: inherit
+
+        deploy:
+          needs: reusable
+          runs-on: ubuntu-latest
+          # This condition now works correctly with either fix above
+          if: needs.reusable.outputs.job-result == 'success'
+          steps:
+            - run: echo "Deploying after successful build"
+prevention:
+  - "Never rely on direct `jobs.<id>.result` access in workflow_call top-level outputs — use the fromJSON(toJSON()) workaround or explicit step outputs."
+  - "Add integration tests for reusable workflows that verify output values are non-empty strings."
+  - "Use job.status (available inside step runs) rather than jobs.<id>.result (the problematic context) when capturing job outcome."
+docs:
+  - url: "https://github.com/actions/runner/issues/3087"
+    label: "actions/runner#3087: Cannot access jobs.<id>.result from on.workflow_call.outputs (open since Jan 2024, 11 reactions)"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/passing-information-between-jobs"
+    label: "GitHub Docs: Passing information between jobs"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/contexts#jobs-context"
+    label: "GitHub Docs: jobs context (documents result property)"

package/package.json

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