@htekdev/actions-debugger 1.0.104 → 1.0.105

package/errors/caching-artifacts/cache-primary-key-prefix-matching-undocumented.yml

@@ -0,0 +1,104 @@
+id: caching-artifacts-060
+title: 'actions/cache Primary key Uses Undocumented Prefix Matching — Stale Cache Restored on Partial Hit'
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - cache
+  - actions/cache
+  - key
+  - prefix-match
+  - stale-cache
+  - cache-hit
+  - restore-keys
+patterns:
+  - regex: 'Cache restored from key:'
+    flags: 'i'
+  - regex: 'cache-hit.*true'
+    flags: 'i'
+  - regex: 'uses:\s*actions/cache@v[34]'
+    flags: 'i'
+error_messages:
+  - "Cache restored from key: npm-cache-linux"
+  - "cache-hit: true"
+  - "Restored cache from key"
+root_cause: |
+  GitHub Actions documentation states that `actions/cache`'s primary `key:`
+  parameter requires an **exact match** to trigger a cache hit. In practice,
+  the cache service backend uses **prefix matching** for primary keys, identical
+  to how `restore-keys:` works. This undocumented behavior was confirmed by the
+  GitHub Actions team in actions/cache#1433:
+
+  > "I've checked the internal service implementation and it appears that our
+  > documentation is incorrect. `key` uses prefix-matching similar to how
+  > `restore-keys` works."
+
+  **What this means in practice:**
+  - If an existing cached entry has key `npm-cache-linux` and the current run
+    uses key `npm-cache-linux-abc123`, the primary `key` lookup returns a hit on
+    `npm-cache-linux` (the existing key is a prefix of the requested key).
+  - The cache is restored silently with `cache-hit: true`, even though the
+    actual content may be outdated or from a completely different run.
+  - Downstream jobs that check `cache-hit == 'true'` to skip install steps will
+    skip them, causing builds to use stale dependencies.
+
+  This is especially problematic when:
+  1. A broad, short key (e.g., `linux-npm`) was saved long ago and a new, more
+     specific key (e.g., `linux-npm-${{ hashFiles('package-lock.json') }}`)
+     happens to have the old key as a prefix.
+  2. CI changes add a version suffix to cache keys, but old caches from before
+     the change are still present and match as prefixes.
+fix: |
+  **Option 1 (recommended): Use unique, non-colliding key prefixes**
+  Design your cache key so that no broader key from a previous run can be a prefix
+  of your current key. Include the hash of lock files or use a version token that
+  changes with major dependency updates.
+
+  **Option 2: Rotate keys by appending a version token**
+  Prefix with a cache version that you bump whenever you want to guarantee a cold
+  start, preventing old keys from matching.
+
+  **Option 3: Use `restore-keys:` intentionally**
+  If you want prefix fallback, make it explicit with `restore-keys:` and verify
+  what you're getting. Check `cache-hit` output and run install even on partial
+  hits when correctness matters.
+
+  **Option 4: Delete stale caches via API**
+  Use `gh extension install actions/gh-actions-cache` or the REST API to delete
+  old broad-key caches that would match as prefixes, preventing unexpected hits.
+fix_code:
+  - language: yaml
+    label: 'Use versioned prefix to prevent stale prefix matches'
+    code: |
+      - uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          # v2 prefix ensures old "v1" caches never match as prefixes
+          key: v2-npm-${{ runner.os }}-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: |
+            v2-npm-${{ runner.os }}-
+  - language: yaml
+    label: 'Re-install deps on partial cache hit to avoid stale cache'
+    code: |
+      - uses: actions/cache@v4
+        id: npm-cache
+        with:
+          path: ~/.npm
+          key: npm-${{ runner.os }}-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: npm-${{ runner.os }}-
+
+      - name: Install dependencies
+        # Always install when not an exact hit to avoid stale partial cache
+        if: steps.npm-cache.outputs.cache-hit != 'true'
+        run: npm ci
+prevention:
+  - 'Always include a lockfile hash in cache keys: `key: npm-${{ runner.os }}-${{ hashFiles(''**/package-lock.json'') }}`'
+  - 'Prefix cache keys with a version token (e.g., `v1-`, `v2-`) so you can easily invalidate all old caches by bumping the version.'
+  - 'Do not rely solely on `cache-hit == true` to skip install steps; consider re-running `npm install --prefer-offline` even on hits to handle partial prefix matches.'
+  - 'Periodically audit and delete stale cache entries via the GitHub REST API or `gh actions-cache` extension.'
+docs:
+  - url: 'https://github.com/actions/cache/issues/1433'
+    label: 'actions/cache#1433: Cache key uses prefix matching — documentation is incorrect'
+  - url: 'https://github.com/actions/cache/issues/1385'
+    label: 'actions/cache#1385: Unexpected cache hit from prefix match'
+  - url: 'https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows'
+    label: 'GitHub Docs: Caching dependencies to speed up workflows'

package/errors/concurrency-timing/batch-workflow-dispatch-static-concurrency-silent-cancel.yml

@@ -0,0 +1,137 @@
+id: concurrency-timing-049
+title: 'Batch workflow_dispatch Runs Silently Cancel Each Other via Static Concurrency Group'
+category: concurrency-timing
+severity: silent-failure
+tags:
+  - concurrency
+  - workflow-dispatch
+  - batch
+  - cancel
+  - static-group
+  - lost-run
+  - dispatch-api
+patterns:
+  - regex: 'This run was cancelled'
+    flags: 'i'
+  - regex: 'concurrency:\s*\n\s*group:\s*[''"]?\$\{\{\s*github\.workflow\s*\}\}'
+    flags: 'im'
+  - regex: 'workflow_dispatch.*concurrency|concurrency.*workflow_dispatch'
+    flags: 'ims'
+error_messages:
+  - "This run was cancelled."
+  - "Run has been cancelled because it is in a concurrency group with a newer run."
+  - "Canceling since a more recent run was started"
+root_cause: |
+  When a workflow uses a **static concurrency group** — one that does not
+  incorporate any per-run unique value like `github.run_id` or a user-supplied
+  input — and multiple `workflow_dispatch` runs are triggered in rapid succession
+  (e.g., from a batch API script, a label webhook fan-out, or automation), GitHub
+  Actions cancels all but the last run.
+
+  GitHub Actions enforces a limit of **1 running + 1 pending** run per concurrency
+  group. Each new dispatch replaces the existing pending run:
+
+  1. Run A starts → becomes "running"
+  2. Run B dispatched → becomes "pending" (waits for A)
+  3. Run C dispatched → **cancels Run B** (B was pending), C becomes "pending"
+  4. Run D dispatched → **cancels Run C**, D becomes "pending"
+  5. Only Run D eventually runs after Run A finishes.
+
+  This produces silent data loss when each dispatch carries different `inputs:`
+  (e.g., different artifact IDs, tenant IDs, or tags to process). All runs except
+  the last are silently discarded with "This run was cancelled."
+
+  Commonly triggered by:
+  - A webhook handler that dispatches one workflow run per event, with bursts of
+    events arriving simultaneously.
+  - Automation scripts that loop over a list and call `gh workflow run` for each item.
+  - A cron job that fans out to per-repo dispatches sharing the same workflow name.
+
+  Note: this is distinct from `concurrency-timing-040` (push + workflow_dispatch
+  sharing a group) — this issue occurs with ONLY workflow_dispatch runs sharing a
+  static group with no event-name differentiation.
+fix: |
+  **Option 1 (recommended): Include a unique input value in the concurrency group**
+  If each dispatch has a unique identifier as an input (e.g., a tenant ID, artifact
+  ID, or item key), include it in the concurrency group so different dispatches
+  get independent groups.
+
+  **Option 2: Include github.run_id in the concurrency group**
+  Using `github.run_id` makes every run its own concurrency group — effectively
+  disabling concurrency entirely. Use only if all runs are important and must
+  complete.
+
+  **Option 3: Use cancel-in-progress: false (no-queue mode)**
+  With `cancel-in-progress: false`, new pending runs do not cancel existing pending
+  ones. The 1-running + 1-pending limit still applies, but the *last* queued run
+  (not the most recent dispatch) survives. This still means high-burst dispatches
+  lose most runs.
+
+  **Option 4: Use a queue-based architecture**
+  For high-volume fan-out, avoid workflow_dispatch entirely. Instead, push items to
+  a queue (SQS, GitHub Issues, database) and have a single polling workflow process
+  items from the queue sequentially or in bounded parallel batches.
+fix_code:
+  - language: yaml
+    label: 'Include unique input in concurrency group to isolate per-dispatch runs'
+    code: |
+      on:
+        workflow_dispatch:
+          inputs:
+            item_id:
+              description: 'Unique identifier for this dispatch'
+              required: true
+              type: string
+
+      concurrency:
+        # Each unique item_id gets its own concurrency slot — no cross-dispatch cancellation
+        group: ${{ github.workflow }}-${{ inputs.item_id }}
+        cancel-in-progress: true
+  - language: yaml
+    label: 'Use github.run_id to guarantee all dispatches run independently'
+    code: |
+      on:
+        workflow_dispatch:
+
+      concurrency:
+        # Every run is its own group — effectively disables concurrency queueing
+        group: ${{ github.workflow }}-${{ github.run_id }}
+        cancel-in-progress: false
+  - language: yaml
+    label: 'Fan-out batch dispatch via matrix instead of separate workflow runs'
+    code: |
+      # Instead of dispatching N separate workflow runs (which cancel each other),
+      # dispatch ONE run with a matrix input to process all items in parallel.
+      on:
+        workflow_dispatch:
+          inputs:
+            item_ids:
+              description: 'JSON array of item IDs to process'
+              required: true
+              type: string
+
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.ref }}
+        cancel-in-progress: false
+
+      jobs:
+        process-items:
+          strategy:
+            matrix:
+              item_id: ${{ fromJSON(inputs.item_ids) }}
+          runs-on: ubuntu-latest
+          steps:
+            - name: Process item
+              run: echo "Processing ${{ matrix.item_id }}"
+prevention:
+  - 'Never use a static concurrency group (e.g., `group: ${{ github.workflow }}`) for workflows dispatched in batch — include a unique per-dispatch key.'
+  - 'When dispatching multiple runs from a script, add a unique ID as an input and include it in the concurrency group.'
+  - 'For high-volume fan-out workloads, use a single matrix job instead of N separate workflow_dispatch runs.'
+  - 'Monitor workflow cancellation counts in the Actions UI — unexpected "This run was cancelled" on dispatch events signals a concurrency group collision.'
+docs:
+  - url: 'https://github.com/github/gh-aw/issues/19467'
+    label: 'github/gh-aw#19467: Batch workflow_dispatch runs cancel each other via static concurrency group'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-concurrency'
+    label: 'GitHub Docs: Using concurrency — 1 running + 1 pending limit per group'
+  - url: 'https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/manually-running-a-workflow'
+    label: 'GitHub Docs: Manually running a workflow'

package/errors/runner-environment/sparse-checkout-persists-self-hosted-cross-run.yml

@@ -0,0 +1,99 @@
+id: runner-environment-174
+title: 'Sparse Checkout Config Persists Across Workflow Runs on Self-Hosted Runners'
+category: runner-environment
+severity: silent-failure
+tags:
+  - sparse-checkout
+  - self-hosted
+  - git-config
+  - workspace-reuse
+  - checkout
+  - non-ephemeral
+patterns:
+  - regex: 'core\.sparseCheckout\s*=\s*true'
+    flags: 'i'
+  - regex: 'sparse.checkout.*persist|persist.*sparse.checkout'
+    flags: 'i'
+  - regex: 'git sparse-checkout disable'
+    flags: 'i'
+error_messages:
+  - "Run actions/checkout@v4"
+  - "Checkout was successful but expected files are missing from working directory"
+  - "sparse-checkout: /run/git/config: sparseCheckout = true"
+root_cause: |
+  On non-ephemeral self-hosted runners, the workspace directory (e.g.
+  `/home/runner/work/my-repo/my-repo`) is reused across multiple workflow runs
+  on the same runner machine. When `actions/checkout` runs with `sparse-checkout:`
+  options, it sets `core.sparseCheckout = true` in the repository's `.git/config`
+  file.
+
+  In older versions of `actions/checkout` (before the fix in commit aadec89,
+  merged ~2025), the `disableSparseCheckout()` method reset `core.sparseCheckout`
+  only in `.git/config.worktree` (used in git worktrees), but NOT in the main
+  `.git/config`. As a result:
+
+  - **Workflow run N** uses `sparse-checkout:` → sets `core.sparseCheckout = true`
+    in `.git/config`.
+  - **Workflow run N+1** on the same runner does NOT use `sparse-checkout:`, but
+    inherits the stale `core.sparseCheckout = true` setting from the reused workspace.
+  - `actions/checkout` reports success, but the working directory contains only
+    the files that matched the previous run's sparse-checkout patterns. All other
+    files silently absent.
+
+  This is distinct from the same-job sticky cone mode issue (sf-008), which covers
+  two `actions/checkout` calls within a single job sharing sparse state. This issue
+  manifests across entirely separate workflow runs on a shared workspace.
+
+  Confirmed in actions/checkout#2249 (published Aug 2025) and actions/checkout#1992.
+fix: |
+  **Option 1 (recommended): Upgrade to actions/checkout v4.2.0+**
+  The bug was fixed in commit aadec89. Pinning to a patched release ensures
+  `disableSparseCheckout()` explicitly sets `core.sparseCheckout = false` in
+  `.git/config` when no `sparse-checkout:` input is provided.
+
+  **Option 2: Add an explicit `git sparse-checkout disable` step**
+  Add this step at the beginning of workflows that do NOT use sparse-checkout
+  on a runner that may previously have run sparse-checkout workflows:
+
+  **Option 3: Use ephemeral self-hosted runners**
+  Configure runners so each job gets a fresh workspace (e.g., ARC ephemeral mode,
+  EC2 runners with fresh AMIs). Ephemeral runners eliminate all cross-run workspace
+  contamination.
+
+  **Option 4: Configure runner to clean workspace between runs**
+  Set `ACTIONS_RUNNER_CLEAN_WORKSPACE=true` in the runner environment (where
+  supported) to force workspace cleanup between job runs.
+fix_code:
+  - language: yaml
+    label: 'Upgrade to patched actions/checkout version'
+    code: |
+      steps:
+        - uses: actions/checkout@v4  # Use v4.2.0+ for the sparse-checkout fix
+          # No sparse-checkout options — will correctly restore full tree
+  - language: yaml
+    label: 'Explicit sparse-checkout reset before checkout on shared runners'
+    code: |
+      steps:
+        - name: Reset sparse-checkout (safety guard for shared self-hosted runners)
+          shell: bash
+          run: |
+            if git -C "${{ github.workspace }}" rev-parse --git-dir > /dev/null 2>&1; then
+              git -C "${{ github.workspace }}" sparse-checkout disable 2>/dev/null || true
+              git -C "${{ github.workspace }}" config --unset core.sparseCheckout 2>/dev/null || true
+            fi
+
+        - uses: actions/checkout@v4
+prevention:
+  - 'On self-hosted runners, always pin `actions/checkout` to v4.2.0+ which fixes the sparse-checkout persistence bug.'
+  - 'Add a `git sparse-checkout disable` guard step at the start of any workflow that runs on a non-ephemeral self-hosted runner.'
+  - 'Use ephemeral runners (fresh environment per job) to eliminate all cross-run workspace contamination.'
+  - 'Do not mix sparse-checkout and full-checkout workflows on the same non-ephemeral runner without resetting `.git/config` between runs.'
+docs:
+  - url: 'https://github.com/actions/checkout/issues/2249'
+    label: 'actions/checkout#2249: Sparse-checkout configuration persists across workflows on self-hosted runners'
+  - url: 'https://github.com/actions/checkout/issues/1992'
+    label: 'actions/checkout#1992: Sparscheckout breaks cached repository on self-hosted runners'
+  - url: 'https://github.com/actions/checkout/commit/aadec899646c8e0f34c52d9219c2faac36626b55'
+    label: 'Fix commit aadec89: Explicitly disable sparseCheckout in .git/config when not using sparse-checkout'
+  - url: 'https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners'
+    label: 'GitHub Docs: About GitHub-hosted runners (ephemeral vs self-hosted)'

package/errors/yaml-syntax/hashfiles-newline-delimiter-returns-empty.yml

@@ -0,0 +1,99 @@
+id: yaml-syntax-066
+title: 'hashFiles() Newline Delimiter in Single String Returns Empty — Use Multiple Arguments'
+category: yaml-syntax
+severity: silent-failure
+tags:
+  - hashfiles
+  - expression
+  - cache-key
+  - empty-string
+  - multifile
+  - glob
+  - newline-delimiter
+patterns:
+  - regex: 'hashFiles\([''"].*\\n.*[''"]'
+    flags: 'i'
+  - regex: 'hashFiles\s*\(\s*[''"][^''",]+\\n[^''",]+[''"]'
+    flags: 'i'
+error_messages:
+  - "${{ hashFiles('src/**\npackage.json') }}"
+  - "${{ hashFiles('**/*.lock\n**/*.toml') }}"
+  - "hashFiles result: ''"
+root_cause: |
+  The `@actions/glob` internal implementation documents that file patterns can be
+  separated by newline (`\n`) characters when passed as a single string. This causes
+  developers to write `hashFiles('file.ts\nfile.tsx')` expecting it to hash both
+  files.
+
+  However, inside a GitHub Actions expression (`${{ ... }}`), string literals do
+  NOT interpret escape sequences. The `\n` in `'file.ts\nfile.tsx'` is a literal
+  two-character sequence: backslash + "n". The glob function then looks for a file
+  literally named `file.ts\nfile.tsx` — which does not exist — and returns an empty
+  string `''`.
+
+  **Result:**
+  - `cache-key: ${{ hashFiles('package.json\nyarn.lock') }}` → cache key ends with
+    an empty string, causing ALL runs to collide on the same constant prefix key.
+  - `if: hashFiles('src/**\ntest/**') != ''` → always false (no hash returned), so
+    cache/condition logic silently skips.
+  - No error is raised; the expression just evaluates to `''` silently.
+
+  Confirmed in actions/runner#3467 and actions/runner#4049.
+
+  Note: `hashFiles()` DOES accept multiple comma-separated string arguments, and
+  each argument is a full glob pattern. The variadic call form works correctly.
+fix: |
+  Use multiple comma-separated arguments to `hashFiles()` instead of a
+  newline-delimited single string.
+
+  `hashFiles('pattern1', 'pattern2', ...)` correctly hashes all files matching
+  any of the provided glob patterns.
+
+  If you are building a dynamic list of patterns from a context value or step
+  output, write the patterns to a file and hash that file, or hash each pattern
+  in separate expressions and combine.
+fix_code:
+  - language: yaml
+    label: 'Use multiple arguments (correct) instead of newline-delimited string (broken)'
+    code: |
+      # BROKEN — \n is a literal backslash-n, not a newline; returns empty string
+      # key: npm-${{ hashFiles('package.json\npackage-lock.json') }}
+
+      # CORRECT — comma-separated arguments, hashes both files
+      - uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          key: npm-${{ runner.os }}-${{ hashFiles('package.json', 'package-lock.json') }}
+  - language: yaml
+    label: 'Multiple lock files hashed with variadic hashFiles()'
+    code: |
+      - uses: actions/cache@v4
+        with:
+          path: |
+            ~/.npm
+            ~/.cache/pip
+          key: multi-${{ runner.os }}-${{ hashFiles('**/package-lock.json', '**/requirements*.txt', '**/Pipfile.lock') }}
+          restore-keys: |
+            multi-${{ runner.os }}-
+  - language: yaml
+    label: 'Conditional step using hashFiles() with multiple arguments'
+    code: |
+      # BROKEN — always evaluates to '' because \n is not a newline escape
+      # if: ${{ hashFiles('src/**\ntest/**') != '' }}
+
+      # CORRECT
+      - name: Check if source files changed
+        if: ${{ hashFiles('src/**', 'test/**') != '' }}
+        run: echo "Source files found"
+prevention:
+  - 'Never use `\n` as a pattern delimiter inside a `hashFiles()` call in a workflow expression — it is a literal backslash-n, not a newline.'
+  - 'Use multiple comma-separated arguments: `hashFiles(''pattern1'', ''pattern2'')` to hash files from multiple glob patterns.'
+  - 'When a `hashFiles()` result is used as a cache key suffix, validate it is non-empty by running the workflow once and checking the logged cache key.'
+  - 'If you suspect an empty hash, add a debug step: `run: echo "hash=${{ hashFiles(''**/*.lock'') }}"` to verify the value before using it in a key.'
+docs:
+  - url: 'https://github.com/actions/runner/issues/3467'
+    label: 'actions/runner#3467: hashFiles does not follow docs — newline delimiter in string returns empty'
+  - url: 'https://github.com/actions/runner/issues/4049'
+    label: 'actions/runner#4049: hashFiles newline pattern delimiter not interpreted in expressions'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/evaluate-expressions-in-workflows-and-actions#hashfiles'
+    label: 'GitHub Docs: hashFiles function — variadic arguments'

package/package.json

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