@htekdev/actions-debugger 1.0.13 → 1.0.15

package/dist/db/search.js

@@ -112,9 +112,11 @@ function matchEntry(entry, input) {
         }
     }
     // 3. Title keyword matching (lowest confidence)
+    // Require words > 5 chars to avoid false positives from common short words
+    // (e.g. "text", "that", "some", "runs", "jobs" appearing in unrelated inputs)
     const inputLower = input.toLowerCase();
     const titleWords = entry.title.toLowerCase().split(/\s+/);
-    const matchingWords = titleWords.filter(w => w.length > 3 && inputLower.includes(w));
+    const matchingWords = titleWords.filter(w => w.length > 5 && inputLower.includes(w));
     if (matchingWords.length >= 2) {
         bestScore = Math.max(bestScore, 20 + matchingWords.length * 5);
     }

package/dist/db/search.js.map

@@ -1 +1 @@
-{"version":3,"file":"search.js","sourceRoot":"","sources":["../../src/db/search.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"search.js","sourceRoot":"","sources":["../../src/db/search.ts"],"names":[],"mappings":"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"}

package/dist/tools/suggest-fix.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"suggest-fix.d.ts","sourceRoot":"","sources":["../../src/tools/suggest-fix.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAGhE;;GAEG;AACH,wBAAgB,UAAU,CACxB,EAAE,EAAE,aAAa,EACjB,YAAY,EAAE,MAAM,EACpB,QAAQ,CAAC,EAAE,MAAM,GAChB,UAAU,EAAE,CAUd;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,MAAM,CA8CjE"}
+{"version":3,"file":"suggest-fix.d.ts","sourceRoot":"","sources":["../../src/tools/suggest-fix.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAGhE;;GAEG;AACH,wBAAgB,UAAU,CACxB,EAAE,EAAE,aAAa,EACjB,YAAY,EAAE,MAAM,EACpB,QAAQ,CAAC,EAAE,MAAM,GAChB,UAAU,EAAE,CAed;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,MAAM,CA8CjE"}

package/dist/tools/suggest-fix.js

@@ -8,7 +8,11 @@ import { lookupByPattern, searchByKeyword } from "../db/search.js";
 export function suggestFix(db, errorContext, category) {
     // Try regex matching first
     let results = lookupByPattern(db, errorContext, 5);
-    // If no regex matches, try keyword search
+    // Apply category filter if provided (pattern matching doesn't filter by category)
+    if (category) {
+        results = results.filter(r => r.entry.category === category);
+    }
+    // If no matches after filtering, fall back to keyword search with category filter
     if (results.length === 0) {
         results = searchByKeyword(db, errorContext, { category, maxResults: 5 });
     }

package/dist/tools/suggest-fix.js.map

@@ -1 +1 @@
-{"version":3,"file":"suggest-fix.js","sourceRoot":"","sources":["../../src/tools/suggest-fix.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEnE;;GAEG;AACH,MAAM,UAAU,UAAU,CACxB,EAAiB,EACjB,YAAoB,EACpB,QAAiB;IAEjB,2BAA2B;IAC3B,IAAI,OAAO,GAAG,eAAe,CAAC,EAAE,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC;IAEnD,0CAA0C;IAC1C,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,GAAG,eAAe,CAAC,EAAE,EAAE,YAAY,EAAE,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC,EAAE,CAAC,CAAC;IAC3E,CAAC;IAED,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;AACnC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAqB;IACvD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO;YACL,4CAA4C;YAC5C,EAAE;YACF,UAAU;YACV,2DAA2D;YAC3D,+DAA+D;YAC/D,mFAAmF;SACpF,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACf,CAAC;IAED,MAAM,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACxB,MAAM,KAAK,GAAG;QACZ,qBAAqB,IAAI,CAAC,KAAK,EAAE;QACjC,EAAE;QACF,iBAAiB,IAAI,CAAC,QAAQ,oBAAoB,IAAI,CAAC,QAAQ,EAAE;QACjE,EAAE;QACF,iBAAiB;QACjB,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE;QACtB,EAAE;QACF,UAAU;QACV,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE;KAChB,CAAC;IAEF,IAAI,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAC;QAC1B,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,MAAM,EAAE,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC/B,KAAK,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,QAAQ,EAAE,CAAC,CAAC;YACnC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;YAC3B,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACpB,CAAC;IACH,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,6BAA6B,CAAC,CAAC;QAC9C,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;YACrC,KAAK,CAAC,IAAI,CAAC,KAAK,KAAK,CAAC,KAAK,KAAK,KAAK,CAAC,QAAQ,GAAG,CAAC,CAAC;QACrD,CAAC;IACH,CAAC;IAED,IAAI,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;QACzB,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,4BAA4B,IAAI,CAAC,MAAM,CAAC,OAAO,GAAG,CAAC,CAAC;IACrE,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}
+{"version":3,"file":"suggest-fix.js","sourceRoot":"","sources":["../../src/tools/suggest-fix.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEnE;;GAEG;AACH,MAAM,UAAU,UAAU,CACxB,EAAiB,EACjB,YAAoB,EACpB,QAAiB;IAEjB,2BAA2B;IAC3B,IAAI,OAAO,GAAG,eAAe,CAAC,EAAE,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC;IAEnD,kFAAkF;IAClF,IAAI,QAAQ,EAAE,CAAC;QACb,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC;IAC/D,CAAC;IAED,kFAAkF;IAClF,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,GAAG,eAAe,CAAC,EAAE,EAAE,YAAY,EAAE,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC,EAAE,CAAC,CAAC;IAC3E,CAAC;IAED,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;AACnC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAqB;IACvD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO;YACL,4CAA4C;YAC5C,EAAE;YACF,UAAU;YACV,2DAA2D;YAC3D,+DAA+D;YAC/D,mFAAmF;SACpF,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACf,CAAC;IAED,MAAM,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACxB,MAAM,KAAK,GAAG;QACZ,qBAAqB,IAAI,CAAC,KAAK,EAAE;QACjC,EAAE;QACF,iBAAiB,IAAI,CAAC,QAAQ,oBAAoB,IAAI,CAAC,QAAQ,EAAE;QACjE,EAAE;QACF,iBAAiB;QACjB,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE;QACtB,EAAE;QACF,UAAU;QACV,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE;KAChB,CAAC;IAEF,IAAI,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAC;QAC1B,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,MAAM,EAAE,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC/B,KAAK,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,QAAQ,EAAE,CAAC,CAAC;YACnC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;YAC3B,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACpB,CAAC;IACH,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,6BAA6B,CAAC,CAAC;QAC9C,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;YACrC,KAAK,CAAC,IAAI,CAAC,KAAK,KAAK,CAAC,KAAK,KAAK,KAAK,CAAC,QAAQ,GAAG,CAAC,CAAC;QACrD,CAAC;IACH,CAAC;IAED,IAAI,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;QACzB,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,4BAA4B,IAAI,CAAC,MAAM,CAAC,OAAO,GAAG,CAAC,CAAC;IACrE,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}

package/errors/caching-artifacts/cache-key-too-long.yml

@@ -0,0 +1,93 @@
+id: caching-artifacts-015
+title: "actions/cache Key Exceeds 512-Character Limit — Cache Action Fails"
+category: caching-artifacts
+severity: error
+tags:
+  - actions/cache
+  - cache-key
+  - key-length
+  - 512-char
+  - restore
+  - save
+patterns:
+  - regex: "Cache key is too long"
+    flags: "i"
+  - regex: "cache.*key.*exceed|key.*too long"
+    flags: "i"
+error_messages:
+  - "Cache key is too long"
+  - "Error: Cache key is too long (max: 512 characters)"
+root_cause: |
+  The `actions/cache` action enforces a maximum cache key length of **512 characters**.
+  When the `key:` or any `restore-keys:` entry exceeds this limit, the action fails
+  immediately with "Cache key is too long" — no cache is saved or restored.
+
+  This limit is hit most often when developers concatenate multiple dynamic values into
+  a single key without length management:
+  - Long branch names (`github.ref_name` on feature branches can be 60+ chars)
+  - Full commit SHAs (`github.sha` = 40 chars)
+  - `github.event_name` + `github.actor` + `github.run_id` (11+ chars) combined with a
+    long dependency hash
+  - `toJSON()` output of a context object embedded directly into the key
+  - Monorepo setups that include multiple file paths in a single hashFiles() call with
+    deeply nested directory structures
+
+  The 512-character limit applies per key entry, including each `restore-keys` line.
+  Keys that would cause the action to fail entirely, leaving the job without any cache.
+
+  Source: GitHub Docs — actions/cache usage limits
+fix: |
+  Shorten the cache key to stay under 512 characters. The primary strategies are:
+
+  1. **Use `hashFiles()` for dependency content** — hashing a lockfile produces a
+     consistent 64-character SHA256 output regardless of the file's contents.
+  2. **Remove redundant dynamic parts** — `github.run_id` is almost never appropriate
+     in a cache key (it changes every run, defeating cache sharing entirely).
+  3. **Truncate long branch names** — use `github.ref_name` only if needed, or hash it.
+  4. **Avoid embedding JSON strings** — never embed `toJSON()` outputs directly in keys.
+  5. **Use `restore-keys` for partial matching** instead of encoding multiple variants
+     into one long key.
+fix_code:
+  - language: yaml
+    label: "Broken — key too long from excessive concatenation"
+    code: |
+      # ❌ BROKEN: Key may exceed 512 chars with long branch names + run context
+      - uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-${{ github.workflow }}-${{ github.ref }}-${{ github.sha }}-${{ github.run_id }}-${{ hashFiles('**/package-lock.json', '**/yarn.lock', '**/pnpm-lock.yaml', 'packages/*/package-lock.json') }}
+  - language: yaml
+    label: "Fixed — concise key using OS + short context + lockfile hash"
+    code: |
+      # ✅ FIXED: OS prefix + workflow + lockfile hash — short and deterministic
+      - uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-npm-
+  - language: yaml
+    label: "Fixed — long branch names: hash github.ref_name if needed"
+    code: |
+      # ✅ FIXED: When you need branch-scoped caches, hash the ref instead of embedding it
+      - name: Compute short ref hash
+        id: ref-hash
+        run: echo "value=$(echo '${{ github.ref }}' | sha256sum | cut -c1-16)" >> $GITHUB_OUTPUT
+
+      - uses: actions/cache@v4
+        with:
+          path: .build-cache
+          key: build-${{ runner.os }}-${{ steps.ref-hash.outputs.value }}-${{ hashFiles('**/go.sum') }}
+          restore-keys: |
+            build-${{ runner.os }}-
+prevention:
+  - "Keep cache keys under 400 characters to leave comfortable headroom below the 512-char limit."
+  - "Never include `github.run_id` or `github.run_number` in cache keys — these values change every run and prevent cache hits entirely."
+  - "Prefer `hashFiles()` over embedding actual file content or long path lists into keys — the hash output is always 64 chars."
+  - "When branch-scoped caching is needed, hash `github.ref` to a short prefix rather than embedding the full ref string."
+  - "Test key length in a debug step: `run: echo \"Key length: $(echo -n '${{ KEY_EXPRESSION }}' | wc -c)\"`"
+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: "GitHub Docs: Cache restrictions and usage limits (512-char key limit)"
+  - url: "https://github.com/actions/cache#inputs"
+    label: "actions/cache inputs — key and restore-keys documentation"

package/errors/caching-artifacts/cache-path-not-exist-skipped.yml

@@ -0,0 +1,152 @@
+id: caching-artifacts-017
+title: "actions/cache Path Validation Error — Specified Path Does Not Exist, Cache Skipped"
+category: caching-artifacts
+severity: warning
+tags:
+  - cache
+  - path
+  - path-validation
+  - cache-miss
+  - warning
+  - actions-cache
+patterns:
+  - regex: "Path Validation Error.*Path.*specified.*action.*caching.*do.*not exist"
+    flags: "i"
+  - regex: "Warning.*Path.*caching.*do.*not exist.*no cache.*saved"
+    flags: "i"
+  - regex: "no cache.*being saved.*path.*not exist"
+    flags: "i"
+error_messages:
+  - "Warning: Path Validation Error: Path(s) specified in the action for caching do(es) not exist, hence no cache is being saved."
+root_cause: |
+  `actions/cache` validates that all paths listed under the `path:` key actually
+  exist on disk **at the time the `Post cache` step runs** (the post-job cleanup
+  step that performs the cache save). If any path does not exist, the action logs a
+  warning and **silently skips the cache save entirely** — no cache entry is written
+  even if other listed paths do exist.
+
+  **Common causes:**
+
+  1. **Conditional install step** — the path is only created when a specific install
+     step runs (e.g., `npm ci` or `pip install`), but the cache step's `key` matched
+     a previous cache, so the install step was skipped. The path therefore doesn't
+     exist when the post step runs.
+
+  2. **Wrong working directory** — the `path:` is relative (e.g., `node_modules`)
+     but the working directory for the run step differs from where `actions/cache`
+     expects to find it.
+
+  3. **Build output cached too early** — the `path:` references build output that
+     hasn't been generated yet (e.g., caching `dist/` before the build step runs).
+
+  4. **Typo in path** — a simple typo (e.g., `node-modules` vs `node_modules`) means
+     the directory is never created under that name.
+
+  5. **Cross-OS path format** — Windows backslash vs Linux forward slash mismatch
+     when the same workflow runs on multiple OS targets.
+
+  The action exits 0 (no failure), making this a **silent failure** — the workflow
+  appears to succeed, but the cache is never saved. Subsequent runs always experience
+  a full cache miss, causing slower CI without any visible error.
+
+  Source: mkdocs-material issue#7990, actions/cache documentation
+fix: |
+  1. **Verify the path exists before relying on it** — add a diagnostic step that
+     lists the directory structure before the cache save to confirm paths are present.
+
+  2. **Always run the install step** — do not skip install steps based on
+     `cache-hit == 'true'`. Instead, use `cache-hit` to skip the install when the
+     restore succeeded, but still let the cache post step validate paths:
+
+     ```yaml
+     - uses: actions/cache@v4
+       id: cache-node
+       with:
+         path: node_modules
+         key: ${{ runner.os }}-node-${{ hashFiles('package-lock.json') }}
+
+     - run: npm ci
+       if: steps.cache-node.outputs.cache-hit != 'true'
+     ```
+
+  3. **Use `setup-node` with caching** — instead of managing cache manually,
+     `actions/setup-node` with `cache: 'npm'` handles path validation internally.
+
+  4. **Check for path typos** — confirm the literal path string matches exactly
+     what is created on disk (case-sensitive on Linux).
+fix_code:
+  - language: yaml
+    label: "Correct pattern — run install only on cache miss, cache path always present"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - uses: actions/cache@v4
+              id: npm-cache
+              with:
+                path: ~/.npm        # Cache the npm cache dir — always exists
+                key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
+                restore-keys: |
+                  ${{ runner.os }}-npm-
+
+            # Always run npm ci so node_modules always exists for the cache post step
+            - run: npm ci
+
+            # ❌ Wrong — skipping npm ci on cache hit means node_modules may not exist
+            # - run: npm ci
+            #   if: steps.npm-cache.outputs.cache-hit != 'true'
+  - language: yaml
+    label: "Use setup-node built-in cache instead of manual actions/cache"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            # setup-node handles path validation and cache lifecycle correctly
+            - uses: actions/setup-node@v4
+              with:
+                node-version: '20'
+                cache: 'npm'   # Manages npm cache path validation internally
+
+            - run: npm ci
+  - language: yaml
+    label: "Debug step — print path existence before cache save"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - uses: actions/cache@v4
+              with:
+                path: |
+                  ~/.cache/pip
+                  .venv
+                key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt') }}
+
+            - run: pip install -r requirements.txt --target .venv
+
+            # Diagnostic — verify paths exist before cache post step runs
+            - name: Verify cache paths
+              run: |
+                echo "~/.cache/pip exists: $(test -d ~/.cache/pip && echo YES || echo NO)"
+                echo ".venv exists: $(test -d .venv && echo YES || echo NO)"
+prevention:
+  - "Always ensure every path listed under `actions/cache path:` is unconditionally created during the job — do not gate install steps on cache-hit in a way that leaves paths missing."
+  - "Prefer `setup-*` actions with their built-in `cache:` input over raw `actions/cache` — they manage path validation and lifecycle correctly."
+  - "Add a diagnostic step after your install/build steps to verify that each cached path exists before relying on the cache post step."
+  - "Use absolute paths (e.g., `~/.npm`, `~/.cache/pip`) rather than relative paths when caching language package caches."
+  - "Enable `ACTIONS_RUNNER_DEBUG: true` in repository secrets to get verbose cache-step output that reveals path validation details."
+docs:
+  - url: "https://github.com/actions/cache/blob/main/README.md"
+    label: "actions/cache README — path and key documentation"
+  - 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 to speed up workflows"
+  - url: "https://github.com/squidfunk/mkdocs-material/issues/7990"
+    label: "mkdocs-material#7990 — Path Validation Error real-world example"

package/errors/caching-artifacts/docker-buildx-gha-cache-capacity.yml

@@ -0,0 +1,107 @@
+id: caching-artifacts-019
+title: "Docker BuildKit type=gha cache silently stops working when repo cache is full"
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - docker
+  - buildkit
+  - buildx
+  - cache
+  - gha-cache
+  - type-gha
+patterns:
+  - regex: "cache export feature is currently not supported"
+    flags: "i"
+  - regex: "failed to fetch remote cache"
+    flags: "i"
+  - regex: "importing cache manifest from gha"
+    flags: "i"
+  - regex: "exporting cache.*SKIPPED"
+    flags: "i"
+error_messages:
+  - "WARNING: cache export feature is currently not supported for docker driver"
+  - "#0 importing cache manifest from gha"
+  - "failed to fetch remote cache: importing cache manifest: not found"
+  - "WARNING: failed to get cache: httpReadSeeker: failed open: unexpected status code 410 Gone"
+root_cause: |
+  Docker BuildKit supports storing build layer cache directly in GitHub Actions
+  cache (type=gha) via docker/build-push-action. This cache backend shares the
+  same 10 GB per-repository cache limit enforced by actions/cache.
+
+  When large images or many active branches push their layer caches, the 10 GB
+  limit is reached. GitHub silently evicts the oldest cache entries using LRU
+  eviction. On the next run the build starts from scratch with no layers cached,
+  but the workflow still reports success — the only symptom is a much slower
+  build with no warning.
+
+  Additional silent failure mode: using the default docker driver (not
+  docker-container) causes "cache export feature is currently not supported"
+  warnings that are easy to miss. The type=gha backend requires the
+  docker-container (or docker-buildx) driver and the containerd image store.
+
+  Per-key limits: individual cache entries exceeding ~5 GB may fail to write
+  completely, resulting in partial caches that are never reusable on restore.
+fix: |
+  Use mode=min so that only the final image layer is cached rather than all
+  intermediate build stages. This dramatically reduces cache pressure.
+
+  For large production images that need full layer caching, use
+  cache-to: type=registry pointing to GHCR (free for public repos) to bypass
+  the 10 GB GitHub Actions cache limit entirely.
+
+  Always configure setup-buildx-action before build-push-action to ensure
+  the docker-container driver is active and type=gha export is supported.
+fix_code:
+  - language: yaml
+    label: "Use mode=min and ensure docker-container driver is configured"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Set up Docker Buildx
+              uses: docker/setup-buildx-action@v3
+              # docker-container driver is the default for setup-buildx-action
+              # Required for type=gha cache export to work at all
+
+            - name: Build and push
+              uses: docker/build-push-action@v6
+              with:
+                push: true
+                tags: ghcr.io/${{ github.repository }}:latest
+                cache-from: type=gha
+                cache-to: type=gha,mode=min  # min = final layer only, not all stages
+  - language: yaml
+    label: "Use GHCR registry cache to bypass the 10 GB GitHub Actions cache limit"
+    code: |
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build and push with registry cache
+        uses: docker/build-push-action@v6
+        with:
+          push: true
+          tags: ghcr.io/${{ github.repository }}:latest
+          cache-from: type=registry,ref=ghcr.io/${{ github.repository }}:buildcache
+          cache-to: type=registry,ref=ghcr.io/${{ github.repository }}:buildcache,mode=max
+prevention:
+  - "Always add docker/setup-buildx-action before docker/build-push-action to enable type=gha"
+  - "Prefer mode=min for type=gha to minimize cache footprint per build"
+  - "Monitor cache usage in Settings > Actions > Caches — eviction is silent until builds slow down"
+  - "Use scope parameter to separate caches per branch: cache-to: type=gha,scope=${{ github.ref_name }},mode=min"
+  - "For large production images prefer type=registry (GHCR) over type=gha to avoid the 10 GB cap"
+docs:
+  - url: "https://docs.docker.com/build/ci/github-actions/cache/#github-cache"
+    label: "Docker Docs — GitHub Actions cache backend for BuildKit"
+  - url: "https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows#usage-limits-and-eviction-policy"
+    label: "GitHub Docs — Cache usage limits and eviction policy (10 GB limit)"
+  - url: "https://github.com/docker/build-push-action/issues/818"
+    label: "docker/build-push-action#818 — type=gha cache eviction behavior"
+  - url: "https://github.com/docker/setup-buildx-action"
+    label: "docker/setup-buildx-action — Required to enable BuildKit cache backends"

package/errors/caching-artifacts/setup-ruby-bundler-ephemeral-workdir-cache-miss.yml

@@ -0,0 +1,147 @@
+id: caching-artifacts-018
+title: "setup-ruby Bundler Cache Always Misses on Ephemeral Self-Hosted Runners Due to Workdir in Cache Key"
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - ruby
+  - setup-ruby
+  - bundler
+  - cache
+  - self-hosted
+  - ephemeral
+  - cache-miss
+  - cache-key
+patterns:
+  - regex: "Cache not found for.*setup-ruby-bundler-cache.*wd-.*[0-9]{8,}"
+    flags: "i"
+  - regex: "setup-ruby-bundler-cache.*wd-\\/.*[a-f0-9]{8,}.*Gemfile\\.lock"
+    flags: "i"
+  - regex: "No cache found.*setup-ruby-bundler.*workdir.*ephemeral"
+    flags: "i"
+  - regex: "Cache miss.*bundler.*setup-ruby.*self-hosted"
+    flags: "i"
+error_messages:
+  - "Cache not found for input keys: setup-ruby-bundler-cache-v6-ubuntu-22.04-x64-ruby-3.3.6-wd-/codebuild/output/src1813367680/src/actions-runner/_work/myapp/myapp-with--without--only--Gemfile.lock-3f96ad38..."
+  - "No cache found for key: setup-ruby-bundler-cache-v6-..."
+root_cause: |
+  `ruby/setup-ruby` includes the absolute working directory path (`wd-<path>`) as a
+  component of the Bundler cache key. The full cache key format is:
+
+    setup-ruby-bundler-cache-v{VERSION}-{OS}-{ARCH}-ruby-{RUBY_VERSION}-wd-{WORKDIR}-...{GEMFILE_HASH}
+
+  On GitHub-hosted runners, the working directory is deterministic per run
+  (`/home/runner/work/{repo}/{repo}` on Linux), so the cache key is stable across runs
+  and the cache is reused correctly.
+
+  On **ephemeral self-hosted runners** (e.g., AWS CodeBuild, GitLab CI runners with
+  unique workspace paths, or any runner that generates a unique working directory path
+  per run for isolation), the `wd-` component changes with each run. This makes every
+  cache lookup a miss — the Bundler gems are reinstalled from scratch on every run,
+  completely defeating the purpose of caching.
+
+  This affects:
+  - AWS CodeBuild with GitHub Actions runners (CodeBuild generates unique src paths per build)
+  - Kubernetes-based ephemeral runners where the pod workspace path includes a job ID
+  - Any custom runner setup that includes a timestamp or job ID in the workspace path
+
+  The issue is open (ruby/setup-ruby#904, April 2026) and has no upstream fix yet as of
+  mid-2026. The workdir was included in the cache key to allow multiple Ruby projects to
+  have separate caches within the same repository, but it breaks ephemeral runners as a
+  side effect.
+
+  Note: This is a **silent failure** — no error is thrown; the workflow succeeds but Bundler
+  installs all gems on every run, causing slow CI with no visible warning about cache
+  effectiveness.
+fix: |
+  **Workaround 1 — Disable setup-ruby's built-in bundler cache, use actions/cache manually**:
+  Set `bundler-cache: false` in setup-ruby and manage the Bundler cache yourself with
+  `actions/cache`, using only the `BUNDLE_PATH` and `Gemfile.lock` hash as the key
+  (no workdir component). This is the most reliable fix for ephemeral runners.
+
+  **Workaround 2 — Normalize the working directory** (if your runner supports it):
+  Configure your runner to use a fixed, predictable working directory path instead of
+  a unique-per-job path. This makes the setup-ruby cache key stable.
+
+  **Workaround 3 — Cache the Ruby gems directory directly**:
+  Cache `~/.bundle` or the Bundler install path rather than the per-project `vendor/bundle`,
+  since the home directory path is typically stable even on ephemeral runners.
+fix_code:
+  - language: yaml
+    label: "Disable setup-ruby cache and use actions/cache with stable key"
+    code: |
+      jobs:
+        test:
+          runs-on: self-hosted   # ephemeral runner
+          steps:
+            - uses: actions/checkout@v4
+
+            - uses: ruby/setup-ruby@v1
+              with:
+                ruby-version: '3.3'
+                bundler-cache: false   # Disable built-in cache (broken on ephemeral runners)
+
+            # Cache gems using a workdir-independent key
+            - uses: actions/cache@v4
+              id: bundle-cache
+              with:
+                path: ~/.bundle/cache
+                key: ${{ runner.os }}-bundle-${{ hashFiles('**/Gemfile.lock') }}
+                restore-keys: |
+                  ${{ runner.os }}-bundle-
+
+            - name: Install gems
+              run: bundle install --path ~/.bundle/cache
+              if: steps.bundle-cache.outputs.cache-hit != 'true'
+
+            - name: Bundle check
+              run: bundle check || bundle install
+  - language: yaml
+    label: "Cache vendor/bundle with BUNDLE_PATH and stable key (no workdir)"
+    code: |
+      jobs:
+        test:
+          runs-on: self-hosted
+          steps:
+            - uses: actions/checkout@v4
+
+            - uses: ruby/setup-ruby@v1
+              with:
+                ruby-version: '3.3'
+                bundler-cache: false
+
+            - uses: actions/cache@v4
+              with:
+                path: vendor/bundle
+                key: ${{ runner.os }}-gems-${{ hashFiles('**/Gemfile.lock') }}
+                restore-keys: |
+                  ${{ runner.os }}-gems-
+
+            - name: Install gems
+              run: |
+                bundle config path vendor/bundle
+                bundle install --jobs 4 --retry 3
+  - language: yaml
+    label: "GitHub-hosted runner — built-in cache works fine (no workaround needed)"
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-latest   # GitHub-hosted: stable workdir, cache works
+          steps:
+            - uses: actions/checkout@v4
+
+            - uses: ruby/setup-ruby@v1
+              with:
+                ruby-version: '3.3'
+                bundler-cache: true   # Works correctly on GitHub-hosted runners
+prevention:
+  - "Always use `bundler-cache: false` with `ruby/setup-ruby` on ephemeral self-hosted runners (CodeBuild, ephemeral Kubernetes runners) and manage caching manually."
+  - "Verify cache effectiveness by checking the `cache-hit` output and monitoring job duration across runs — a stable cache hit means no Bundler reinstall."
+  - "Use workdir-independent cache keys: `${{ runner.os }}-bundle-${{ hashFiles('**/Gemfile.lock') }}` instead of paths that include dynamic segments."
+  - "Track ruby/setup-ruby#904 for an upstream fix that makes the cache key workdir-independent by default."
+docs:
+  - url: "https://github.com/ruby/setup-ruby/issues/904"
+    label: "ruby/setup-ruby#904: Bundler cache not working due to ephemeral workdir (open)"
+  - url: "https://github.com/ruby/setup-ruby#caching-bundle-install-automatically"
+    label: "setup-ruby README: Caching bundle install automatically"
+  - url: "https://github.com/actions/cache/blob/main/README.md"
+    label: "actions/cache README: manual caching approach"