@htekdev/actions-debugger 1.0.33 → 1.0.34

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/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/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/package.json

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