@htekdev/actions-debugger 1.0.60 → 1.0.62

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/permissions-auth-044.yml

@@ -0,0 +1,82 @@
+id: permissions-auth-044
+title: "OIDC token sub claim format changes inside reusable workflow jobs, breaking cloud provider trust policies"
+category: permissions-auth
+severity: error
+tags:
+  - oidc
+  - reusable-workflow
+  - aws
+  - gcp
+  - trust-policy
+  - sub-claim
+  - job-workflow-ref
+patterns:
+  - regex: 'Not authorized to perform sts:AssumeRoleWithWebIdentity'
+    flags: i
+  - regex: 'failed to generate Google Cloud federated token'
+    flags: i
+  - regex: 'Credentials could not be loaded.*Could not load credentials from any providers'
+    flags: i
+error_messages:
+  - "An error occurred (AccessDenied) when calling the AssumeRoleWithWebIdentity operation: Not authorized to perform sts:AssumeRoleWithWebIdentity"
+  - "Error: google-github-actions/auth failed to generate Google Cloud federated token for..."
+  - "Error: Credentials could not be loaded, please check your action inputs: Could not load credentials from any providers"
+root_cause: |
+  When a job runs inside a reusable workflow (called via uses:), GitHub changes the format of
+  the OIDC token sub claim to include the calling workflow's path. For a direct job the sub is:
+    repo:ORG/REPO:ref:refs/heads/main
+  For a job inside a reusable workflow the sub becomes:
+    repo:ORG/REPO:job_workflow_ref:ORG/REPO/.github/workflows/reusable.yml@refs/heads/main
+  AWS IAM OIDC trust policies and GCP Workload Identity Federation attribute conditions that
+  were configured to match the simpler ref-based sub format now reject the OIDC token with an
+  AccessDenied error. The error message gives no indication that the sub claim format changed —
+  it looks identical to any other OIDC trust policy mismatch.
+fix: |
+  Update the cloud provider's OIDC trust policy to match the new sub claim format used by
+  reusable workflow jobs. For AWS, update the IAM trust policy StringLike condition to match
+  job_workflow_ref instead of ref. For GCP, update the attribute condition in the Workload
+  Identity Pool provider. Alternatively, use GitHub's OIDC subject claim customization feature
+  (repo Settings → Actions → General → OIDC subject claims) to define a consistent sub claim
+  template that works for both caller and reusable workflow jobs.
+fix_code:
+  - language: yaml
+    label: "Reusable workflow with id-token permission declared (required)"
+    code: |
+      # In the reusable workflow file (.github/workflows/reusable.yml):
+      on:
+        workflow_call:
+
+      permissions:
+        id-token: write
+        contents: read
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Configure AWS credentials
+              uses: aws-actions/configure-aws-credentials@v4
+              with:
+                role-to-assume: arn:aws:iam::123456789:role/my-role
+                aws-region: us-east-1
+  - language: yaml
+    label: "AWS IAM trust policy StringLike condition for reusable workflow sub claim"
+    code: |
+      # Update AWS IAM role trust policy Condition block to match reusable workflow sub format.
+      # Old (direct job):   "repo:ORG/REPO:ref:refs/heads/main"
+      # New (reusable job): "repo:ORG/REPO:job_workflow_ref:ORG/REPO/.github/workflows/reusable.yml@refs/heads/main"
+      #
+      # Use a wildcard to allow both patterns:
+      # "token.actions.githubusercontent.com:sub": "StringLike": ["repo:ORG/REPO:*"]
+prevention:
+  - "When refactoring direct jobs into reusable workflows, update cloud OIDC trust policies before deploying"
+  - "Use GitHub subject claim customization to define a consistent sub format that works across direct and reusable jobs"
+  - "Document the expected OIDC sub claim format in the reusable workflow README alongside cloud policy requirements"
+  - "Test OIDC authentication in a staging cloud environment when moving jobs into reusable workflows"
+docs:
+  - url: https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/using-openid-connect-with-reusable-workflows
+    label: "GitHub Docs: Using OIDC with reusable workflows"
+  - url: https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/about-security-hardening-with-openid-connect#customizing-the-subject-claims-for-an-organization-or-repository
+    label: "GitHub Docs: Customizing OIDC subject claims"
+  - url: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_oidc.html
+    label: "AWS Docs: Creating IAM OIDC identity providers"

package/errors/runner-environment/runner-environment-123.yml

@@ -0,0 +1,61 @@
+id: runner-environment-123
+title: "actions/checkout@v6 breaks Docker container actions that use git authentication"
+category: runner-environment
+severity: error
+tags:
+  - checkout
+  - v6
+  - docker
+  - container-action
+  - git-auth
+  - breaking-change
+patterns:
+  - regex: 'fatal: could not read Username for.*No such device or address'
+    flags: i
+  - regex: 'fatal: Authentication failed for.*github\.com'
+    flags: i
+  - regex: 'fatal: credential helper.*is not executable'
+    flags: i
+error_messages:
+  - "fatal: could not read Username for 'https://github.com/': No such device or address"
+  - "fatal: Authentication failed for 'https://github.com/org/repo.git/'"
+  - "Error: The process '/usr/bin/git' failed with exit code 128"
+root_cause: |
+  actions/checkout@v6 changed credential storage: credentials are now written to the runner's
+  native credential manager rather than the global gitconfig file. Docker container actions run
+  in isolated containers without access to the runner host's credential store, so any git
+  operations inside a Docker-based action or container: job that require authentication fail.
+  This is a breaking change from v5, where credentials were written to gitconfig and could be
+  inherited by Docker containers. The v6 runner PR #4011 introduced this mechanism and Docker
+  container action support is gated behind a feature flag not yet enabled for all runners.
+fix: |
+  Pin to actions/checkout@v5 for workflows that rely on Docker container actions making
+  authenticated git calls. Monitor the actions/checkout issue tracker for v6 Docker container
+  action support. Alternatively, pass the GITHUB_TOKEN as an environment variable to the Docker
+  action and configure credentials inside the container's own entrypoint script.
+fix_code:
+  - language: yaml
+    label: "Pin to actions/checkout@v5 for Docker container action compatibility"
+    code: |
+      - name: Checkout repository
+        uses: actions/checkout@v5
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+  - language: yaml
+    label: "Pass token as env var to Docker action for container-side credential setup"
+    code: |
+      - name: Run Docker-based action with explicit token
+        uses: org/my-docker-action@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+prevention:
+  - "Pin actions/checkout to a tested major version and review release notes before upgrading to a new major"
+  - "Audit workflows for Docker container actions that perform authenticated repository operations before upgrading checkout"
+  - "Test Docker-based custom actions in CI against the new checkout version before rolling out"
+docs:
+  - url: https://github.com/actions/checkout/issues/2313
+    label: "actions/checkout#2313: v6 breaks Docker actions that use git authentication"
+  - url: https://github.com/orgs/community/discussions/179107
+    label: "GitHub Community: actions/checkout v6 changes discussion"
+  - url: https://github.com/actions/runner/pull/4011
+    label: "actions/runner PR#4011: credential manager changes introduced in v6"

package/errors/runner-environment/runner-environment-124.yml

@@ -0,0 +1,68 @@
+id: runner-environment-124
+title: "actions/setup-go@v6 GOTOOLCHAIN auto mode downloads unexpected Go version from go.mod toolchain directive"
+category: runner-environment
+severity: silent-failure
+tags:
+  - setup-go
+  - v6
+  - gotoolchain
+  - go-version
+  - toolchain-directive
+  - breaking-change
+patterns:
+  - regex: 'go: downloading go\d+\.\d+\.\d+ \('
+    flags: i
+  - regex: 'toolchain go\d+\.\d+\.\d+ cannot be used because it would require a later version'
+    flags: i
+  - regex: 'go: toolchain go\d+\.\d+\.\d+ not available on GOPROXY'
+    flags: i
+error_messages:
+  - "go: downloading go1.23.4 (linux/amd64)"
+  - "toolchain go1.23.4 cannot be used because it would require a later version"
+  - "go: toolchain go1.23.4 not available on GOPROXY"
+root_cause: |
+  actions/setup-go@v6 (released September 2025) changed toolchain handling to honor Go 1.21+
+  GOTOOLCHAIN semantics. When a go.mod file contains a 'toolchain goX.Y.Z' directive and
+  GOTOOLCHAIN is set to 'auto' (the default for Go 1.21+), Go will automatically download the
+  toolchain version specified in go.mod rather than using the version installed by setup-go.
+  The workflow runs with a different Go version than the one specified in the go-version: input,
+  causing unexpected behavior, build failures, or unintended Go version usage. In v5, setup-go
+  implicitly set GOTOOLCHAIN=local, preventing automatic toolchain downloads. v6 removed this
+  implicit override, meaning go.mod toolchain directives now take effect in CI.
+fix: |
+  Set GOTOOLCHAIN=local in the step environment to force Go to use exactly the version installed
+  by setup-go, ignoring the toolchain directive in go.mod. Alternatively, align the go-version:
+  input with the toolchain directive in go.mod, or use go-version-file: go.mod to let setup-go
+  read the version directly from the module file.
+fix_code:
+  - language: yaml
+    label: "Set GOTOOLCHAIN=local to prevent auto-download — use exactly the installed version"
+    code: |
+      - name: Set up Go
+        uses: actions/setup-go@v6
+        with:
+          go-version: '1.22'
+
+      - name: Build
+        run: go build ./...
+        env:
+          GOTOOLCHAIN: local   # disables auto-download; uses only the version from setup-go
+  - language: yaml
+    label: "Or read go-version directly from go.mod to stay aligned with the toolchain directive"
+    code: |
+      - name: Set up Go
+        uses: actions/setup-go@v6
+        with:
+          go-version-file: go.mod   # reads 'go X.Y' line from go.mod; stays in sync automatically
+prevention:
+  - "After upgrading to setup-go@v6, verify the actual Go version used in builds matches the go-version: input"
+  - "Add GOTOOLCHAIN=local to workflow env or per-step env to opt out of automatic toolchain download behavior"
+  - "Keep the go.mod toolchain directive in sync with the go-version: value specified in setup-go"
+  - "Use go-version-file: go.mod instead of an explicit go-version: value to stay automatically aligned"
+docs:
+  - url: https://github.com/actions/setup-go/releases/tag/v6.0.0
+    label: "actions/setup-go v6.0.0 release notes — toolchain handling breaking change"
+  - url: https://github.com/actions/setup-go/pull/460
+    label: "actions/setup-go PR#460: Improve toolchain handling"
+  - url: https://go.dev/doc/toolchain
+    label: "Go documentation: Toolchains — GOTOOLCHAIN environment variable"

package/errors/silent-failures/silent-failures-062.yml

@@ -0,0 +1,66 @@
+id: silent-failures-062
+title: "actions/cache save failure emits Warning annotation but does not fail the workflow step"
+category: silent-failures
+severity: silent-failure
+tags:
+  - cache
+  - cache-save
+  - warning
+  - non-fatal
+  - false-success
+  - cache-service
+patterns:
+  - regex: 'Warning: Failed to save:.*Failed to CreateCacheEntry.*non-retryable'
+    flags: i
+  - regex: 'Warning: Failed to restore:.*Failed to GetCacheEntryDownloadURL.*non-retryable'
+    flags: i
+error_messages:
+  - "Warning: Failed to save: Failed to CreateCacheEntry: Received non-retryable error: Failed request: (404) Not Found: invalid request"
+  - "Warning: Failed to restore: Failed to GetCacheEntryDownloadURL: Received non-retryable error: Failed request: (404) Not Found: invalid request"
+root_cause: |
+  The actions/cache and actions/cache/save actions treat upload failures as non-fatal warnings
+  rather than step errors. When the GitHub cache backend returns an error (4xx/5xx), is
+  unavailable, or rejects the request, the action emits a yellow Warning annotation in the
+  workflow log but exits with code 0. The workflow step is marked green (success). Downstream
+  runs then see genuine "Cache not found" misses since nothing was persisted. Developers assume
+  the cache was saved based on the green checkmark, spending hours debugging unreliable cache
+  restore before finding the Warning annotation buried in the save step output. This behavior is
+  intentional — cache is treated as an optimization, not a requirement — but it means failures
+  are invisible unless annotations are actively checked.
+fix: |
+  Check step-level annotations (the yellow warning triangle icon) on cache save steps, not just
+  the green/red status indicator. Use fail-on-cache-miss: true on restore steps when cache
+  availability is critical to your build speed so that a missing cache surfaces as a hard
+  failure. For save failures there is no built-in fail flag — add a downstream validation step
+  if guaranteed cache persistence is required. Always use supported cache action versions
+  (actions/cache@v3 or @v4) to ensure compatibility with the current cache backend service.
+fix_code:
+  - language: yaml
+    label: "Use fail-on-cache-miss on restore to surface missing cache as an error"
+    code: |
+      - name: Restore build cache
+        id: restore-cache
+        uses: actions/cache/restore@v4
+        with:
+          key: ${{ runner.os }}-build-${{ hashFiles('**/package-lock.json') }}
+          path: ~/.npm
+          fail-on-cache-miss: true   # step fails with error if nothing was previously saved
+
+      - name: Save build cache
+        if: always()
+        uses: actions/cache/save@v4
+        with:
+          key: ${{ runner.os }}-build-${{ hashFiles('**/package-lock.json') }}
+          path: ~/.npm
+prevention:
+  - "Always check workflow annotations (yellow warning triangle) in addition to the step pass/fail status"
+  - "Use actions/cache@v4 or @v3 — deprecated pinned SHAs may fail silently after the cache backend migration"
+  - "Use fail-on-cache-miss: true on restore steps to make cache misses visible as hard failures"
+  - "Monitor the actions/cache issue tracker when cache restore reliability degrades — backend incidents are reported quickly"
+docs:
+  - url: https://github.com/actions/cache/issues/1541
+    label: "actions/cache#1541: Bug: Failed to CreateCacheEntry (29 reactions, Feb 2025)"
+  - url: https://github.com/actions/cache/discussions/1510
+    label: "actions/cache Discussion#1510: Deprecation Notice — upgrade to latest before Feb 2025"
+  - 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 — fail-on-cache-miss option"

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.62",
   "description": "65+ real GitHub Actions errors, queryable by agents. CLI + MCP server + Copilot skills + error database.",
   "type": "module",
   "main": "./dist/index.js",