@htekdev/actions-debugger 1.0.62 → 1.0.63

package/errors/caching-artifacts/cache-key-github-sha-no-restore.yml

@@ -0,0 +1,72 @@
+id: caching-artifacts-042
+title: "Cache key containing github.sha always misses on restore — cache is saved but never reused"
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - cache
+  - cache-key
+  - github-sha
+  - cache-miss
+  - restore-keys
+  - performance
+patterns:
+  - regex: 'Cache not found for input keys: .*\b[0-9a-f]{40}\b'
+    flags: i
+  - regex: 'Warning: Cache not found for.*sha.*\.'
+    flags: i
+  - regex: 'Cache restored from key: .*\b[0-9a-f]{40}\b'
+    flags: i
+error_messages:
+  - "Cache not found for input keys: Linux-node-a3f2b1c9d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9"
+  - "Warning: Cache not found for key: ubuntu-latest-npm-abc1234def5678901234567890abcdef12345678"
+root_cause: |
+  When a cache key includes ${{ github.sha }}, every commit produces a unique key. The cache is
+  saved successfully at the end of the workflow, but on the very next run the sha is different,
+  so the restore step finds no matching cache entry and declares a miss. This pattern ensures
+  the cache is written once and thrown away — it provides no performance benefit.
+
+  This mistake is common because github.sha is a readily available context value and its use
+  in cache keys looks reasonable at first glance. The cache action's restore-keys fallback
+  mechanism would normally rescue a miss, but developers often omit restore-keys when using
+  sha-based keys, expecting the primary key to match.
+fix: |
+  Replace github.sha with a hash of the files that determine cache validity, such as
+  hashFiles('**/package-lock.json') for npm or hashFiles('**/go.sum') for Go. Use github.sha
+  only as a restore-keys fallback prefix if you want a per-commit cache layer on top of a
+  stable base cache. The cache key should be stable across commits unless the relevant
+  dependency manifest changes.
+fix_code:
+  - language: yaml
+    label: "Correct cache key using hashFiles instead of github.sha"
+    code: |
+      - name: Cache node modules
+        uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-node-
+  - language: yaml
+    label: "Per-commit layer on top of a stable base cache (advanced)"
+    code: |
+      # Stable key hits on re-runs; sha layer saves per-commit installs
+      - name: Cache node modules
+        uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-node-${{ github.sha }}
+          restore-keys: |
+            ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+            ${{ runner.os }}-node-
+prevention:
+  - "Never use github.sha as a primary cache key unless you explicitly want a per-commit cache that never restores"
+  - "Use hashFiles() over the relevant lock file or manifest as the stable portion of the cache key"
+  - "Always add restore-keys with progressively broader prefixes to benefit from partial cache hits"
+  - "Check the cache hit rate in the Actions UI — 0% hit rate on restore is a sign the key is too unique"
+docs:
+  - url: https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows#using-the-cache-action
+    label: "GitHub Docs: Using the cache action"
+  - url: https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows#matching-a-cache-key
+    label: "GitHub Docs: Matching a cache key"
+  - url: https://stackoverflow.com/questions/59435153/github-actions-cache-miss-every-run
+    label: "Stack Overflow: GitHub Actions cache miss every run"

package/errors/permissions-auth/github-token-fork-pr-read-only.yml

@@ -0,0 +1,114 @@
+id: permissions-auth-045
+title: "GITHUB_TOKEN has read-only access in pull_request workflows from forks — write operations return 403"
+category: permissions-auth
+severity: error
+tags:
+  - github-token
+  - fork
+  - pull-request
+  - read-only
+  - permissions
+  - resource-not-accessible
+  - write-access
+patterns:
+  - regex: 'Resource not accessible by integration'
+    flags: i
+  - regex: 'HttpError: Resource not accessible by integration'
+    flags: i
+  - regex: 'Error: HttpError: Not Found.*token.*forked'
+    flags: i
+  - regex: 'refused.*write.*403.*pull_request.*fork'
+    flags: i
+error_messages:
+  - "Error: Resource not accessible by integration"
+  - "RequestError [HttpError]: Resource not accessible by integration"
+  - "Error: HttpError: Resource not accessible by integration"
+root_cause: |
+  When a pull_request workflow is triggered by a PR from a forked repository, GitHub
+  automatically restricts the GITHUB_TOKEN to read-only permissions. This security measure
+  prevents malicious PRs from using the token to modify the base repository — the token
+  cannot create issues, post comments, create releases, trigger deployments, or write to
+  the repository. Workflows see a token that behaves as if all write permissions were denied.
+
+  This restriction applies even if the workflow YAML has explicit permissions: write entries.
+  The fork security boundary takes precedence. The workflow still runs (unlike pull_request_target
+  which runs with base repo permissions), but the token scope is silently reduced.
+
+  Common victims include: posting PR comments with github-script, uploading artifacts to
+  releases, creating check runs, and updating commit statuses.
+fix: |
+  Use the pull_request_target event if the workflow must write to the base repo. Be aware
+  that pull_request_target checks out the base branch by default (not the PR head) and carries
+  security implications — never checkout and execute untrusted PR code with write-permission
+  tokens (see pwn request attacks). For safe comment posting, split into two workflows:
+  a read-only pull_request workflow that uploads results as an artifact, and a
+  pull_request_target or workflow_run workflow with write access that downloads the artifact
+  and posts the comment.
+fix_code:
+  - language: yaml
+    label: "Split pattern — upload results in pull_request, post comment in workflow_run"
+    code: |
+      # Workflow 1: pr-test.yml — runs on pull_request (fork-safe, read-only token)
+      on: pull_request
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - name: Run tests and save results
+              run: npm test > test-results.txt 2>&1 || true
+            - name: Upload PR number for downstream workflow
+              uses: actions/upload-artifact@v4
+              with:
+                name: pr-results
+                path: |
+                  test-results.txt
+  - language: yaml
+    label: "Workflow 2 — post comment using workflow_run (has write token)"
+    code: |
+      # Workflow 2: pr-comment.yml — runs after pr-test.yml completes (has write token)
+      on:
+        workflow_run:
+          workflows: ["PR Tests"]
+          types: [completed]
+
+      permissions:
+        pull-requests: write
+
+      jobs:
+        comment:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Download test results artifact
+              uses: actions/download-artifact@v4
+              with:
+                name: pr-results
+                run-id: ${{ github.event.workflow_run.id }}
+                github-token: ${{ secrets.GITHUB_TOKEN }}
+            - name: Post PR comment
+              uses: actions/github-script@v7
+              with:
+                script: |
+                  const fs = require('fs');
+                  const results = fs.readFileSync('test-results.txt', 'utf8');
+                  await github.rest.issues.createComment({
+                    owner: context.repo.owner,
+                    repo: context.repo.repo,
+                    issue_number: context.payload.workflow_run.pull_requests[0].number,
+                    body: '## Test Results\n```\n' + results + '\n```'
+                  });
+prevention:
+  - "Know that GITHUB_TOKEN is read-only for PR workflows from forks — this is a security feature, not a misconfiguration"
+  - "Never use pull_request_target to run PR head code with write-permission tokens — this creates a pwn request vulnerability"
+  - "Use the upload-artifact + workflow_run split pattern for safe cross-fork write operations"
+  - "Test workflows with a fork PR specifically if they perform write operations — the token scope difference won't appear in same-repo PRs"
+docs:
+  - url: https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#pull_request
+    label: "GitHub Docs: pull_request event — fork permission restrictions"
+  - url: https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication#permissions-for-the-github_token
+    label: "GitHub Docs: GITHUB_TOKEN permissions"
+  - url: https://securitylab.github.com/research/github-actions-preventing-pwn-requests/
+    label: "GitHub Security Lab: Preventing pwn requests (pull_request_target risks)"
+  - url: https://stackoverflow.com/questions/70435286/resource-not-accessible-by-integration-on-github-pull-request-event
+    label: "Stack Overflow: Resource not accessible by integration on pull_request"

package/errors/silent-failures/cache-hit-output-empty-string-not-false.yml

@@ -0,0 +1,87 @@
+id: silent-failures-063
+title: "actions/cache cache-hit output is empty string on miss, not 'false' — equality checks silently never match"
+category: silent-failures
+severity: silent-failure
+tags:
+  - actions-cache
+  - cache-hit
+  - output
+  - empty-string
+  - if-condition
+  - false-comparison
+patterns:
+  - regex: 'steps\.\w+\.outputs\.cache-hit\s*==\s*[''"]false[''"]'
+    flags: i
+  - regex: "cache-hit.*==.*'false'"
+    flags: i
+error_messages:
+  - "cache-hit output comparison to 'false' always evaluates to false — use != 'true' instead"
+root_cause: |
+  The actions/cache action sets the cache-hit output to the string 'true' when a cache is
+  restored from an exact key match, and to an empty string '' when the cache is not found
+  (including when restored from a restore-keys fallback, which returns '' for cache-hit in v3
+  and 'false' only in some v4 configurations). This means that
+  `if: steps.cache.outputs.cache-hit == 'false'` evaluates to false on a cache miss because
+  '' != 'false', so the step or job it guards is silently skipped.
+
+  This is one of the most upvoted GitHub Actions questions on Stack Overflow. Developers
+  naturally expect a boolean-like output to be 'true' or 'false', but the cache action uses
+  'true' vs '' (empty) semantics. The step appears to run successfully; nothing in the logs
+  indicates the if condition did not match as expected.
+fix: |
+  Check for cache miss using != 'true' instead of == 'false'. An empty string and 'false'
+  both evaluate to not-equal-to-'true', so this pattern correctly handles all cache miss
+  cases across cache action versions. Alternatively, use the boolean expression
+  `steps.cache.outputs.cache-hit != 'true'` or omit the check and rely on the cache action's
+  lookup-only: true parameter combined with a separate save step.
+fix_code:
+  - language: yaml
+    label: "Use != 'true' to reliably detect cache miss (works across all cache action versions)"
+    code: |
+      - name: Cache dependencies
+        id: cache-deps
+        uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+
+      # WRONG — silently never runs on cache miss:
+      # - name: Install deps
+      #   if: steps.cache-deps.outputs.cache-hit == 'false'
+
+      # CORRECT — matches both '' and 'false':
+      - name: Install dependencies
+        if: steps.cache-deps.outputs.cache-hit != 'true'
+        run: npm ci
+  - language: yaml
+    label: "Lookup-only + explicit save pattern (cache@v4) to avoid output ambiguity"
+    code: |
+      - name: Restore cache (lookup only, no auto-save)
+        id: cache-restore
+        uses: actions/cache/restore@v4
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+
+      - name: Install dependencies
+        if: steps.cache-restore.outputs.cache-hit != 'true'
+        run: npm ci
+
+      - name: Save cache
+        if: steps.cache-restore.outputs.cache-hit != 'true'
+        uses: actions/cache/save@v4
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+prevention:
+  - "Always use != 'true' to check for cache miss — never use == 'false' on cache action outputs"
+  - "Review the cache action version changelog: v3 uses '' on miss, v4 behavior depends on exact/partial hit"
+  - "Add a debug step that echoes cache-hit output to make cache behavior visible in logs during development"
+  - "Consult the cache action README for the exact semantics of cache-hit, cache-primary-key, and cache-matched-key"
+docs:
+  - url: https://github.com/actions/cache#outputs
+    label: "actions/cache README: Outputs"
+  - url: https://stackoverflow.com/questions/62754195/github-actions-cache-hit-is-true-but-id-expect-false
+    label: "Stack Overflow: cache-hit is empty string, not 'false'"
+  - url: https://github.com/actions/cache/issues/1699
+    label: "actions/cache#1699: cache-hit output '' vs 'false' confusion"

package/errors/triggers/push-paths-filter-no-effect-workflow-dispatch.yml

@@ -0,0 +1,81 @@
+id: triggers-045
+title: "on.push.paths filter has no effect on workflow_dispatch — manual trigger always runs regardless of changed files"
+category: triggers
+severity: silent-failure
+tags:
+  - workflow-dispatch
+  - push
+  - paths-filter
+  - triggers
+  - manual-trigger
+  - always-runs
+patterns:
+  - regex: 'workflow_dispatch'
+    flags: i
+error_messages:
+  - "Workflow ran unexpectedly when triggered via workflow_dispatch despite paths filter"
+root_cause: |
+  GitHub Actions evaluates on.push.paths (and on.push.paths-ignore) filters only for push
+  events. The filter is tied to the event type it is defined under. When workflow_dispatch is
+  added as a separate trigger, it has no paths context — there is no commit diff associated
+  with a manual dispatch. GitHub therefore runs the workflow unconditionally when dispatched.
+
+  This surprises developers who add workflow_dispatch: to an existing push-triggered workflow
+  for convenience and expect the paths filter to still gate the run. The workflow_dispatch
+  event has no paths or branches key at all; any such keys would be silently ignored if added.
+
+  A related confusion: paths filters on pull_request or push do not protect against
+  workflow_dispatch, so adding a workflow_dispatch trigger effectively creates an unfiltered
+  entry point into the workflow.
+fix: |
+  Accept that workflow_dispatch runs unconditionally — this is intentional GitHub behavior.
+  If you want to restrict what the dispatched workflow does based on inputs, use
+  workflow_dispatch inputs to pass a flag and gate steps with if: conditions. If the goal is
+  to limit accidental runs, remove workflow_dispatch from workflows where paths-gating is
+  critical, or add a required input that must be confirmed before proceeding.
+fix_code:
+  - language: yaml
+    label: "Separate push-only workflow (with paths filter) from a dispatch-friendly workflow"
+    code: |
+      # Option 1: keep push and dispatch as separate workflow files
+      # push-filtered.yml — only triggered on relevant path changes
+      on:
+        push:
+          paths:
+            - 'src/**'
+
+      # dispatch-build.yml — no paths filter needed; always intentional
+      on:
+        workflow_dispatch:
+  - language: yaml
+    label: "Use a workflow_dispatch input to require confirmation before running"
+    code: |
+      on:
+        push:
+          paths:
+            - 'src/**'
+        workflow_dispatch:
+          inputs:
+            confirm:
+              description: 'Type YES to run regardless of changed files'
+              required: true
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Proceed only if push triggered by path change OR dispatch confirmed
+              if: github.event_name == 'push' || inputs.confirm == 'YES'
+              run: echo "Running build"
+prevention:
+  - "Understand that paths/branches filters are per-event-type — workflow_dispatch has no file diff context"
+  - "Document in the workflow file that workflow_dispatch runs unconditionally to avoid future confusion"
+  - "Use workflow_dispatch inputs to gate critical steps when a manual trigger is added to a path-filtered workflow"
+  - "Review which workflows have both push.paths filters and workflow_dispatch before adding the dispatch trigger"
+docs:
+  - url: https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_dispatch
+    label: "GitHub Docs: workflow_dispatch event"
+  - url: https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/triggering-a-workflow#using-filters-to-target-specific-branches-or-tags-for-push-events
+    label: "GitHub Docs: Using filters to target specific paths"
+  - url: https://stackoverflow.com/questions/65900201/workflow-dispatch-ignores-paths-filter
+    label: "Stack Overflow: workflow_dispatch ignores paths filter"

package/package.json

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