@htekdev/actions-debugger 1.0.34 → 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/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/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/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.34",
+  "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",