@htekdev/actions-debugger 1.0.59 → 1.0.61

package/errors/caching-artifacts/fork-pr-cache-isolation.yml

@@ -0,0 +1,114 @@
+id: caching-artifacts-041
+title: "Fork PR workflows cannot read caches from the parent repository — always cache miss"
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - cache
+  - fork
+  - pull-request
+  - security
+  - cache-miss
+  - isolation
+patterns:
+  - regex: 'Cache not found for input keys'
+    flags: i
+  - regex: 'No cache found'
+    flags: i
+error_messages:
+  - "Cache not found for input keys:"
+  - "No cache found"
+root_cause: |
+  GitHub Actions intentionally prevents fork PR workflows from reading caches created by
+  the parent repository. This is a security measure: a malicious fork could craft a cache
+  key matching a parent repo cache, read its contents (which may contain build artifacts,
+  installed dependencies, or sensitive intermediate files), and exfiltrate them via the
+  fork workflow's logs or artifact uploads.
+
+  The restriction applies to `pull_request` events triggered by fork contributors:
+  - The fork workflow runs in a restricted sandbox with a read-only GITHUB_TOKEN
+  - `restore-keys` fallback does NOT traverse to the parent repository's cache namespace
+  - Even a perfect cache key match on the parent repo returns a miss in the fork
+  - The `actions/cache` step reports "Cache not found" with no indication that security
+    isolation is the cause — developers commonly assume misconfigured cache keys
+
+  Affected scenarios:
+  - Open source projects where external contributors submit PRs
+  - npm/pip/gem dependency caches that would accelerate fork CI significantly
+  - Docker buildx layer caches configured via `actions/cache`
+  - Turborepo and Nx remote caches backed by GitHub Actions cache
+fix: |
+  Fork PR cache isolation is intentional and cannot be disabled. Mitigations:
+
+  1. Accept cold builds for fork PRs and optimize speed without cache:
+     Use package manager offline flags (npm ci --prefer-offline, pip --no-index),
+     pre-built base Docker images, and build sharding to minimize cold-build time.
+
+  2. Use `pull_request_target` instead of `pull_request` — this event runs in the parent
+     repo context with full cache access. SECURITY WARNING: this grants the fork workflow
+     write-level GITHUB_TOKEN access. Only safe for workflows that do NOT check out and
+     execute code from the PR head branch.
+
+  3. Pre-warm fork caches via a separate trusted workflow that runs on push to the base
+     branch and stores a cache accessible by the fork's restore-keys fallback scope. This
+     works because forks CAN read the parent's default branch caches via restore-keys.
+     The fork cannot read arbitrary keys, but restore-keys prefix matching against the
+     default branch cache does work.
+fix_code:
+  - language: yaml
+    label: "Accept cold builds — optimize fork PR without relying on cache"
+    code: |
+      on:
+        pull_request:
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-node@v4
+              with:
+                node-version: '20'
+                # Cache works for non-fork PRs; fork PRs will be cold builds
+                cache: 'npm'
+            - name: Install dependencies
+              # --prefer-offline minimizes network round-trips on cold builds
+              run: npm ci --prefer-offline --no-audit
+
+  - language: yaml
+    label: "Restore-keys fallback from default branch — forks CAN match default-branch caches"
+    code: |
+      # Caches saved on the default branch (main/master) ARE accessible to fork PRs
+      # via restore-keys prefix matching. Pre-warm by saving on each push to main.
+      on:
+        push:
+          branches: [main]
+        pull_request:
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - uses: actions/cache@v4
+              with:
+                path: ~/.npm
+                # Exact key includes lockfile hash — will miss on forks
+                key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+                # Restore-key matches default-branch cache — forks get a partial hit
+                restore-keys: |
+                  ${{ runner.os }}-node-
+prevention:
+  - "Document that fork contributor CI will be slower due to cache isolation — set expectations"
+  - "Use restore-keys with a broad prefix to allow forks to partially match default-branch caches"
+  - "Avoid `pull_request_target` with PR head checkout and code execution — this is a high-severity security vulnerability"
+  - "Optimize cold-build speed with offline package manager flags and pre-built base images"
+  - "Consider caching at the Docker image layer level via a registry rather than GitHub Actions cache"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#pull_request"
+    label: "pull_request event — fork restrictions — GitHub Docs"
+  - url: "https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions#using-pull_request_target"
+    label: "Security hardening — pull_request_target risks — GitHub Docs"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows#restrictions-for-accessing-a-cache"
+    label: "Cache access restrictions — GitHub Docs"
+  - url: "https://github.com/orgs/community/discussions/44783"
+    label: "Fork PR workflows cannot access parent repo cache — GitHub Community #44783"

package/errors/concurrency-timing/cancel-in-progress-required-check-cancelled-conclusion.yml

@@ -0,0 +1,84 @@
+id: concurrency-timing-035
+title: "cancel-in-progress posts 'cancelled' conclusion — required status check blocks PR merge"
+category: concurrency-timing
+severity: error
+tags:
+  - concurrency
+  - cancel-in-progress
+  - required-checks
+  - branch-protection
+  - pull-request
+  - status-checks
+patterns:
+  - regex: 'Required status checks have not passed'
+    flags: i
+  - regex: 'cancelled.*required.*check|required.*check.*cancelled'
+    flags: i
+error_messages:
+  - "Required status checks have not passed"
+  - "Branch protection rule requires status check to pass before merging"
+root_cause: |
+  When `cancel-in-progress: true` is configured in a concurrency group and that workflow
+  is a required status check on a branch protection rule, a cancelled run posts a
+  `cancelled` conclusion to the Checks API. GitHub treats `cancelled` as a non-passing
+  conclusion for required status checks — identical to `failure`.
+
+  The failure cycle:
+  1. Push A triggers run A (check posts `in_progress`)
+  2. Push B triggers run B; concurrency group cancels run A
+  3. Run A posts `cancelled` conclusion — required check is now "failed"
+  4. Run B may itself get cancelled by Push C before it completes
+  5. PR is permanently stuck: merge button blocked until a run completes with `success`
+
+  This is especially painful in fast-moving PRs where rapid pushes prevent any run from
+  completing. The `cancelled` status on the required check is indistinguishable from a
+  genuine test failure in the PR view.
+fix: |
+  Option 1 — Use a separate reporter job with `if: always()` that is NOT subject to the
+  concurrency group. The main build job can be cancelled; the reporter always runs and
+  posts the actual status. Configure branch protection to require the reporter job, not
+  the build job.
+
+  Option 2 — Set concurrency at job level instead of workflow level for the job that
+  posts the required status check. The job itself will not be cancelled mid-run; only
+  newly queued workflow runs are affected.
+
+  Option 3 — Accept the pattern and use auto-merge on PRs. Once any non-cancelled run
+  succeeds, the merge proceeds automatically without manual unblocking.
+fix_code:
+  - language: yaml
+    label: "Reporter job pattern — required check never posts 'cancelled'"
+    code: |
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.ref }}
+        cancel-in-progress: true
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm ci && npm test
+
+        # This job is NOT inside the concurrency group — it always runs.
+        # Configure branch protection to require 'report-status', not 'build'.
+        report-status:
+          runs-on: ubuntu-latest
+          needs: [build]
+          if: always()
+          steps:
+            - name: Fail if build did not succeed
+              if: needs.build.result != 'success'
+              run: exit 1
+prevention:
+  - "Test required-check + cancel-in-progress interaction on a draft PR before enabling branch protection"
+  - "Configure branch protection to require a dedicated reporter job, not the cancellable build job"
+  - "Set concurrency at job level for jobs that post required checks"
+  - "Enable auto-merge to reduce manual intervention when cancelled checks momentarily block the PR"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-concurrency"
+    label: "Using concurrency — GitHub Docs"
+  - url: "https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches"
+    label: "About protected branches — GitHub Docs"
+  - url: "https://github.com/orgs/community/discussions/13015"
+    label: "cancel-in-progress fails required status check — GitHub Community #13015"

package/errors/known-unsolved/skipped-job-outputs-empty-string.yml

@@ -0,0 +1,109 @@
+id: known-unsolved-040
+title: "Skipped job outputs always resolve to empty string — downstream consumers receive '' silently"
+category: known-unsolved
+severity: silent-failure
+tags:
+  - outputs
+  - skipped
+  - needs
+  - conditional-jobs
+  - silent-failure
+  - limitation
+patterns:
+  - regex: 'needs\.[a-z_-]+\.outputs\.[a-z_-]+'
+    flags: i
+error_messages: []
+root_cause: |
+  When a job is skipped — because its `if:` condition evaluated to false, or because all
+  jobs in its `needs` array were skipped or failed — that job's `outputs` block never
+  executes. Any downstream job that reads `needs.<skipped-job>.outputs.<key>` receives an
+  empty string `''`.
+
+  This is completely silent: no workflow annotation, no job failure, no warning in the logs.
+  The downstream job receives `''` and continues executing as though the output was
+  legitimately set to an empty string.
+
+  Common failure scenarios:
+  - A build job is gated with `if: github.ref == 'refs/heads/main'`; a deploy job reads
+    its artifact path output and deploys with an empty path string
+  - A matrix job is conditionally skipped on a specific OS; a dependent job reads the
+    OS-specific output and silently operates on an empty value
+  - A fan-out aggregator reads outputs from multiple conditional jobs; skipped job outputs
+    silently produce empty aggregation results
+
+  There is no way to distinguish "output was deliberately set to empty string" from "job
+  was skipped and output was never set". The `needs.<job>.result` value is `'skipped'`
+  but `needs.<job>.outputs.*` is always `''` regardless of cause.
+fix: |
+  There is no built-in mechanism to throw an error when reading outputs from a skipped job.
+  This is a known GitHub Actions limitation — skipped job outputs permanently resolve to ''.
+
+  Workarounds:
+
+  1. Guard downstream jobs with a result check:
+     Add `if: needs.<job>.result == 'success'` to every job that consumes outputs from a
+     conditional job. This prevents the downstream job from running on empty outputs.
+
+  2. Provide explicit sentinel defaults in the output-setting step:
+     Use a shell default expansion in the step that sets the output:
+     `echo "path=${ARTIFACT_PATH:-UNSET}" >> $GITHUB_OUTPUT`
+     Downstream jobs check for `'UNSET'` to detect the unset case.
+
+  3. Inline null-coalescing in expressions:
+     `${{ needs.build.outputs.path != '' && needs.build.outputs.path || 'default-value' }}`
+fix_code:
+  - language: yaml
+    label: "Guard downstream job with result check — prevents execution on empty outputs"
+    code: |
+      jobs:
+        build:
+          if: github.ref == 'refs/heads/main'
+          runs-on: ubuntu-latest
+          outputs:
+            artifact-path: ${{ steps.build.outputs.path }}
+          steps:
+            - id: build
+              run: echo "path=dist/" >> $GITHUB_OUTPUT
+
+        deploy:
+          needs: [build]
+          # Only run if build actually succeeded — never run if skipped or failed
+          if: needs.build.result == 'success'
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Deploying ${{ needs.build.outputs.artifact-path }}"
+
+  - language: yaml
+    label: "Sentinel default — detect skipped output in downstream job"
+    code: |
+      jobs:
+        build:
+          if: github.event_name == 'push'
+          runs-on: ubuntu-latest
+          outputs:
+            version: ${{ steps.ver.outputs.version }}
+          steps:
+            - id: ver
+              run: echo "version=${VERSION:-UNSET}" >> $GITHUB_OUTPUT
+
+        publish:
+          needs: [build]
+          runs-on: ubuntu-latest
+          steps:
+            - name: Abort if build was skipped
+              if: needs.build.outputs.version == 'UNSET' || needs.build.outputs.version == ''
+              run: |
+                echo "Build was skipped or version not set — aborting publish"
+                exit 1
+prevention:
+  - "Always check `needs.<job>.result == 'success'` before using that job's outputs"
+  - "Provide explicit sentinel defaults in output-setting steps for critical values"
+  - "Treat empty string outputs from conditional jobs as indicative of skip or failure"
+  - "Document which jobs are conditional and which downstream jobs depend on their outputs"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/passing-information-between-jobs"
+    label: "Passing information between jobs — GitHub Docs"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/using-conditions-to-control-job-execution"
+    label: "Using conditions to control job execution — GitHub Docs"
+  - url: "https://github.com/orgs/community/discussions/26704"
+    label: "Job outputs from skipped jobs are empty string — GitHub Community #26704"

package/errors/permissions-auth/github-token-cross-repo-dispatch-limitation.yml

@@ -0,0 +1,115 @@
+id: permissions-auth-043
+title: 'GITHUB_TOKEN cannot dispatch workflows or events in other repositories'
+category: permissions-auth
+severity: error
+tags:
+  - GITHUB_TOKEN
+  - repository_dispatch
+  - workflow_dispatch
+  - cross-repo
+  - 404
+  - permissions
+patterns:
+  - regex: 'Resource not accessible by integration'
+    flags: 'i'
+  - regex: '404.*dispatches|dispatches.*404'
+    flags: 'i'
+  - regex: 'HttpError: Not Found'
+    flags: 'i'
+error_messages:
+  - 'Resource not accessible by integration'
+  - 'HttpError: Not Found'
+  - '{"message":"Not Found","documentation_url":"https://docs.github.com/rest/repos/repos#create-a-repository-dispatch-event"}'
+  - 'RequestError [HttpError]: Not Found'
+root_cause: |
+  GITHUB_TOKEN is automatically scoped to the repository where the workflow
+  runs. It cannot authenticate to any other repository, regardless of what is
+  declared in the workflow's permissions block. The permissions block controls
+  only the scopes of the automatically-generated token for the CURRENT repo —
+  it has no effect on access to other repositories.
+
+  Attempts to call the GitHub REST API against a different repository —
+  including POST /repos/{owner}/{other-repo}/dispatches (repository_dispatch)
+  or POST /repos/{owner}/{other-repo}/actions/workflows/{id}/dispatches
+  (workflow_dispatch) — return 404 Not Found. GitHub returns 404 rather than
+  403 to avoid leaking information about whether the target repository exists
+  or is private.
+
+  This is a hard authentication boundary enforced by GitHub's token system,
+  not a configuration issue. No amount of permissions: adjustments in the
+  workflow file can grant the automatic GITHUB_TOKEN cross-repository access.
+
+  Note: this is distinct from the GITHUB_TOKEN loopback limitation (where
+  GITHUB_TOKEN cannot trigger new workflow runs in the SAME repository). This
+  error applies to any cross-repository API call.
+fix: |
+  Replace GITHUB_TOKEN with a credential that has access to the target
+  repository: a Personal Access Token (PAT) with repo scope, or a GitHub App
+  installation token scoped to both repositories. Store the credential as an
+  encrypted repository or organization secret.
+
+  GitHub Apps with installation tokens are the recommended approach for
+  production cross-repo automation — they provide fine-grained permissions,
+  do not depend on a specific user account, and tokens are automatically
+  rotated.
+fix_code:
+  - language: yaml
+    label: 'Use a PAT secret for cross-repo repository_dispatch'
+    code: |
+      jobs:
+        trigger-downstream:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Dispatch event to other repository
+              uses: actions/github-script@v7
+              with:
+                github-token: ${{ secrets.CROSS_REPO_PAT }}
+                script: |
+                  await github.rest.repos.createDispatchEvent({
+                    owner: 'my-org',
+                    repo: 'other-repo',
+                    event_type: 'build-triggered',
+                    client_payload: {
+                      ref: context.ref,
+                      sha: context.sha
+                    }
+                  });
+  - language: yaml
+    label: 'Use a GitHub App installation token for cross-repo workflow dispatch (recommended)'
+    code: |
+      jobs:
+        trigger-downstream:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Generate GitHub App installation token
+              id: app-token
+              uses: actions/create-github-app-token@v1
+              with:
+                app-id: ${{ vars.APP_ID }}
+                private-key: ${{ secrets.APP_PRIVATE_KEY }}
+                owner: my-org
+                repositories: other-repo
+
+            - name: Dispatch workflow in other repository
+              uses: actions/github-script@v7
+              with:
+                github-token: ${{ steps.app-token.outputs.token }}
+                script: |
+                  await github.rest.actions.createWorkflowDispatch({
+                    owner: 'my-org',
+                    repo: 'other-repo',
+                    workflow_id: 'deploy.yml',
+                    ref: 'main'
+                  });
+prevention:
+  - 'Never use ${{ secrets.GITHUB_TOKEN }} in API calls targeting other repositories — it will always 404'
+  - 'Prefer GitHub Apps with installation tokens over PATs for cross-repo automation — scoped, auto-rotating, and not tied to a user account'
+  - 'Store cross-repo PATs as organization secrets so they are reusable across multiple source repositories without per-repo duplication'
+  - 'When debugging 404 on dispatch endpoints, first check whether the token is GITHUB_TOKEN vs a PAT — this is the most common cause'
+docs:
+  - url: 'https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication#permissions-for-the-github_token'
+    label: 'GitHub Docs: Permissions for the GITHUB_TOKEN'
+  - url: 'https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/making-authenticated-api-requests-with-a-github-app-in-a-github-actions-workflow'
+    label: 'GitHub Docs: Authenticating with a GitHub App in GitHub Actions'
+  - url: 'https://github.com/orgs/community/discussions/26724'
+    label: 'GitHub Community: GITHUB_TOKEN cannot dispatch to another repository'

package/errors/silent-failures/reusable-workflow-outputs-undeclared-workflow-level.yml

@@ -0,0 +1,95 @@
+id: silent-failures-060
+title: 'Reusable workflow outputs not declared at on.workflow_call.outputs are silently empty in callers'
+category: silent-failures
+severity: silent-failure
+tags:
+  - reusable-workflow
+  - workflow_call
+  - outputs
+  - empty-string
+  - silent-failure
+patterns:
+  - regex: 'needs\.[a-z][a-z0-9_-]*\.outputs\.[a-z][a-z0-9_-]*'
+    flags: 'i'
+error_messages:
+  - '(no error emitted — callers receive empty strings silently)'
+  - 'Error: Input required and not supplied'
+root_cause: |
+  Reusable workflows require a two-level output declaration. Developers
+  correctly declare job-level outputs under jobs.<job-id>.outputs, but omit
+  the second required declaration: the workflow-level outputs block under
+  on.workflow_call.outputs.
+
+  Without the workflow-level outputs declaration, any caller that references
+  ${{ needs.<call-job>.outputs.<name> }} receives an empty string. GitHub
+  Actions does not emit any error, warning, or annotation — downstream steps
+  silently receive empty values, producing wrong behavior or spurious failures
+  (e.g., artifact path is empty, deployment target is blank).
+
+  The root cause is that GitHub's reusable workflow output model requires two
+  separate declarations:
+    1. job.outputs: maps a step output to a job-scoped output
+    2. on.workflow_call.outputs: hoists a job output up to the workflow level
+       so external callers can reference it
+
+  Omitting level 2 is invisible — the job output exists internally but is
+  never exposed to the calling workflow.
+fix: |
+  Add an outputs block directly under on.workflow_call that maps each desired
+  workflow output name to ${{ jobs.<job-id>.outputs.<output-name> }}. This is
+  in addition to (not a replacement for) the job-level outputs block.
+fix_code:
+  - language: yaml
+    label: 'Reusable workflow: declare outputs at both job level and on.workflow_call level'
+    code: |
+      on:
+        workflow_call:
+          outputs:
+            build-version:
+              description: 'The semantic version produced by this workflow'
+              value: ${{ jobs.build.outputs.build-version }}
+            artifact-path:
+              description: 'Path to the uploaded artifact'
+              value: ${{ jobs.build.outputs.artifact-path }}
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          outputs:
+            build-version: ${{ steps.version.outputs.version }}
+            artifact-path: ${{ steps.upload.outputs.artifact-path }}
+          steps:
+            - id: version
+              run: echo "version=1.2.3" >> "$GITHUB_OUTPUT"
+              shell: bash
+            - id: upload
+              uses: actions/upload-artifact@v4
+              with:
+                name: my-artifact
+                path: dist/
+  - language: yaml
+    label: 'Calling workflow: access reusable workflow outputs via needs context'
+    code: |
+      jobs:
+        call-build:
+          uses: ./.github/workflows/build.yml
+
+        deploy:
+          needs: call-build
+          runs-on: ubuntu-latest
+          steps:
+            - name: Use build outputs
+              run: |
+                echo "Version: ${{ needs.call-build.outputs.build-version }}"
+                echo "Artifact: ${{ needs.call-build.outputs.artifact-path }}"
+              shell: bash
+prevention:
+  - 'Always declare outputs under on.workflow_call.outputs in addition to any job-level outputs blocks — they are two distinct YAML nodes'
+  - 'Immediately echo needs.<call-job>.outputs.* in the caller after wiring up to verify outputs are populated during development'
+  - 'Use actionlint locally or in CI to catch missing workflow-level output declarations before they ship'
+  - 'Treat the two-level declaration as a checklist: job outputs block + workflow_call outputs block'
+docs:
+  - url: 'https://docs.github.com/en/actions/sharing-automations/reusing-workflows#using-outputs-from-a-reusable-workflow'
+    label: 'GitHub Docs: Using outputs from a reusable workflow'
+  - url: 'https://github.com/orgs/community/discussions/17245'
+    label: 'GitHub Community: Outputs from reusable workflow missing in caller'

package/errors/silent-failures/workflow-call-boolean-input-string-coercion.yml

@@ -0,0 +1,98 @@
+id: silent-failures-061
+title: "`workflow_call` boolean inputs evaluate as strings — `if: inputs.flag` is truthy even when caller passes `false`"
+category: silent-failures
+severity: silent-failure
+tags:
+  - workflow-call
+  - reusable-workflow
+  - boolean
+  - inputs
+  - if-condition
+  - type-coercion
+patterns:
+  - regex: 'inputs\.[a-z_-]+\s*(?:==\s*true|==\s*false)?'
+    flags: i
+error_messages: []
+root_cause: |
+  In `on.workflow_call` inputs, declaring `type: boolean` describes the intended type of
+  the input — it does NOT cause the value to be passed as a JSON boolean. At runtime,
+  inside the called workflow, `${{ inputs.my_flag }}` always evaluates to the string
+  `'true'` or `'false'`.
+
+  Because non-empty strings are truthy in GitHub Actions expression evaluation:
+  - `if: inputs.my_flag` evaluates the string `'false'` as TRUTHY (non-empty string = true)
+  - Steps and jobs conditioned on `if: inputs.my_flag` run even when the caller passes false
+
+  This is distinct from the `workflow_dispatch` boolean input coercion issue (silent-failures-053)
+  in that it affects all callers of a reusable workflow simultaneously. A single bug in a
+  widely-used reusable workflow can cause unintended deploys, notifications, or expensive
+  steps to run across every calling workflow.
+
+  Example of the failure:
+  Caller passes `deploy: false` intending to skip deployment.
+  Reusable workflow has `if: inputs.deploy` on its deploy job.
+  The deploy job runs because the string 'false' is non-empty and therefore truthy.
+fix: |
+  Always compare boolean inputs against the boolean literal `true` using `==`, or use
+  `fromJSON()` to parse the string to an actual boolean value:
+
+  CORRECT patterns:
+  - `if: inputs.my_flag == true`   — Actions coerces the string 'true' to boolean true for == comparison
+  - `if: fromJSON(inputs.my_flag)` — parses string 'true'/'false' to actual boolean
+
+  WRONG patterns:
+  - `if: inputs.my_flag`           — always true for non-empty strings ('false' is truthy)
+  - `if: inputs.my_flag == 'true'` — works but fragile; fails if value is boolean true not string
+fix_code:
+  - language: yaml
+    label: "Correct boolean input handling in reusable workflow"
+    code: |
+      # reusable.yml
+      on:
+        workflow_call:
+          inputs:
+            deploy:
+              type: boolean
+              default: false
+            notify:
+              type: boolean
+              default: true
+
+      jobs:
+        deploy:
+          # Correct: == true comparison handles string-to-boolean coercion
+          if: inputs.deploy == true
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Deploying..."
+
+        notify:
+          # Alternative: fromJSON() parses string to actual boolean
+          if: fromJSON(inputs.notify)
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Notifying..."
+
+  - language: yaml
+    label: "Caller side — no change needed; fix is in the reusable workflow"
+    code: |
+      # caller.yml — calling the reusable workflow
+      jobs:
+        call-reusable:
+          uses: ./.github/workflows/reusable.yml
+          with:
+            deploy: false   # This passes as string 'false' — fix is in reusable.yml
+            notify: true
+prevention:
+  - "Audit all reusable workflows for bare `if: inputs.<name>` patterns where the input is type boolean"
+  - "Use `if: inputs.<flag> == true` consistently — never `if: inputs.<flag>` for boolean inputs"
+  - "Add a comment in reusable workflows noting that boolean inputs are strings at runtime"
+  - "Test callers with both `true` and `false` values and verify both branches execute as expected"
+  - "Consider wrapping boolean inputs in `fromJSON()` at the point of use for clarity"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/evaluate-expressions-in-workflows-and-actions#literals"
+    label: "Expressions — literals and type coercion — GitHub Docs"
+  - url: "https://docs.github.com/en/actions/sharing-automations/reusing-workflows#using-inputs-and-secrets-in-a-reusable-workflow"
+    label: "Reusable workflows — using inputs — GitHub Docs"
+  - url: "https://github.com/orgs/community/discussions/45843"
+    label: "workflow_call boolean inputs evaluated as truthy strings — GitHub Community #45843"

package/errors/triggers/pull-request-target-checkout-base-branch.yml

@@ -0,0 +1,101 @@
+id: triggers-044
+title: 'pull_request_target checks out base branch by default — PR head requires explicit ref'
+category: triggers
+severity: silent-failure
+tags:
+  - pull_request_target
+  - checkout
+  - ref
+  - base-branch
+  - security
+  - fork
+patterns:
+  - regex: 'on:\s*\n\s*pull_request_target'
+    flags: 'im'
+  - regex: 'uses:\s*actions/checkout.*\n(?!.*ref:)'
+    flags: 'im'
+error_messages:
+  - '(no error — workflow runs against base branch code, not PR changes)'
+root_cause: |
+  pull_request_target runs in the context of the BASE repository rather than
+  the contributor's fork. This is an intentional security boundary: because
+  the workflow has access to repository secrets and typically runs with write
+  permissions, GitHub executes it against trusted code on the base branch
+  rather than potentially untrusted PR code.
+
+  As a direct consequence, actions/checkout without an explicit ref: parameter
+  checks out the TARGET BRANCH (e.g., main), not the contributor's changes.
+  The workflow appears to run successfully — tests pass, linters pass — but
+  only because they are testing the existing base branch code. The PR's actual
+  changes are completely ignored. CI gives a false green for every PR
+  regardless of what was submitted.
+
+  This is among the most common misuses of pull_request_target, appearing
+  frequently in workflows that were migrated from pull_request to gain write
+  access (e.g., to post PR comments or add labels) without understanding the
+  checkout difference.
+fix: |
+  If the goal is to build and test PR code, use on: pull_request instead of
+  pull_request_target. pull_request runs in the fork context with limited
+  permissions, which is the correct and safe choice for CI testing.
+
+  Reserve pull_request_target only for operations that specifically need write
+  permissions or secrets AND that do NOT execute untrusted PR code (e.g.,
+  adding labels based on event metadata, posting a comment using a stored
+  token). If pull_request_target must check out PR code, consult the GitHub
+  Security Lab advisory on pwn requests first — the attack surface is
+  significant.
+fix_code:
+  - language: yaml
+    label: 'Preferred: use pull_request for code testing workflows (runs against PR head safely)'
+    code: |
+      on:
+        pull_request:
+          branches: [main]
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          permissions:
+            contents: read
+          steps:
+            - uses: actions/checkout@v4
+              # No ref needed — pull_request automatically checks out the merge commit
+            - run: npm ci && npm test
+              shell: bash
+  - language: yaml
+    label: 'Safe pull_request_target: metadata-only operations — no checkout of PR code'
+    code: |
+      on:
+        pull_request_target:
+          types: [opened, synchronize, labeled]
+
+      jobs:
+        label:
+          runs-on: ubuntu-latest
+          permissions:
+            pull-requests: write
+          steps:
+            # Safe: uses only github.event data, does NOT check out PR code
+            - name: Add triage label
+              uses: actions/github-script@v7
+              with:
+                script: |
+                  await github.rest.issues.addLabels({
+                    owner: context.repo.owner,
+                    repo: context.repo.repo,
+                    issue_number: context.payload.pull_request.number,
+                    labels: ['needs-review']
+                  });
+prevention:
+  - 'Default to on: pull_request for all CI testing workflows — it checks out PR code correctly and runs with limited permissions'
+  - 'Only use pull_request_target when write permissions or secrets are required AND untrusted PR code is never executed'
+  - 'If pull_request_target is in a workflow, verify there is NO actions/checkout step (or that it explicitly uses a trusted ref)'
+  - 'Review the GitHub Security Lab pwn requests advisory before combining pull_request_target with any form of code execution from the PR'
+docs:
+  - 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'
+  - url: 'https://securitylab.github.com/research/github-actions-preventing-pwn-requests/'
+    label: 'GitHub Security Lab: Preventing pwn requests in GitHub Actions'
+  - url: 'https://github.com/orgs/community/discussions/15669'
+    label: 'GitHub Community: pull_request_target and checkout behavior'

package/errors/yaml-syntax/composite-action-run-step-missing-shell.yml

@@ -0,0 +1,93 @@
+id: yaml-syntax-042
+title: 'Composite action run steps require explicit shell property — no default shell is applied'
+category: yaml-syntax
+severity: error
+tags:
+  - composite-action
+  - shell
+  - run-step
+  - action-yaml
+  - validation-error
+patterns:
+  - regex: 'Required property is missing: shell'
+    flags: 'i'
+  - regex: 'The `shell` property must be set'
+    flags: 'i'
+  - regex: 'shell is required for `run` step in composite action'
+    flags: 'i'
+error_messages:
+  - 'Required property is missing: shell'
+  - 'The `shell` property must be set for step `run` in composite actions'
+  - "Error: Unexpected value ''"
+root_cause: |
+  Regular workflow jobs default to bash on Linux and macOS, and pwsh on
+  Windows, when the shell property is omitted from a run step. Composite
+  actions (using: composite) do not inherit any default shell — every run
+  step must explicitly declare a shell value such as bash, pwsh, sh, or cmd.
+
+  This inconsistency frequently catches developers who copy run steps from a
+  workflow job into a composite action's action.yml without adding shell: bash.
+  The error surfaces immediately on the first run and is caught by the runner's
+  action schema validation, but the message can be confusing because shell is
+  a property developers rarely need to specify in regular workflows.
+
+  The GitHub Actions runner enforces this requirement because composite actions
+  must be portable across multiple callers (Linux, macOS, Windows) and the
+  runner has no basis to assume which shell is appropriate without the caller
+  specifying one.
+fix: |
+  Add shell: bash (or shell: pwsh on Windows-targeted steps, shell: sh for
+  minimal Alpine images) to every run step in the composite action's
+  action.yml. If the action must support multiple operating systems, use a
+  conditional expression to select the shell based on runner.os.
+fix_code:
+  - language: yaml
+    label: 'action.yml: add explicit shell to every run step in a composite action'
+    code: |
+      name: My Composite Action
+      description: 'Example composite action with correct shell declarations'
+      runs:
+        using: composite
+        steps:
+          - name: Install dependencies
+            run: npm ci
+            shell: bash
+
+          - name: Build
+            run: npm run build
+            shell: bash
+
+          - name: Run tests
+            run: npm test
+            shell: bash
+  - language: yaml
+    label: 'Cross-platform composite action: select shell via runner.os expression'
+    code: |
+      runs:
+        using: composite
+        steps:
+          - name: Platform-aware step
+            run: echo "Running on ${{ runner.os }}"
+            shell: ${{ runner.os == 'Windows' && 'pwsh' || 'bash' }}
+
+          - name: Windows-only step
+            if: runner.os == 'Windows'
+            run: Write-Host "Windows step"
+            shell: pwsh
+
+          - name: Unix step
+            if: runner.os != 'Windows'
+            run: echo "Unix step"
+            shell: bash
+prevention:
+  - 'Add shell: bash to every run step when authoring or editing a composite action — treat it as required boilerplate'
+  - 'Use actionlint or the VS Code GitHub Actions extension to surface missing shell properties before committing'
+  - 'Keep a composite action template or snippet that includes shell: bash by default in every run step'
+  - 'When converting a workflow job to a composite action, do a search for all run: blocks and add shell: to each'
+docs:
+  - url: 'https://docs.github.com/en/actions/sharing-automations/creating-actions/metadata-syntax-for-github-actions#runsusing-for-composite-actions'
+    label: 'GitHub Docs: Metadata syntax for composite actions'
+  - url: 'https://github.com/actions/runner/issues/835'
+    label: 'actions/runner #835: Composite actions should have a default shell'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsshell'
+    label: 'GitHub Docs: Workflow syntax — steps.shell'

package/package.json

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