@htekdev/actions-debugger 1.0.60 → 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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@htekdev/actions-debugger",
-  "version": "1.0.60",
+  "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",