@htekdev/actions-debugger 1.0.72 → 1.0.74

package/errors/caching-artifacts/cache-post-step-skipped-on-job-failure.yml

@@ -0,0 +1,127 @@
+id: caching-artifacts-044
+title: 'actions/cache post step skipped when job fails — cache not saved on failure (post-if: success() default)'
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - actions-cache
+  - cache-save
+  - job-failure
+  - post-if
+  - save-always
+  - silent-skip
+patterns:
+  - regex: 'Post\s+Run\s+actions/cache'
+    flags: 'i'
+  - regex: 'save-always'
+    flags: 'i'
+  - regex: 'Cache\s+not\s+found'
+    flags: 'i'
+error_messages:
+  - "Cache was not saved. Exiting with failure."
+  - "Post Run actions/cache@v4 skipped"
+  - "Cache miss on subsequent run after failed job"
+  - "cache-hit: false even though previous run had cache action"
+root_cause: |
+  actions/cache (v3 and v4) uses a `post-if: success()` condition on the cache save post step
+  by default. This means the cache save step only runs when ALL preceding steps in the job
+  succeeded. When any step fails:
+  - The job transitions to "failure" state
+  - The cache post step is SKIPPED silently — no warning, annotation, or error is logged
+  - The next run gets a cache miss and must re-download/rebuild from scratch
+
+  This is commonly discovered when:
+  - A test suite installs dependencies (cached) then runs tests (which fail)
+  - The cache works on the first run but never again after a flaky failure
+  - A build step fails, wasting all compilation work that could have been cached
+  - CI is slow because each failed run discards the cache and rebuilds from zero
+
+  Note: This is DIFFERENT from caching-artifacts-036 which covers the case where the job
+  is CANCELLED (via concurrency cancel-in-progress). Cancellation also skips the post step,
+  but for a different reason — cancellation interrupts all runners immediately.
+
+  The failure case is separate: the job runs to completion (with a failure), the post step
+  lifecycle still runs, but the post-if condition evaluates to false and skips it silently.
+fix: |
+  Option 1 (recommended): Set `save-always: true` on the restore step (actions/cache v3.3.3+ and v4+):
+    - uses: actions/cache@v4
+      with:
+        path: ~/.npm
+        key: ${{ runner.os }}-node-${{ hashFiles('package-lock.json') }}
+        save-always: true   # Save cache even if job fails
+
+  Option 2: Use the standalone cache/save action in an explicit cleanup step:
+    - uses: actions/cache/restore@v4
+      id: cache-restore
+      with:
+        path: ~/.npm
+        key: ${{ runner.os }}-node-${{ hashFiles('package-lock.json') }}
+    - run: npm ci
+    - uses: actions/cache/save@v4
+      if: always()   # Explicit save even on failure
+      with:
+        path: ~/.npm
+        key: ${{ runner.os }}-node-${{ hashFiles('package-lock.json') }}
+
+  Option 3 (v3 only): Use `cache-v3-save-always-unexpected-input` — note that `save-always`
+  was not available before v3.3.3. On older versions, use the split restore/save approach.
+fix_code:
+  - language: yaml
+    label: 'Save cache on job failure using save-always: true (v4)'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - uses: actions/cache@v4
+              with:
+                path: ~/.npm
+                key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
+                restore-keys: |
+                  ${{ runner.os }}-npm-
+                save-always: true   # Cache saves even if subsequent steps fail
+
+            - run: npm ci
+            - run: npm test         # If this fails, cache is still saved
+  - language: yaml
+    label: 'Explicit restore then save with if: always() (works on all versions)'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Restore cache
+              id: npm-cache
+              uses: actions/cache/restore@v4
+              with:
+                path: ~/.npm
+                key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
+                restore-keys: |
+                  ${{ runner.os }}-npm-
+
+            - run: npm ci
+            - run: npm test
+
+            - name: Save cache (always, even on failure)
+              uses: actions/cache/save@v4
+              if: always()
+              with:
+                path: ~/.npm
+                key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
+prevention:
+  - 'Add save-always: true to actions/cache when partial installs (e.g., npm ci with an error) are still worth caching'
+  - 'Consider whether caching a partial/failed state is desirable — for compiled artifacts, only cache on success'
+  - 'Use the split restore/save action pattern for fine-grained control over when the cache is saved'
+  - 'Monitor cache hit rates in the Actions UI — consistently low rates after failures indicate post-if skips'
+docs:
+  - url: 'https://github.com/actions/cache#save-cache-even-if-the-build-fails'
+    label: 'actions/cache — save-always: true option'
+  - url: 'https://github.com/actions/cache/blob/main/save/README.md'
+    label: 'actions/cache/save — standalone save action'
+  - 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'
+  - url: 'https://github.com/actions/cache/issues/92'
+    label: 'actions/cache#92 — Feature request: save cache on failure (highly voted)'

package/errors/concurrency-timing/push-pr-ref-format-different-concurrency-no-sharing.yml

@@ -0,0 +1,113 @@
+id: concurrency-timing-038
+title: 'push and pull_request events use different github.ref formats — concurrency slots never shared between event types'
+category: concurrency-timing
+severity: silent-failure
+tags:
+  - concurrency
+  - github-ref
+  - pull-request
+  - push
+  - cancel-in-progress
+  - slot-sharing
+patterns:
+  - regex: 'group:\s+\$\{\{\s*github\.workflow\s*\}\}-\$\{\{\s*github\.ref\s*\}\}'
+    flags: 'i'
+  - regex: 'refs/pull/\d+/merge'
+    flags: ''
+error_messages:
+  - "Push deploy and PR deploy run in parallel despite same concurrency group"
+  - "concurrency group does not prevent push and pull_request from running simultaneously"
+  - "Both workflows triggered at the same time even with concurrency group set"
+root_cause: |
+  When concurrency group uses `${{ github.ref }}`, the ref value differs by event type:
+  - `on: push` to main → github.ref = 'refs/heads/main'
+  - `on: pull_request` targeting main → github.ref = 'refs/pull/123/merge' (synthetic merge ref)
+
+  These produce different concurrency group keys, so push and pull_request runs NEVER share
+  a concurrency slot. Developers who want "one deploy at a time" across push and PR events
+  are surprised when both run in parallel.
+
+  Common scenario:
+  - Deploy workflow triggers on both push (to main) and pull_request (for preview)
+  - A push to main is deploying
+  - A new PR triggers a deploy
+  - Both run simultaneously because their github.ref values are different strings
+  - Race condition or resource contention on the deployment target
+
+  This is distinct from the `github.head_ref` empty-on-push issue (which over-cancels).
+  Here, using `github.ref` under-cancels by never sharing slots between event types.
+fix: |
+  To serialize push and pull_request deploys into one slot, use a ref-agnostic key
+  or normalize the ref to a shared value.
+
+  Option 1: Use a static concurrency key scoped to just the workflow name (one slot total):
+    group: ${{ github.workflow }}
+    cancel-in-progress: true
+
+  Option 2: Normalize to the target/base branch using head_ref for PRs and ref_name for push:
+    group: ${{ github.workflow }}-${{ github.head_ref || github.ref_name }}
+    cancel-in-progress: true
+
+  For github.head_ref || github.ref_name:
+  - pull_request: github.head_ref = 'feature/my-branch' (PR source branch)
+  - push:        github.ref_name = 'main' (pushed branch name)
+  - Both give meaningful branch names, but they still differ — PRs use source branch, push uses target
+  - For "one deploy to main at a time" across both events, use github.base_ref || github.ref_name
+
+  Option 3: Use the target/base branch for both:
+    group: ${{ github.workflow }}-${{ github.base_ref || github.ref_name }}
+    cancel-in-progress: true
+  - pull_request: github.base_ref = 'main' (target branch)
+  - push:        github.ref_name = 'main' (pushed branch)
+  - Both produce the same key for operations targeting main — serializes push and PR deploys
+fix_code:
+  - language: yaml
+    label: 'Serialize push and pull_request deploys to the same target branch'
+    code: |
+      on:
+        push:
+          branches: [main]
+        pull_request:
+          branches: [main]
+
+      concurrency:
+        # Use base_ref (PR target) or ref_name (push branch) — both equal 'main'
+        # when targeting main, so push and PR deploys share one slot
+        group: ${{ github.workflow }}-${{ github.base_ref || github.ref_name }}
+        cancel-in-progress: true
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Deploy
+              run: echo "Deploying to ${{ github.base_ref || github.ref_name }}"
+  - language: yaml
+    label: 'One global slot for the entire workflow (simplest serialization)'
+    code: |
+      on:
+        push:
+          branches: [main]
+        pull_request:
+
+      concurrency:
+        group: ${{ github.workflow }}
+        cancel-in-progress: true
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Only one run at a time, any trigger"
+prevention:
+  - 'Understand that github.ref differs between push (refs/heads/BRANCH) and pull_request (refs/pull/N/merge) events'
+  - 'Use github.base_ref || github.ref_name to get the target/base branch name for both event types'
+  - 'Test concurrency behavior with simultaneous push and PR triggers before relying on it for deploy serialization'
+  - 'Use github.head_ref for the PR source branch or github.ref_name for push branch — never github.ref directly in concurrency keys unless same-event-type serialization is the goal'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/controlling-concurrency'
+    label: 'GitHub Actions — Controlling concurrency'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#github-context'
+    label: 'GitHub context — github.ref, github.head_ref, github.base_ref, github.ref_name'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#pull_request'
+    label: 'pull_request event — github.ref is refs/pull/N/merge'

package/errors/known-unsolved/github-step-summary-not-accessible-cross-job.yml

@@ -0,0 +1,132 @@
+id: known-unsolved-046
+title: 'GITHUB_STEP_SUMMARY content is not accessible by downstream jobs or reusable workflows'
+category: known-unsolved
+severity: limitation
+tags:
+  - github-step-summary
+  - step-summary
+  - cross-job
+  - job-outputs
+  - reusable-workflow
+  - limitation
+patterns:
+  - regex: 'GITHUB_STEP_SUMMARY'
+    flags: 'i'
+  - regex: 'step.summary'
+    flags: 'i'
+error_messages:
+  - "Cannot read GITHUB_STEP_SUMMARY from another job"
+  - "Step summary not available as job output"
+  - "How to share step summary content between jobs"
+root_cause: |
+  `GITHUB_STEP_SUMMARY` is a write-only file path for adding Markdown content to the job
+  summary page in the GitHub Actions UI. The content written to it is visible in the UI
+  but is NOT accessible programmatically from:
+  - Other jobs in the same workflow (even with `needs:` dependency)
+  - Downstream caller workflows that invoke this as a reusable workflow
+  - Workflow run APIs — the summary content cannot be retrieved via the REST API
+
+  The summary file exists only on the runner's local filesystem during execution and is
+  uploaded to GitHub as display-only content. There is no `steps.<id>.summary` output
+  or `needs.<job>.summary` context available.
+
+  Common failure patterns:
+  - Build job writes a changelog summary; deploy job tries to use it in a notification
+  - Reusable workflow summarizes test results; caller tries to aggregate summaries
+  - Reporting job expects to read markdown generated by upstream jobs
+
+  GitHub has no native mechanism to read back summary content once written.
+  This is a long-standing requested feature with no announced roadmap.
+fix: |
+  Use job outputs or artifacts to share data that needs to be readable by downstream jobs.
+  GITHUB_STEP_SUMMARY is display-only — treat it as a write-once UI annotation.
+
+  Workaround 1 — Dual-write (write to both summary AND output/artifact):
+    Write the same content to GITHUB_STEP_SUMMARY for display AND to $GITHUB_OUTPUT or
+    an artifact for programmatic consumption by downstream jobs.
+
+  Workaround 2 — Generate in a script and capture output:
+    Run the data-generation logic in a script, capture to a variable, write to both
+    $GITHUB_STEP_SUMMARY and $GITHUB_OUTPUT in the same step.
+
+  There is no workaround that reads GITHUB_STEP_SUMMARY after it has been written.
+  Data sharing between jobs MUST use job outputs or artifacts.
+fix_code:
+  - language: yaml
+    label: 'Dual-write: populate GITHUB_STEP_SUMMARY for UI AND job output for downstream use'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          outputs:
+            changelog: ${{ steps.gen.outputs.changelog }}
+          steps:
+            - name: Generate changelog
+              id: gen
+              run: |
+                CHANGES=$(git log --oneline HEAD~5..HEAD)
+
+                # Write to step summary for UI display
+                echo "## Changes" >> $GITHUB_STEP_SUMMARY
+                echo "$CHANGES" >> $GITHUB_STEP_SUMMARY
+
+                # Also write to output for downstream job consumption
+                # Use heredoc for multiline output
+                {
+                  echo "changelog<<EOF"
+                  echo "$CHANGES"
+                  echo "EOF"
+                } >> $GITHUB_OUTPUT
+
+        notify:
+          needs: build
+          runs-on: ubuntu-latest
+          steps:
+            - name: Use changelog from build job
+              run: |
+                echo "Changes to notify: ${{ needs.build.outputs.changelog }}"
+  - language: yaml
+    label: 'Upload summary content as artifact for reusable workflow callers'
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Run tests and generate report
+              run: |
+                # Write display summary
+                echo "## Test Results" >> $GITHUB_STEP_SUMMARY
+                echo "All tests passed" >> $GITHUB_STEP_SUMMARY
+
+                # Write machine-readable copy to a file (upload as artifact)
+                echo "All tests passed" > test-summary.md
+
+            - name: Upload summary as artifact
+              uses: actions/upload-artifact@v4
+              with:
+                name: test-summary
+                path: test-summary.md
+
+        deploy:
+          needs: test
+          runs-on: ubuntu-latest
+          steps:
+            - name: Download test summary
+              uses: actions/download-artifact@v4
+              with:
+                name: test-summary
+
+            - name: Use test summary
+              run: cat test-summary.md
+prevention:
+  - 'Never assume GITHUB_STEP_SUMMARY content can be read back — it is write-only display output'
+  - 'Design workflows to use job outputs ($GITHUB_OUTPUT) or artifacts for any data that must flow between jobs'
+  - 'Write data to both GITHUB_STEP_SUMMARY (for UI) and $GITHUB_OUTPUT (for downstream) in the same step when both are needed'
+  - 'Document this limitation for team members who discover it while trying to aggregate summaries across jobs'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#adding-a-job-summary'
+    label: 'GitHub Docs — Adding a job summary (GITHUB_STEP_SUMMARY)'
+  - 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 (outputs and artifacts)'
+  - url: 'https://github.com/orgs/community/discussions/12836'
+    label: 'GitHub Community — Read GITHUB_STEP_SUMMARY from downstream jobs (no native support)'

package/errors/silent-failures/github-ref-name-pr-merge-ref-not-branch.yml

@@ -0,0 +1,102 @@
+id: silent-failures-070
+title: 'github.ref_name returns N/merge on pull_request events, not the head branch name'
+category: silent-failures
+severity: silent-failure
+tags:
+  - github-ref-name
+  - github-head-ref
+  - pull-request
+  - merge-ref
+  - branch-name
+  - context
+patterns:
+  - regex: 'github\.ref_name'
+    flags: 'i'
+  - regex: '\d+/merge'
+    flags: ''
+error_messages:
+  - "branch name is '15/merge' instead of 'feature/my-branch'"
+  - "invalid branch: 45/merge"
+  - "ref_name evaluates to 23/merge on pull_request trigger"
+root_cause: |
+  On pull_request events, GitHub creates a synthetic merge commit ref at refs/pull/N/merge
+  representing the result of merging the head branch into the base branch. This is the ref
+  that the runner checks out by default.
+
+  github.ref resolves to 'refs/pull/N/merge' and github.ref_name resolves to 'N/merge'
+  (e.g., '15/merge') — not the human-readable head branch name.
+
+  Developers who use github.ref_name expecting the PR head branch name receive the synthetic
+  merge ref slug instead, which breaks:
+  - Branch-based deployment logic
+  - Conditional workflow steps that check the branch name
+  - Tag/release workflows incorrectly applied to PR builds
+  - Docker image tags derived from the branch name
+
+  To get the actual PR head branch name on pull_request events, use github.head_ref.
+  To get the base branch name, use github.base_ref.
+
+  Note: On push events, github.ref_name correctly returns the branch name (e.g., 'main').
+  The discrepancy only affects pull_request (and pull_request_target) events.
+fix: |
+  Use github.head_ref instead of github.ref_name when you need the PR head branch name.
+
+  For robust multi-event workflows, use a conditional expression:
+  - On pull_request: github.head_ref contains the branch name
+  - On push: github.ref_name contains the branch name
+
+  Or use a ternary-style expression to normalize:
+  ${{ github.event_name == 'pull_request' && github.head_ref || github.ref_name }}
+fix_code:
+  - language: yaml
+    label: 'Use github.head_ref for PR branch name, github.ref_name for push'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Get branch name
+              run: |
+                if [ "${{ github.event_name }}" = "pull_request" ]; then
+                  BRANCH="${{ github.head_ref }}"
+                else
+                  BRANCH="${{ github.ref_name }}"
+                fi
+                echo "Branch: $BRANCH"
+                echo "BRANCH=$BRANCH" >> $GITHUB_ENV
+
+  - language: yaml
+    label: 'Normalize branch name in Docker image tag (works for push and PR)'
+    code: |
+      on:
+        push:
+          branches: [main, develop]
+        pull_request:
+
+      jobs:
+        docker:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Set branch slug
+              id: branch
+              run: |
+                # Use head_ref for PRs, ref_name for push events
+                BRANCH="${{ github.event_name == 'pull_request' && github.head_ref || github.ref_name }}"
+                # Slugify: replace / with - for Docker tag compatibility
+                SLUG=$(echo "$BRANCH" | tr '/' '-' | tr '[:upper:]' '[:lower:]')
+                echo "slug=$SLUG" >> $GITHUB_OUTPUT
+
+            - name: Build Docker image
+              run: docker build -t myapp:${{ steps.branch.outputs.slug }} .
+prevention:
+  - 'On pull_request events, always use github.head_ref for the PR head branch and github.base_ref for the target base branch'
+  - 'github.ref_name is only reliable as a branch name on push events — never use it unconditionally'
+  - 'When writing multi-event workflows (push + pull_request), add an event-conditional expression to normalize the branch name'
+  - 'Test workflows triggered by both push and pull_request events to catch context differences early'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#github-context'
+    label: 'GitHub context — github.ref_name, github.head_ref, github.base_ref'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#pull_request'
+    label: 'pull_request event context and merge ref behavior'
+  - url: 'https://github.com/orgs/community/discussions/25722'
+    label: 'GitHub Community: github.ref_name returns N/merge on pull_request'

package/errors/silent-failures/reusable-workflow-caller-env-not-forwarded.yml

@@ -0,0 +1,93 @@
+id: silent-failures-069
+title: 'workflow_call: caller env vars not forwarded to reusable workflow — silently unavailable'
+category: silent-failures
+severity: silent-failure
+tags:
+  - reusable-workflow
+  - workflow_call
+  - env-context
+  - caller-env
+  - inputs
+  - environment-variables
+patterns:
+  - regex: 'env\.\w+ is not defined'
+    flags: 'i'
+  - regex: '\$\{\{\s*env\.\w+\s*\}\}\s*$'
+    flags: 'im'
+error_messages:
+  - "env.API_URL is not defined"
+  - "The template is not valid. .github/workflows/deploy.yml: env.BASE_URL is not defined"
+root_cause: |
+  GitHub Actions reusable workflows (on.workflow_call) run in a completely isolated environment.
+  The caller workflow's env: context — whether defined at the top-level workflow scope or at the
+  calling job scope — is NOT automatically forwarded to the called reusable workflow.
+
+  Only two mechanisms exist for passing data into a reusable workflow:
+  - inputs: (on.workflow_call.inputs) for plain values
+  - secrets: (on.workflow_call.secrets) for sensitive values
+
+  A common mistake is defining env: vars at the caller workflow level and assuming they will be
+  visible inside the reusable workflow. They are not. The called workflow has its own empty env:
+  context (unless vars.* or env: is set within the reusable workflow itself).
+
+  Example that breaks silently:
+  - Caller sets: env: { API_URL: 'https://api.example.com' }
+  - Caller calls: uses: ./.github/workflows/deploy.yml
+  - Inside deploy.yml: run: curl ${{ env.API_URL }}  # evaluates to empty string, no error
+fix: |
+  Pass values explicitly via the inputs: mechanism on the reusable workflow call.
+  Define the input on on.workflow_call.inputs and reference it as inputs.<name> inside the
+  called workflow.
+
+  If many env vars need forwarding, consider using a JSON-encoded input and fromJSON() inside
+  the called workflow, or use repository variables (vars.*) which are available in all workflows.
+fix_code:
+  - language: yaml
+    label: 'Pass caller env var as explicit input to reusable workflow'
+    code: |
+      # Caller workflow
+      jobs:
+        deploy:
+          uses: ./.github/workflows/deploy.yml
+          with:
+            api_url: ${{ vars.API_URL }}   # or hardcoded value
+          secrets: inherit
+
+      # Reusable workflow: .github/workflows/deploy.yml
+      on:
+        workflow_call:
+          inputs:
+            api_url:
+              required: true
+              type: string
+
+      jobs:
+        run:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Deploy
+              run: curl ${{ inputs.api_url }}
+
+  - language: yaml
+    label: 'Use repository variables (vars.*) accessible in all workflows'
+    code: |
+      # Set API_URL as a repository variable in Settings → Secrets and variables → Actions → Variables
+      # Then reference it in the reusable workflow directly:
+      jobs:
+        run:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Deploy
+              run: curl ${{ vars.API_URL }}
+prevention:
+  - 'Never rely on env: vars defined in a caller workflow being available inside a reusable workflow — they are not forwarded'
+  - 'Declare all cross-workflow values as on.workflow_call.inputs or on.workflow_call.secrets'
+  - 'Use repository/org-level variables (vars.*) for configuration that many workflows need without explicit passing'
+  - 'Run actionlint on caller and callee separately — it will flag undefined env references in reusable workflows'
+docs:
+  - url: 'https://docs.github.com/en/actions/sharing-automations/reusing-workflows#passing-inputs-and-secrets-to-a-reusable-workflow'
+    label: 'Passing inputs and secrets to a reusable workflow'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables#using-the-vars-context-to-access-configuration-variable-values'
+    label: 'Using repository variables with the vars context'
+  - url: 'https://github.com/orgs/community/discussions/26671'
+    label: 'GitHub Community: env vars not accessible in reusable workflows'

package/errors/triggers/issue-comment-pr-review-thread-not-triggered.yml

@@ -0,0 +1,105 @@
+id: triggers-050
+title: 'on.issue_comment does not fire for PR review thread comments — requires pull_request_review_comment'
+category: triggers
+severity: silent-failure
+tags:
+  - issue_comment
+  - pull_request_review_comment
+  - pr-review
+  - comment-event
+  - trigger
+  - chatops
+patterns:
+  - regex: 'on:\s*\n\s+issue_comment'
+    flags: 'im'
+  - regex: 'github\.event_name\s*==\s*[''"]issue_comment[''"]'
+    flags: 'i'
+error_messages:
+  - "workflow never triggered when commenting on a PR review thread"
+  - "issue_comment workflow fires on issue comments but not PR inline review comments"
+root_cause: |
+  GitHub Actions has two distinct comment event types that developers frequently confuse:
+
+  1. issue_comment — fires when a comment is posted on:
+     - The main conversation thread of an issue
+     - The main conversation thread of a pull request (PR-as-issue comments)
+     It does NOT fire for inline PR code review comments or review summary comments.
+
+  2. pull_request_review_comment — fires when a comment is posted on:
+     - A specific line of code in a PR diff (inline review comment)
+     It does NOT fire for comments on the main PR conversation thread.
+
+  3. pull_request_review — fires when:
+     - A complete PR review is submitted (including review body, approval, or request-changes)
+
+  Chatops bots and automation that listen to issue_comment expecting to catch all PR comment
+  activity will silently miss all PR code review thread comments. There is no error — the
+  workflow simply never fires for that comment type.
+
+  Similarly, on.pull_request_review_comment will miss all main thread comments on the same PR.
+fix: |
+  Choose the correct trigger based on what type of comment you want to react to:
+
+  - For commands in PR main conversation (/deploy, /approve, etc.): use issue_comment
+  - For reactions to inline code review comments: use pull_request_review_comment
+  - For reactions to full review submissions (approve, request changes): use pull_request_review
+  - For all PR comment activity: use both issue_comment AND pull_request_review_comment
+
+  Note: on.issue_comment has access to github.event.issue.number for the PR number,
+  while on.pull_request_review_comment has access to github.event.pull_request.number.
+fix_code:
+  - language: yaml
+    label: 'Listen to all PR comment types (main thread + review thread)'
+    code: |
+      on:
+        issue_comment:
+          types: [created]
+        pull_request_review_comment:
+          types: [created]
+        pull_request_review:
+          types: [submitted]
+
+      jobs:
+        handle-comment:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Handle comment
+              run: |
+                if [ "${{ github.event_name }}" = "issue_comment" ]; then
+                  echo "Main thread comment: ${{ github.event.comment.body }}"
+                  echo "PR number: ${{ github.event.issue.number }}"
+                elif [ "${{ github.event_name }}" = "pull_request_review_comment" ]; then
+                  echo "Review thread comment: ${{ github.event.comment.body }}"
+                  echo "PR number: ${{ github.event.pull_request.number }}"
+                fi
+
+  - language: yaml
+    label: 'Chatops bot — listen for slash commands on main PR thread only'
+    code: |
+      on:
+        issue_comment:
+          types: [created]
+
+      jobs:
+        chatops:
+          # Only run for PR comments (issue_comment also fires on plain issues)
+          if: github.event.issue.pull_request != null
+          runs-on: ubuntu-latest
+          steps:
+            - name: Check for slash command
+              run: |
+                echo "Comment body: ${{ github.event.comment.body }}"
+prevention:
+  - 'Distinguish issue_comment (main PR thread) from pull_request_review_comment (inline code review thread) — they never overlap'
+  - 'If building a PR chatops bot, filter to PR-only comments by checking github.event.issue.pull_request != null'
+  - 'Use pull_request_review for reactions to full review submissions (approve/reject), not pull_request_review_comment'
+  - 'Test your trigger by posting comments in BOTH places (main conversation and code review thread) to verify expected behavior'
+docs:
+  - 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'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#pull_request_review_comment'
+    label: 'GitHub Docs — pull_request_review_comment event'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#pull_request_review'
+    label: 'GitHub Docs — pull_request_review event'
+  - url: 'https://github.com/orgs/community/discussions/21929'
+    label: 'GitHub Community: issue_comment vs pull_request_review_comment confusion'

package/errors/yaml-syntax/branches-and-branches-ignore-combined-same-event.yml

@@ -0,0 +1,99 @@
+id: yaml-syntax-047
+title: '"You can''t use both ''branches'' and ''branches-ignore''" — combined on same event trigger'
+category: yaml-syntax
+severity: error
+tags:
+  - branches
+  - branches-ignore
+  - trigger-filter
+  - validation-error
+  - actionlint
+  - on-push
+patterns:
+  - regex: 'You can''t use both ''branches'' and ''branches-ignore'''
+    flags: 'i'
+  - regex: "You can't use both 'branches' and 'branches-ignore'"
+    flags: 'i'
+  - regex: 'branches.*branches-ignore|branches-ignore.*branches'
+    flags: 'is'
+error_messages:
+  - "You can't use both 'branches' and 'branches-ignore' for the same event."
+  - "Invalid workflow file: .github/workflows/ci.yml: You can't use both 'branches' and 'branches-ignore' for the same event."
+root_cause: |
+  GitHub Actions validates that branches and branches-ignore are mutually exclusive filters
+  on the same trigger event. Using both simultaneously causes a workflow parse error because
+  the semantics are contradictory — branches is an allowlist while branches-ignore is a
+  denylist, and combining them on the same trigger is undefined behavior.
+
+  This restriction applies to all events that support branch filtering, including:
+  - on.push
+  - on.pull_request
+  - on.pull_request_target
+
+  The same restriction applies to paths vs paths-ignore and tags vs tags-ignore.
+
+  Common mistake patterns:
+  - Developer adds branches-ignore: [main] to prevent duplicate runs, forgetting branches is set
+  - Developer copies a snippet with branches and adds branches-ignore without removing the original
+  - Workflow generated from a template that includes both filters from different sections
+
+  Note: branches and paths can coexist on the same trigger (both act as allowlists that AND together).
+  It is only branches + branches-ignore (or paths + paths-ignore) that conflict.
+fix: |
+  Choose one approach and remove the other:
+
+  Option A — Use branches (allowlist): explicitly list which branches should trigger the workflow.
+  Option B — Use branches-ignore (denylist): list which branches should NOT trigger the workflow.
+
+  To achieve "run on all branches except main and release/*", use branches-ignore.
+  To achieve "only run on main and feature/*", use branches.
+
+  For complex patterns (e.g., "feature/* except feature/skip"), use branches with negation
+  via the ! prefix:
+    branches:
+      - 'feature/**'
+      - '!feature/skip-*'
+fix_code:
+  - language: yaml
+    label: 'Broken — branches and branches-ignore on same event (causes validation error)'
+    code: |
+      # BROKEN — do not use both on the same event
+      on:
+        push:
+          branches:
+            - main
+            - 'feature/**'
+          branches-ignore:      # ERROR: cannot combine with branches
+            - 'feature/wip-*'
+
+  - language: yaml
+    label: 'Fixed — use branches with ! negation patterns'
+    code: |
+      on:
+        push:
+          branches:
+            - main
+            - 'feature/**'
+            - '!feature/wip-*'   # negate specific sub-pattern
+
+  - language: yaml
+    label: 'Fixed — use branches-ignore (denylist) alone'
+    code: |
+      on:
+        push:
+          branches-ignore:
+            - 'feature/wip-*'
+            - 'dependabot/**'
+prevention:
+  - 'Never combine branches and branches-ignore on the same trigger event — pick one approach'
+  - 'Use branches (allowlist) when only a few branches should trigger; use branches-ignore (denylist) when most branches should trigger'
+  - 'To exclude specific patterns from an allowlist, use ! negation prefix inside the branches list'
+  - 'Run actionlint in CI to catch this validation error before pushing (actionlint reports it immediately)'
+  - 'The same mutual-exclusion rule applies to paths/paths-ignore and tags/tags-ignore'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/triggering-a-workflow#using-filters'
+    label: 'Using filters — branches, branches-ignore, and negation patterns'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#onpushbranchestagsbranches-ignoretags-ignore'
+    label: 'Workflow syntax — on.push branches and branches-ignore'
+  - url: 'https://rhysd.github.io/actionlint/'
+    label: 'actionlint — static checker that catches this error instantly'

package/errors/yaml-syntax/workflow-call-inputs-no-choice-type.yml

@@ -0,0 +1,121 @@
+id: yaml-syntax-048
+title: 'workflow_call inputs do not support type: choice — validation error when copying from workflow_dispatch'
+category: yaml-syntax
+severity: error
+tags:
+  - workflow-call
+  - reusable-workflow
+  - inputs
+  - type-choice
+  - workflow-dispatch
+  - validation-error
+patterns:
+  - regex: 'Unexpected\s+value\s+[''"]choice[''"]'
+    flags: 'i'
+  - regex: 'type:\s+choice'
+    flags: 'i'
+  - regex: 'on\.workflow_call\.inputs\.[^.]+\.type.*choice'
+    flags: 'i'
+error_messages:
+  - "Unexpected value 'choice'"
+  - "Invalid workflow file: .github/workflows/deploy.yml#L12: Unexpected value 'choice'"
+  - "on.workflow_call.inputs.environment.type: Unexpected value 'choice'"
+  - "inputs.environment.options: Unexpected value"
+root_cause: |
+  GitHub Actions supports two input type systems that are NOT identical:
+  - workflow_dispatch inputs support: string, choice, boolean, environment, number
+  - workflow_call inputs support:     string, boolean, number ONLY
+
+  The `choice` type (with its `options:` list) is exclusive to workflow_dispatch manual triggers.
+  Reusable workflows (workflow_call) do not support `type: choice` or the `options:` field.
+
+  This error is most commonly hit when:
+  1. A developer builds a manual workflow_dispatch workflow with choice inputs
+  2. They convert it to a reusable workflow by changing `on: workflow_dispatch` to `on: workflow_call`
+  3. They leave the `type: choice` and `options:` keys intact
+  4. The workflow fails validation with "Unexpected value 'choice'"
+
+  Example invalid workflow_call input:
+    on:
+      workflow_call:
+        inputs:
+          environment:
+            type: choice        # ERROR: not supported in workflow_call
+            options:            # ERROR: not supported in workflow_call
+              - staging
+              - production
+            required: true
+fix: |
+  Change `type: choice` to `type: string` in workflow_call inputs and remove the `options:` key.
+  To enforce valid values, validate the input inside the workflow body using an `if:` condition
+  or a run step that exits on invalid input.
+
+  The calling workflow or documentation should enumerate the valid values since workflow_call
+  cannot enforce them at the input schema level.
+fix_code:
+  - language: yaml
+    label: 'workflow_call input with string type and manual validation (called workflow)'
+    code: |
+      # .github/workflows/deploy-reusable.yml
+      on:
+        workflow_call:
+          inputs:
+            environment:
+              type: string        # Change 'choice' to 'string'
+              required: true
+              description: 'Target environment: staging or production'
+              # No 'options:' key — not supported in workflow_call
+
+      jobs:
+        validate-input:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Validate environment input
+              run: |
+                if [[ "${{ inputs.environment }}" != "staging" && "${{ inputs.environment }}" != "production" ]]; then
+                  echo "Invalid environment: ${{ inputs.environment }}"
+                  echo "Valid values: staging, production"
+                  exit 1
+                fi
+
+        deploy:
+          needs: validate-input
+          runs-on: ubuntu-latest
+          environment: ${{ inputs.environment }}
+          steps:
+            - run: echo "Deploying to ${{ inputs.environment }}"
+  - language: yaml
+    label: 'Calling workflow passing the environment string input'
+    code: |
+      # .github/workflows/deploy-caller.yml
+      on:
+        workflow_dispatch:
+          inputs:
+            environment:
+              type: choice        # choice IS supported here in workflow_dispatch
+              options:
+                - staging
+                - production
+              required: true
+
+      jobs:
+        call-deploy:
+          uses: ./.github/workflows/deploy-reusable.yml
+          with:
+            environment: ${{ inputs.environment }}  # Pass validated string to reusable
+          secrets: inherit
+prevention:
+  - 'workflow_call inputs only support type: string, boolean, and number — never type: choice or type: environment'
+  - 'Keep workflow_dispatch wrappers that expose choice inputs and call the reusable workflow internally'
+  - 'Document the valid values for string inputs in the description field of workflow_call inputs'
+  - 'Add an explicit validation step at the start of the reusable workflow to enforce allowed values'
+  - 'Use actionlint to catch unsupported input types before pushing the workflow file'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_call'
+    label: 'GitHub Docs — workflow_call inputs (string, boolean, number only)'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_dispatch'
+    label: 'GitHub Docs — workflow_dispatch inputs (includes choice, environment types)'
+  - url: 'https://docs.github.com/en/actions/sharing-automations/reusing-workflows#using-inputs-and-secrets-in-a-reusable-workflow'
+    label: 'GitHub Docs — Reusable workflow inputs and secrets'
+  - url: 'https://github.com/orgs/community/discussions/39357'
+    label: 'GitHub Community — workflow_call does not support type: choice inputs'

package/package.json

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