@htekdev/actions-debugger 1.0.126 → 1.0.128

package/errors/caching-artifacts/caching-artifacts-075.yml

@@ -0,0 +1,172 @@
+id: caching-artifacts-075
+title: '`actions/cache` entries saved by GitHub-hosted runners are not accessible from self-hosted runners — cache lookup returns miss despite matching key'
+category: caching-artifacts
+severity: error
+tags:
+  - actions-cache
+  - self-hosted
+  - github-hosted
+  - cache-miss
+  - cross-runner
+  - ACTIONS_CACHE_URL
+  - cache-backend
+patterns:
+  - regex: 'Cache not found for input keys'
+    flags: 'i'
+  - regex: 'No cache found.*self.hosted'
+    flags: 'i'
+  - regex: 'ACTIONS_CACHE_URL.*self.hosted'
+    flags: 'i'
+  - regex: 'cache.*miss.*self.hosted|self.hosted.*cache.*miss'
+    flags: 'i'
+error_messages:
+  - "Cache not found for input keys: my-cache-key-abc123"
+  - "Warning: Cache restore failed."
+  - "No cache found for key my-cache-key on self-hosted runner"
+root_cause: |
+  `actions/cache` stores and retrieves cache entries via a **runner-specific
+  `ACTIONS_CACHE_URL` endpoint** that is injected into each job by the Actions
+  infrastructure. The cache URL for a GitHub-hosted runner points to GitHub's
+  hosted cache service, while the cache URL for a self-hosted runner may point to
+  a different endpoint (e.g., GHES cache, Actions Runner Controller cache proxy,
+  or a completely different ACTIONS_CACHE_URL configured by the runner operator).
+
+  When a GitHub-hosted runner saves a cache entry:
+  - The entry is stored at GitHub's hosted cache service endpoint.
+  - The entry IS visible via the GitHub Cache REST API and the repository's
+    Actions → Caches UI.
+
+  When a self-hosted runner tries to restore the same key:
+  - The runner uses its own `ACTIONS_CACHE_URL`, which may point to a different
+    service.
+  - The cache lookup returns "Cache not found" even though the entry is visible
+    in the UI.
+  - No error is surfaced — the action silently reports a cache miss and the job
+    continues.
+
+  This is commonly encountered when:
+  1. **ARC (Actions Runner Controller) on Kubernetes** — ARC runners use a
+     `gha-cache-server` proxy sidecar that fronts GitHub's cache API; the proxy's
+     cache scope or URL differs from the GitHub-hosted ACTIONS_CACHE_URL.
+  2. **GHES (GitHub Enterprise Server)** — On-prem GHES cache is a separate
+     service from github.com hosted cache.
+  3. **Mixed runner pools** — Some jobs run on GitHub-hosted (`ubuntu-latest`)
+     and others on self-hosted runners; they do not share cache entries.
+  4. **Self-hosted runners with custom ACTIONS_CACHE_URL** — Operators configure
+     a custom cache backend (e.g., Artifactory, Nexus) that doesn't contain entries
+     from GitHub's hosted cache.
+
+  Related: actions/cache#1595 (open since April 2025).
+
+  The cache entries ARE there (visible via REST API) but are stored at a different
+  cache service endpoint than the one the self-hosted runner queries.
+fix: |
+  **Option 1 (Recommended) — Ensure all cache-sharing jobs use the same runner type:**
+  If a job saves a cache on a GitHub-hosted runner, ensure the job that needs to
+  restore it also runs on a GitHub-hosted runner. Do not rely on cross-runner-type
+  cache sharing.
+
+  **Option 2 — Configure a shared external cache backend:**
+  For mixed runner environments, configure all runners (GitHub-hosted and self-hosted)
+  to use a shared external cache backend. This requires customizing `ACTIONS_CACHE_URL`
+  on your self-hosted runners to point to the same service.
+
+  **Option 3 — Re-populate cache from self-hosted runners:**
+  Have the self-hosted runner job save its own cache entry with the same key on first
+  miss. Subsequent self-hosted runner runs will hit this entry. The GitHub-hosted and
+  self-hosted entries may diverge if they have different paths.
+
+  **Option 4 — Use artifact-based sharing instead of cache:**
+  If the data must cross runner types, use `actions/upload-artifact` and
+  `actions/download-artifact` instead of cache. Artifacts are stored and retrieved
+  via the same GitHub API endpoint regardless of runner type.
+fix_code:
+  - language: yaml
+    label: 'Broken — cache saved by GitHub-hosted runner, restored by self-hosted (misses)'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest          # GitHub-hosted runner saves cache
+          steps:
+            - uses: actions/checkout@v4
+            - uses: actions/cache@v4
+              with:
+                path: ~/.npm
+                key: npm-${{ hashFiles('**/package-lock.json') }}
+            - run: npm ci
+
+        test:
+          runs-on: self-hosted            # ✗ Self-hosted runner cannot access
+          needs: build                    #   github-hosted runner's cache entry
+          steps:
+            - uses: actions/cache@v4
+              with:
+                path: ~/.npm
+                key: npm-${{ hashFiles('**/package-lock.json') }}
+                # → Always "Cache not found for input keys: npm-..."
+            - run: npm test
+
+  - language: yaml
+    label: 'Fixed — both jobs on the same runner type share cache entries'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest          # ✓ Both jobs use GitHub-hosted runners
+          steps:
+            - uses: actions/checkout@v4
+            - uses: actions/cache@v4
+              with:
+                path: ~/.npm
+                key: npm-${{ hashFiles('**/package-lock.json') }}
+            - run: npm ci
+
+        test:
+          runs-on: ubuntu-latest          # ✓ Same runner type = same cache backend
+          needs: build
+          steps:
+            - uses: actions/cache@v4
+              with:
+                path: ~/.npm
+                key: npm-${{ hashFiles('**/package-lock.json') }}
+                # ✓ Cache hit — saved by github-hosted, restored by github-hosted
+            - run: npm test
+
+  - language: yaml
+    label: 'Alternative — use upload-artifact / download-artifact for cross-runner sharing'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest          # GitHub-hosted builds the artifacts
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm ci && npm run build
+            - uses: actions/upload-artifact@v4
+              with:
+                name: build-output
+                path: dist/
+
+        test:
+          runs-on: self-hosted            # ✓ Artifacts are accessible from any runner type
+          needs: build
+          steps:
+            - uses: actions/download-artifact@v4
+              with:
+                name: build-output
+                path: dist/
+            - run: npm test
+
+prevention:
+  - 'Treat `actions/cache` entries as scoped to the runner type that created them — GitHub-hosted and self-hosted runners do not share a cache backend by default.'
+  - 'Design workflows so that cache-save and cache-restore jobs run on the same runner type (both GitHub-hosted or both self-hosted).'
+  - 'When mixing runner types, use `actions/upload-artifact` + `actions/download-artifact` for data that must cross the runner boundary.'
+  - 'Verify cache access in ARC (Actions Runner Controller) setups: ARC uses a gha-cache-server proxy that may have different scope from the GitHub-hosted cache.'
+  - 'Inspect `ACTIONS_CACHE_URL` in debug logs (`ACTIONS_RUNNER_DEBUG=true`) to confirm both runners are pointing to the same cache endpoint.'
+docs:
+  - url: 'https://github.com/actions/cache/issues/1595'
+    label: 'actions/cache#1595: GitHub-hosted runner cache not found from self-hosted runner (open 2025)'
+  - url: 'https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows#restrictions-for-accessing-a-cache'
+    label: 'GitHub Docs: Cache access restrictions'
+  - url: 'https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows'
+    label: 'GitHub Docs: Caching dependencies to speed up workflows'
+  - url: 'https://github.com/actions/actions-runner-controller/blob/main/docs/gha-runner-scale-set-controller/README.md'
+    label: 'ARC docs: Runner Scale Set — cache proxy configuration'

package/errors/known-unsolved/known-unsolved-074.yml

@@ -0,0 +1,141 @@
+id: known-unsolved-074
+title: '`hashFiles()` has a hardcoded 120-second timeout — fails silently on large repos with many files'
+category: known-unsolved
+severity: limitation
+tags:
+  - hashFiles
+  - timeout
+  - cache-key
+  - large-repo
+  - actions-cache
+  - 120-seconds
+  - known-limitation
+patterns:
+  - regex: 'hashFiles\(.+\) couldn''t finish within 120 seconds'
+    flags: 'i'
+  - regex: 'hashFiles.*couldn''t finish'
+    flags: 'i'
+  - regex: 'The template is not valid.*hashFiles.*couldn''t finish'
+    flags: 'i'
+error_messages:
+  - "Error: The template is not valid. .github/workflows/ci.yml (Line: N, Col: M): hashFiles('Assets/**', 'Packages/**', 'ProjectSettings/**') couldn't finish within 120 seconds."
+  - "hashFiles('**/pom.xml') couldn't finish within 120 seconds."
+  - "hashFiles('**/Podfile.lock') couldn't finish within 120 seconds."
+root_cause: |
+  The `hashFiles()` expression function has a **hardcoded 120-second timeout** inside the
+  GitHub Actions runner. When hashing many files — large game projects, monorepos with
+  thousands of dependencies, or deeply nested directory trees — the hash process (a separate
+  Node.js subprocess) can exceed this limit.
+
+  The timeout is set in the runner source:
+  `src/Runner.Worker/Expressions/HashFilesFunction.cs` as a fixed constant. There is no
+  workflow-level configuration to extend or remove it. Pull Request actions/runner#1844,
+  opened in April 2022 to make the timeout configurable, has remained unmerged for years.
+
+  **Common triggers:**
+  - Unity game projects hashing `Assets/**`, `Packages/**`, `ProjectSettings/**` (tens of
+    thousands of binary and text assets).
+  - Java monorepos hashing `**/pom.xml` across hundreds of modules.
+  - iOS projects hashing `**/Podfile.lock` where CocoaPods creates large lock files.
+  - `actions/cache` Post step re-computing `hashFiles()` at the **end** of the job (to
+    check whether the cache should be saved), by which point many new files may exist in
+    the hashed path, making the second hash slower than the first.
+  - Self-hosted Windows runners, which tend to have slower file system scan speeds than
+    Linux GitHub-hosted runners for large directory trees.
+
+  The error surfaces as a YAML template evaluation failure before any step runs, so the
+  entire job fails immediately with no useful diagnostic beyond the 120-second error.
+
+  Related: actions/runner#1840 (12 reactions, open since April 2022, last active May 2024).
+fix: |
+  There is **no native fix** — `hashFiles()` timeout is hardcoded and cannot be increased
+  in workflow YAML.
+
+  **Workaround 1 — Pre-compute the hash in a shell step:**
+  Run a shell command to hash the target files and write the result to a single file, then
+  use `hashFiles()` on only that single file. The shell command runs without the 120-second
+  runner constraint, and hashing one file is nearly instant.
+
+  **Workaround 2 — Use the last Git commit hash for the target directory:**
+  `git log` is much faster than file-content hashing. If cache invalidation on the last
+  commit touching the directory is acceptable (rather than on file-content change), use
+  `git log -1 --pretty=format:%H -- <directory>` to generate the key.
+
+  **Workaround 3 — Narrow the glob pattern:**
+  Instead of `Assets/**`, narrow to a specific file type:
+  `Assets/**/*.meta` or `Assets/**/*.asset`. Fewer files = faster hash = less chance of
+  timeout. Acceptable when only certain file types are meaningful for cache invalidation.
+
+  **Workaround 4 — Reduce what goes in the hashed path:**
+  If you control the directory structure, move frequently-updated large binary files out
+  of the hashed path so the glob matches fewer files.
+fix_code:
+  - language: yaml
+    label: 'Broken — hashFiles() times out on large directory tree'
+    code: |
+      - uses: actions/cache@v4
+        with:
+          path: Library
+          # ✗ hashFiles() will time out if Assets/**, Packages/**, ProjectSettings/**
+          # contains thousands of files (e.g. large Unity project)
+          key: Library-${{ hashFiles('Assets/**', 'Packages/**', 'ProjectSettings/**') }}
+
+  - language: yaml
+    label: 'Fixed — pre-compute hash in a shell step, then hashFiles() on single file'
+    code: |
+      - name: Generate cache key from directory contents
+        run: |
+          find Assets Packages ProjectSettings \
+            -type f | sort | xargs sha256sum > /tmp/unity-hash-input.txt
+          # On Windows self-hosted runner, use PowerShell instead:
+          # Get-ChildItem -Recurse Assets,Packages,ProjectSettings |
+          #   Where-Object { !$_.PSIsContainer } |
+          #   Sort-Object FullName |
+          #   ForEach-Object { sha256sum $_.FullName } |
+          #   Out-File /tmp/unity-hash-input.txt -Encoding utf8
+
+      - uses: actions/cache@v4
+        with:
+          path: Library
+          # ✓ hashFiles() on a single pre-computed file is nearly instant
+          key: Library-${{ hashFiles('/tmp/unity-hash-input.txt') }}
+
+  - language: yaml
+    label: 'Alternative — use last Git commit hash touching the cached directory'
+    code: |
+      - name: Get cache key from last commit touching packages
+        run: |
+          echo "PKG_HASH=$(git log -1 --pretty=format:%H -- packages/)" >> $GITHUB_ENV
+
+      - uses: actions/cache@v4
+        with:
+          path: ~/.m2/repository
+          # ✓ git log is instant regardless of how many files are in packages/
+          # Note: invalidates on commit, not on file-content change
+          key: maven-${{ runner.os }}-${{ env.PKG_HASH }}
+
+  - language: yaml
+    label: 'Alternative — narrow glob to only meaningful file types'
+    code: |
+      - uses: actions/cache@v4
+        with:
+          path: Library
+          # ✓ Narrow glob: only hash .meta files instead of all assets
+          # Fewer matched files = faster hash = less risk of timeout
+          key: Library-${{ hashFiles('Assets/**/*.meta', 'Packages/**/package.json') }}
+
+prevention:
+  - 'For any project with more than ~10,000 files in the hashed path, pre-compute the hash in a shell step instead of using `hashFiles()` directly in the cache key expression.'
+  - 'Test `hashFiles()` locally by adding a step that logs the evaluation time: the timeout occurs during expression evaluation, before the step executes.'
+  - 'On Windows self-hosted runners, file system scan is slower — lower the threshold for when to switch to a pre-computed hash (≥5,000 files).'
+  - 'Watch the `actions/cache` Post step — it re-evaluates `hashFiles()` at job end to decide whether to save. If you add files to the hashed path during the job, the Post step can time out even when the Pre step succeeded.'
+  - 'Upvote actions/runner#1844 — the PR to make the timeout configurable. No merge timeline as of June 2026.'
+docs:
+  - url: 'https://github.com/actions/runner/issues/1840'
+    label: 'actions/runner#1840: hashFiles() couldn''t finish within 120 seconds (12 reactions, open since 2022)'
+  - url: 'https://github.com/actions/runner/pull/1844'
+    label: 'actions/runner#1844: PR to make hashFiles() timeout configurable (unmerged)'
+  - 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() expression function'
+  - 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/known-unsolved/known-unsolved-075.yml

@@ -0,0 +1,147 @@
+id: known-unsolved-075
+title: '`matrix` context unavailable in job-level `if:` condition when matrix is dynamically generated from upstream job outputs'
+category: known-unsolved
+severity: limitation
+tags:
+  - matrix
+  - dynamic-matrix
+  - if-condition
+  - job-level
+  - fromJSON
+  - needs-outputs
+patterns:
+  - regex: 'Unrecognized named-value.*matrix.*Located at position'
+    flags: 'i'
+  - regex: 'matrix.*context.*not.*available.*if|if.*matrix.*unrecognized'
+    flags: 'i'
+error_messages:
+  - "Unrecognized named-value: 'matrix'. Located at position 26 within expression: contains(inputs.SCHEMAS, matrix.customer.schema)"
+  - "The workflow is not valid. ... Unrecognized named-value: 'matrix'."
+root_cause: |
+  When a job uses `strategy.matrix` with values derived from an upstream job's outputs
+  (e.g. `fromJson(needs.set-matrix.outputs.matrix)`), the `matrix` context is **not**
+  available in the job's own `if:` condition.
+
+  The root cause is evaluation ordering: GitHub Actions evaluates job-level `if:`
+  conditions **before** resolving the dynamic matrix values from upstream job outputs.
+  At the time `if:` is checked, the specific matrix combination (e.g. `matrix.schema`,
+  `matrix.os`) has not yet been bound.
+
+  This limitation does NOT affect:
+  - Step-level `if:` conditions inside the job (matrix IS available there)
+  - Static matrices defined inline with literal values (matrix IS available in job-level if)
+  - Downstream jobs reading this job's outputs (normal needs chain)
+
+  **Workaround does not exist at job level**: There is no supported way to filter
+  individual matrix combinations at the job `if:` level when the matrix is dynamic.
+  GitHub's matrix `include`/`exclude` keys do not support expressions.
+
+  The only workaround is to move the filtering logic inside a step using
+  `if: condition` at the step level, or to generate a pre-filtered matrix in the
+  upstream job so that no filtering is needed at the consumer job level.
+
+  Source: actions/runner#1985 (64 reactions, open since 2022)
+  Community discussion: https://github.community/t/matrix-cannot-be-used-in-jobs-level-if/17177
+fix: |
+  **Option 1 (recommended): Filter inside the upstream matrix-generation job**
+
+  Produce a matrix JSON that only includes the combinations you want to run. This is
+  the cleanest approach — no filtering needed in the consumer job.
+
+  **Option 2: Use step-level `if:` instead of job-level `if:`**
+
+  Move the filtering logic into the first step of the job. The job itself runs for
+  every matrix entry but exits cleanly. This wastes a job slot but works.
+
+  **Option 3: Use `continue-on-error: true` with an early-exit pattern**
+
+  Not recommended — harder to distinguish real failures from filtered runs.
+fix_code:
+  - language: yaml
+    label: "Broken — matrix context in job-level if with dynamic matrix"
+    code: |
+      jobs:
+        set-matrix:
+          runs-on: ubuntu-latest
+          outputs:
+            matrix: ${{ steps.gen.outputs.matrix }}
+          steps:
+            - id: gen
+              run: |
+                echo 'matrix={"customer":[{"schema":"prod"},{"schema":"staging"}]}' >> "$GITHUB_OUTPUT"
+
+        deploy:
+          needs: set-matrix
+          runs-on: ubuntu-latest
+          strategy:
+            matrix: ${{ fromJson(needs.set-matrix.outputs.matrix) }}
+          # ❌ FAILS: "Unrecognized named-value: 'matrix'"
+          if: contains(inputs.SCHEMAS, matrix.customer.schema)
+          steps:
+            - run: echo "Deploying ${{ matrix.customer.schema }}"
+
+  - language: yaml
+    label: "Fixed Option 1 — pre-filter in the matrix-generation job"
+    code: |
+      jobs:
+        set-matrix:
+          runs-on: ubuntu-latest
+          outputs:
+            matrix: ${{ steps.gen.outputs.matrix }}
+          steps:
+            - id: gen
+              # ✅ Generate only the matrix entries that should run
+              run: |
+                # Filter based on inputs.SCHEMAS inside the script
+                SCHEMAS="${{ inputs.SCHEMAS }}"
+                MATRIX=$(jq -n --arg schemas "$SCHEMAS" \
+                  '[{"schema":"prod"},{"schema":"staging"}] |
+                   map(select(.schema | IN($schemas | split(","))))' \
+                  | jq -c '{customer:.}')
+                echo "matrix=$MATRIX" >> "$GITHUB_OUTPUT"
+
+        deploy:
+          needs: set-matrix
+          runs-on: ubuntu-latest
+          strategy:
+            matrix: ${{ fromJson(needs.set-matrix.outputs.matrix) }}
+          # ✅ No job-level if needed — matrix is already filtered
+          steps:
+            - run: echo "Deploying ${{ matrix.customer.schema }}"
+
+  - language: yaml
+    label: "Fixed Option 2 — move filtering to step-level if"
+    code: |
+      jobs:
+        deploy:
+          needs: set-matrix
+          runs-on: ubuntu-latest
+          strategy:
+            matrix: ${{ fromJson(needs.set-matrix.outputs.matrix) }}
+          # ✅ No job-level if — allow all matrix entries through
+          steps:
+            # Early exit for matrix entries that don't match
+            - name: Check if this schema should deploy
+              # ✅ matrix context IS available in step-level if conditions
+              if: "!contains(inputs.SCHEMAS, matrix.customer.schema)"
+              run: |
+                echo "Skipping schema ${{ matrix.customer.schema }}"
+                exit 0
+
+            - name: Deploy
+              if: contains(inputs.SCHEMAS, matrix.customer.schema)
+              run: echo "Deploying ${{ matrix.customer.schema }}"
+
+prevention:
+  - "When you need per-combination filtering, pre-filter the matrix JSON in the generation step rather than relying on job-level `if:` with matrix context."
+  - "Use step-level `if:` conditions (not job-level) when you must reference `matrix.*` context for filtering — step-level conditions evaluate after matrix expansion."
+  - "Check GitHub docs for 'Context availability' to confirm which contexts are available at each level before authoring complex conditional logic."
+docs:
+  - url: 'https://github.com/actions/runner/issues/1985'
+    label: 'actions/runner#1985 — Unrecognized named-value: matrix in job if conditional (64 reactions)'
+  - url: 'https://github.community/t/matrix-cannot-be-used-in-jobs-level-if/17177'
+    label: 'GitHub Community: matrix cannot be used in jobs level if'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-a-matrix-for-your-jobs'
+    label: 'GitHub Docs: Using a matrix for your jobs'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/contexts#context-availability'
+    label: 'GitHub Docs: Context availability table'

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

@@ -0,0 +1,146 @@
+id: runner-environment-236
+title: '`ubuntu-slim` runner has Docker CLI but no Docker daemon — docker build/pull and Dockerfile container actions fail'
+category: runner-environment
+severity: error
+tags:
+  - ubuntu-slim
+  - docker
+  - docker-daemon
+  - container-action
+  - docker-build
+  - dockerfile
+  - lightweight-runner
+patterns:
+  - regex: 'Cannot connect to the Docker daemon at unix:///var/run/docker\.sock'
+    flags: 'i'
+  - regex: 'docker\.sock.*no such file or directory'
+    flags: 'i'
+  - regex: 'ERROR: Cannot connect to the Docker daemon'
+    flags: 'i'
+  - regex: 'ubuntu-slim.*docker|docker.*ubuntu-slim'
+    flags: 'i'
+error_messages:
+  - "Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?"
+  - "ERROR: Cannot connect to the Docker daemon at unix:///var/run/docker.sock: connect: no such file or directory"
+  - "Docker build failed with exit code 1, back off 3.588 seconds before retry."
+  - "failed to connect to the docker API at unix:///var/run/docker.sock; check if the path is correct and if the daemon is running: dial unix /var/run/docker.sock: connect: no such file or directory"
+  - "/usr/bin/docker build ... ERROR: Cannot connect to the Docker daemon"
+root_cause: |
+  The `ubuntu-slim` GitHub-hosted runner image (added January 2026 via runner-images
+  PR#13542) is a **lightweight Ubuntu image intentionally stripped of the Docker daemon**.
+  It is designed for fast, low-overhead CI jobs (linting, unit tests, scripting) that
+  do not need container tooling.
+
+  **What ubuntu-slim DOES have:**
+  - Docker CLI (`docker` command is on `PATH`)
+  - Standard shell tooling, git, curl, Node.js, Python
+
+  **What ubuntu-slim does NOT have:**
+  - Docker daemon (no `/var/run/docker.sock` socket)
+  - Docker daemon service (not running — not even stopped, just not installed)
+  - BuildKit / buildx (requires daemon)
+
+  This affects several common patterns:
+  1. **`docker build` / `docker run` / `docker pull` in `run:` steps** — All fail
+     immediately because there is no daemon to dispatch commands to.
+  2. **Container actions** (`uses: some-org/docker-action@v1` where the action has a
+     `Dockerfile`) — The Actions runner tries to build the action's `Dockerfile` using
+     the host Docker daemon before executing the step. On `ubuntu-slim`, this fails during
+     job setup with "Cannot connect to the Docker daemon."
+  3. **`docker/setup-buildx-action`** — Fails because BuildKit requires a Docker daemon.
+  4. **Service containers** (`services:` block using Docker images) — Fail because
+     pulling and starting service containers requires the Docker daemon.
+
+  GitHub has closed requests to add Docker daemon to ubuntu-slim as "not_planned"
+  (runner-images#13583 Feb 2026), confirming this is **by design**.
+
+  This is distinct from `runner-environment-030` (ubuntu-arm64-docker-not-preinstalled),
+  which covers ARM64 partner runners where Docker CLI itself is missing. On ubuntu-slim,
+  Docker CLI IS present — only the daemon is absent.
+fix: |
+  **Option 1 (Recommended) — Switch to `ubuntu-latest` or `ubuntu-24.04`:**
+  If your workflow uses Docker in any form (docker build, container actions, service
+  containers), use a full Ubuntu image. Docker daemon is pre-installed and running
+  on `ubuntu-latest` and `ubuntu-24.04`.
+
+  **Option 2 — Conditionally skip Docker-dependent steps:**
+  If you want to use ubuntu-slim for most of a workflow but have one Docker step, you
+  cannot run that step on ubuntu-slim. Restructure into two jobs: one on ubuntu-slim for
+  fast non-Docker steps, one on ubuntu-latest for Docker steps.
+
+  **Option 3 — Use a Docker-in-Docker container (advanced, not recommended):**
+  You can run a `dind` (Docker-in-Docker) container as a service and set `DOCKER_HOST`
+  to point to it, but this is complex, slow, and defeats the purpose of ubuntu-slim.
+
+  **Option 4 — Replace Dockerfile container actions with JS/composite alternatives:**
+  Some Docker-based third-party actions have JavaScript equivalents that don't require
+  a daemon. Check if the action you're using has a non-Docker version.
+fix_code:
+  - language: yaml
+    label: 'Broken — docker commands and container actions fail on ubuntu-slim'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-slim    # ✗ No Docker daemon available
+
+          steps:
+            - uses: actions/checkout@v4
+
+            # ✗ Fails: "Cannot connect to the Docker daemon at unix:///var/run/docker.sock"
+            - name: Build Docker image
+              run: docker build -t myapp:latest .
+
+            # ✗ Also fails: action uses Dockerfile, requires Docker daemon to build
+            - name: Run Docker-based action
+              uses: some-org/docker-based-action@v2
+
+  - language: yaml
+    label: 'Fixed — use ubuntu-latest for any workflow that needs Docker'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest    # ✓ Docker daemon pre-installed and running
+
+          steps:
+            - uses: actions/checkout@v4
+
+            # ✓ Works: Docker daemon available on ubuntu-latest
+            - name: Build Docker image
+              run: docker build -t myapp:latest .
+
+            # ✓ Works: container actions can build their Dockerfiles
+            - name: Run Docker-based action
+              uses: some-org/docker-based-action@v2
+
+  - language: yaml
+    label: 'Pattern — split jobs to use ubuntu-slim for fast steps, ubuntu-latest for Docker'
+    code: |
+      jobs:
+        lint:
+          runs-on: ubuntu-slim      # ✓ Fast, no Docker needed for lint
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm run lint
+
+        docker-build:
+          runs-on: ubuntu-latest    # ✓ Docker available for build/push steps
+          needs: lint
+          steps:
+            - uses: actions/checkout@v4
+            - run: docker build -t myapp:latest .
+            - run: docker push myregistry/myapp:latest
+
+prevention:
+  - 'Before switching to `ubuntu-slim`, audit your workflow for `docker` commands, Dockerfile-based `uses:` steps, and `services:` blocks — any of these require a Docker daemon.'
+  - 'Container actions (actions with a `Dockerfile`) silently fail during job setup on ubuntu-slim, making the error appear before any step runs — check the "Set up job" section of the logs.'
+  - 'Check the ubuntu-slim software list at https://github.com/actions/runner-images to confirm Docker daemon is not present before migrating workflows.'
+  - '`service containers` defined in the `services:` block also require the Docker daemon — they will also fail on ubuntu-slim.'
+docs:
+  - url: 'https://github.com/actions/runner-images/issues/13583'
+    label: 'runner-images#13583: Docker pull failed on ubuntu-slim (closed as not_planned — by design)'
+  - url: 'https://github.com/actions/runner-images/pull/13542'
+    label: 'runner-images PR#13542: Add ubuntu-slim image (Jan 2026)'
+  - url: 'https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners'
+    label: 'GitHub Docs: About GitHub-hosted runners'
+  - url: 'https://docs.github.com/en/actions/creating-actions/creating-a-docker-container-action'
+    label: 'GitHub Docs: Creating a Docker container action'

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

@@ -0,0 +1,146 @@
+id: runner-environment-237
+title: 'Container job `$HOME` is hardcoded to `/github/home` — Docker images built with `/root` home break silently'
+category: runner-environment
+severity: error
+tags:
+  - container
+  - HOME
+  - docker
+  - self-hosted
+  - environment-variable
+  - tool-cache
+patterns:
+  - regex: '\$HOME.*github/home'
+    flags: 'i'
+  - regex: 'Could not find.*\$HOME.*plugin|command not found.*HOME.*github'
+    flags: 'i'
+  - regex: 'no such file.*github/home|Permission denied.*github/home'
+    flags: 'i'
+error_messages:
+  - "The reason `bluebase plugins` doesn't work is because it depends on `$HOME` pointing to `/root` but now GitHub Actions has changed it to `/github/home`."
+  - "Error: Could not find plugin at /github/home/.cache/@bluebase"
+  - "rust: command not found"
+  - "cargo: command not found"
+  - "go: command not found"
+root_cause: |
+  When using `jobs.<name>.container`, the GitHub Actions runner mounts a host volume at
+  `/github/home` and unconditionally overrides the `HOME` environment variable to point there,
+  regardless of:
+  - The Docker image's configured user or home directory
+  - Any `env: HOME:` value set in the container spec
+  - The container image's `ENV HOME` instruction
+
+  This is hard-coded in ContainerOperationProvider.cs:
+    `-v "/runner/work/_temp/_github_home":"/github/home"`
+    `HOME=/github/home`
+
+  The volume mount overwrites whatever was at `/github/home` inside the container, and
+  the forced HOME env var points to that empty/host-controlled directory.
+
+  **Impact on pre-installed tools**: Any CLI tool or plugin manager that stores
+  state relative to `$HOME` during the Docker image build (e.g. `npm global`, Rust's
+  `cargo`, Go binaries in `~/go/bin`, Homebrew cellar, Python user installs at
+  `~/.local`) will no longer find its data because HOME now points to `/github/home`
+  instead of `/root` or the image user's home.
+
+  Source: actions/runner#863 (124 reactions, open since 2021)
+fix: |
+  **Option 1 (recommended): Prefix affected commands with `HOME=/root`**
+
+  Temporarily reset HOME to the original image home for each step that relies on
+  pre-installed tools. Do NOT set HOME permanently in the workflow — the runner
+  depends on `/github/home` for internal state.
+
+  **Option 2: Rebuild Docker image with `/github/home` as the home directory**
+
+  Set `ENV HOME /github/home` in the Dockerfile before installing tools.
+  Note: if `/github/home` is empty at build time (it is), tools install there, and
+  the volume mount at runtime will still OVERWRITE the directory. This does not work.
+
+  **Option 3: Copy tool state in a setup step**
+
+  Add an entrypoint or a workflow step that copies `/root/.config`, `/root/.cache`,
+  `/root/go`, etc. to `/github/home` before the steps that need them run.
+
+  **Option 4: Avoid container jobs for images with pre-installed tools**
+
+  Use a Docker action (`uses: docker://image`) instead of `jobs.<name>.container`
+  — Docker actions do not override HOME.
+fix_code:
+  - language: yaml
+    label: "Broken — pre-installed cargo/rust not found in container job"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          container:
+            image: my-rust-tools:latest  # Built with cargo installed at /root/.cargo
+          steps:
+            - uses: actions/checkout@v4
+            - name: Build
+              run: cargo build --release  # ❌ FAILS: cargo not found — HOME=/github/home
+
+  - language: yaml
+    label: "Fixed — reset HOME per-step for pre-built tool invocations"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          container:
+            image: my-rust-tools:latest
+          steps:
+            - uses: actions/checkout@v4
+            - name: Build
+              run: HOME=/root cargo build --release  # ✅ HOME temporarily reset to where cargo is
+
+            # Or use env: at the step level:
+            - name: Run tests
+              env:
+                HOME: /root
+              run: cargo test
+
+  - language: yaml
+    label: "Fixed — rebuild Docker image with tools installed at github/home path"
+    code: |
+      # Dockerfile — install tools where GHA will point HOME
+      FROM ubuntu:22.04
+
+      # Install Rust to /github/home/.cargo (matches runtime HOME)
+      RUN mkdir -p /github/home
+      ENV HOME=/github/home
+      RUN curl https://sh.rustup.rs -sSf | sh -s -- -y
+
+      # In workflow, no HOME override needed:
+      # cargo is at /github/home/.cargo/bin — BUT runtime mount overwrites!
+      # This approach ONLY works if you add the PATH explicitly:
+      ENV PATH="/github/home/.cargo/bin:${PATH}"
+
+      # Better: install to /usr/local/bin which is not affected by HOME mount
+      RUN curl https://sh.rustup.rs -sSf | sh -s -- -y --default-toolchain stable
+      RUN cp -r /github/home/.cargo/bin/* /usr/local/bin/
+
+  - language: yaml
+    label: "Alternative — use Docker action instead of container job (HOME not overridden)"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - name: Build in custom container
+              uses: docker://my-rust-tools:latest  # ✅ HOME not overridden by runner
+              with:
+                args: cargo build --release
+
+prevention:
+  - "When building Docker images for use in `jobs.<name>.container`, install binaries to `/usr/local/bin` or another PATH location not dependent on `$HOME`."
+  - "Test container images locally by running `docker run -e HOME=/github/home <image> <command>` to reproduce the GHA HOME override before using them in workflows."
+  - "Prefer Docker actions (`uses: docker://image`) over container jobs if your image relies on a specific HOME directory — Docker actions do not override HOME."
+  - "Read actions/runner#863 before publishing a Docker image intended for use as a GHA container job."
+docs:
+  - url: 'https://github.com/actions/runner/issues/863'
+    label: 'actions/runner#863 — HOME is overridden for containers (124 reactions, open since 2021)'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/running-jobs-in-a-container'
+    label: 'GitHub Docs: Running jobs in a container'
+  - url: 'https://stackoverflow.com/questions/58516181/missing-installed-dependencies-when-docker-image-is-used'
+    label: 'Stack Overflow: Missing installed dependencies when Docker image is used (Score: 3)'

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

@@ -0,0 +1,151 @@
+id: runner-environment-238
+title: 'Self-hosted runner with Docker container steps creates root-owned files in workspace — `git clean` fails on next run'
+category: runner-environment
+severity: error
+tags:
+  - self-hosted
+  - docker
+  - container
+  - workspace
+  - permissions
+  - checkout
+  - root-owned
+patterns:
+  - regex: 'warning: could not open directory.*Permission denied'
+    flags: 'i'
+  - regex: 'failed to remove.*Directory not empty|rm.*cannot remove.*Permission denied'
+    flags: 'i'
+  - regex: 'Unable to clean or reset the repository.*recreated'
+    flags: 'i'
+error_messages:
+  - "warning: could not open directory 'foo/': Permission denied"
+  - "warning: failed to remove foo/: Directory not empty"
+  - "##[warning]Unable to clean or reset the repository. The repository will be recreated instead."
+  - "##[error]Command failed: rm -rf \"/home/runner/_work/repo/repo/foo\""
+  - "rm: cannot remove '/home/runner/_work/repo/repo/foo': Permission denied"
+  - "error: failed to run 'git clean -ffdx': exit code 1"
+root_cause: |
+  When a GitHub Actions workflow on a **self-hosted runner** uses a Docker-based step
+  (either `container:` jobs or `uses: docker://` actions), files written to the
+  workspace during that step are owned by `root:root` — because most Docker containers
+  run as root by default.
+
+  The self-hosted runner process runs as a non-root user (e.g., `github-runner`, `ubuntu`).
+  On the **next workflow run**, `actions/checkout` attempts to clean the workspace by
+  running `git clean -ffdx`. Git's clean-up calls `stat()` on root-owned directories.
+  Because stat succeeds (files are visible) but `rm` is blocked (not root), `git clean`
+  reports the directory but cannot remove it. Git then falls back to `rm -rf` via the
+  runner, which also fails with `Permission denied`.
+
+  The checkout action logs a warning "Unable to clean or reset the repository. The
+  repository will be recreated instead." — then `rm -rf` of the entire workspace also
+  fails because root-owned directories are nested inside. The job fails permanently
+  until a human manually removes the root-owned files on the runner host.
+
+  **Why GitHub-hosted runners don't hit this**: GitHub-hosted runners are ephemeral —
+  the workspace is destroyed after every job, so there's no cross-run persistence of
+  root-owned files. Self-hosted runners persist the workspace by default.
+
+  Source: actions/runner#434 (131 reactions, open since 2020)
+fix: |
+  **Option 1 (recommended): Run the container as the same UID as the host runner user**
+
+  Pass `--user $(id -u):$(id -g)` to Docker options so files are written with the
+  runner's UID/GID. Most images support this without modification.
+
+  **Option 2: Add a cleanup step before checkout**
+
+  Add a step at the start of the workflow that removes workspace contents using sudo.
+  Requires configuring passwordless sudo for the runner user.
+
+  **Option 3: Configure the container to run as root but add a post-step chown**
+
+  After container steps, add a step that runs `sudo chown -R $USER:$USER .` to
+  reclaim ownership. Still requires sudo access.
+
+  **Option 4: Use ephemeral (one-shot) self-hosted runners**
+
+  Ephemeral runners create a fresh workspace per job. No cross-run file persistence
+  means root-owned files from Docker steps never accumulate.
+
+  **Option 5: Set `clean: false` on checkout and handle cleanup yourself**
+
+  Disable automatic workspace cleaning in checkout and add your own robust cleanup
+  step that can handle permission errors.
+fix_code:
+  - language: yaml
+    label: "Fixed — run Docker container as host runner's UID"
+    code: |
+      jobs:
+        build:
+          runs-on: [self-hosted, linux]
+          container:
+            image: node:20
+            options: '--user 1001:1001'  # ✅ Match runner UID — no root-owned files
+
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm ci && npm run build
+
+  - language: yaml
+    label: "Fixed — run container as current user dynamically"
+    code: |
+      jobs:
+        build:
+          runs-on: [self-hosted, linux]
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Build in container (current user)
+              run: |
+                docker run --rm \
+                  --user "$(id -u):$(id -g)" \
+                  -v "${{ github.workspace }}:/work" \
+                  -w /work \
+                  node:20 \
+                  npm ci && npm run build
+                # ✅ Files written inside container owned by host runner user
+
+  - language: yaml
+    label: "Fixed — cleanup step before checkout to handle pre-existing root-owned files"
+    code: |
+      jobs:
+        build:
+          runs-on: [self-hosted, linux]
+          steps:
+            # ✅ Cleanup root-owned files before checkout
+            - name: Cleanup workspace
+              run: |
+                if [ -d "${{ github.workspace }}" ]; then
+                  sudo chown -R "$USER:$USER" "${{ github.workspace }}" || true
+                  sudo rm -rf "${{ github.workspace }}"
+                fi
+              # Requires: echo "runner ALL=(ALL) NOPASSWD: /bin/chown, /bin/rm" | sudo tee /etc/sudoers.d/runner
+
+            - uses: actions/checkout@v4
+
+  - language: yaml
+    label: "Fixed — register self-hosted runner as ephemeral (--ephemeral flag)"
+    code: |
+      # Register the runner with --ephemeral so each job gets a fresh workspace:
+      # ./config.sh --url https://github.com/org/repo --token TOKEN --ephemeral
+      #
+      # Or for ARC (Actions Runner Controller):
+      # spec:
+      #   ephemeral: true  # Each job pod is destroyed after completion
+
+prevention:
+  - "Always run Docker container steps with `--user $(id -u):$(id -g)` on self-hosted runners to match the host runner's UID/GID."
+  - "Use ephemeral self-hosted runners to eliminate cross-run workspace persistence entirely."
+  - "Add a workspace cleanup step at the start of workflows that use Docker container steps to proactively clear root-owned files."
+  - "After setting up a self-hosted runner, test with a workflow that uses a `container:` job and verify subsequent runs can clean up without errors."
+  - "When using ARC (Actions Runner Controller), enable `ephemeral: true` on the RunnerDeployment spec."
+docs:
+  - url: 'https://github.com/actions/runner/issues/434'
+    label: 'actions/runner#434 — Self-hosted runner with Docker step creates root-owned files (131 reactions)'
+  - url: 'https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners'
+    label: 'GitHub Docs: About self-hosted runners'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/running-jobs-in-a-container'
+    label: 'GitHub Docs: Running jobs in a container'
+  - url: 'https://stackoverflow.com/questions/76407664/files-owned-by-rootroot-when-using-actions-checkout-on-self-hosted-runner'
+    label: 'Stack Overflow: Files owned by root:root when using actions/checkout on self-hosted runner'

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

@@ -0,0 +1,162 @@
+id: silent-failures-119
+title: '`github.ref` and `GITHUB_REF` intermittently empty on `release` event — workflows that tag-check silently fail or exit 1'
+category: silent-failures
+severity: silent-failure
+tags:
+  - github.ref
+  - GITHUB_REF
+  - release
+  - release-event
+  - intermittent
+  - tag
+  - empty
+patterns:
+  - regex: 'github\.ref.*release|GITHUB_REF.*release.*empty'
+    flags: 'i'
+  - regex: 'refs/tags.*empty.*release|release.*github_ref.*blank'
+    flags: 'i'
+  - regex: 'startsWith\(github\.ref.*refs/tags.*false.*release'
+    flags: 'i'
+error_messages:
+  - "if [[ \"\" == refs/tags/release/* ]] ; then"
+  - "::error ::Could not determine the version number using ref "
+  - "GITHUB_REF: ''"
+  - "github.ref evaluates to empty string on release event"
+root_cause: |
+  When a workflow is triggered by an `on: release` event (e.g. `published`, `created`,
+  `prereleased`), the `github.ref` context value and `GITHUB_REF` environment variable
+  are **intermittently empty** — sometimes populated correctly, sometimes empty string.
+
+  The bug is non-deterministic: re-running the same workflow sometimes succeeds (ref
+  populated) and sometimes fails (ref empty). It is more frequent when:
+  - The release is created immediately after tagging
+  - Multiple releases fire in quick succession
+  - The workflow is called as a reusable workflow with `github.ref` forwarded
+
+  **Root cause**: A race condition or internal state propagation issue in the GitHub
+  Actions platform where the `release` event payload is dispatched before the ref
+  metadata is fully resolved in all runtime components. The `github.event.release`
+  object IS populated correctly in the same runs that have an empty `github.ref`.
+
+  **Impact**: Workflows that use `github.ref` to extract tag names (e.g.
+  `startsWith(github.ref, 'refs/tags/')`, or `echo $GITHUB_REF | cut -c11-`) will
+  silently get an empty string, causing:
+  - Conditional steps to be skipped (release-only deployments don't run)
+  - Version parsing to produce empty strings (publishing incorrect artifacts)
+  - Shell scripts to `exit 1` on empty-ref checks
+
+  This issue was introduced/regressed in August 2023 (runner ~v2.307) and remains
+  intermittently reproducible as of April/August 2025.
+
+  Source: actions/runner#2788 (65 reactions, open since 2023)
+fix: |
+  **Always use `github.event.release.tag_name` for release tag extraction** instead of
+  parsing `github.ref`. The `github.event.release` object is consistently populated
+  even when `github.ref` is empty.
+
+  For step-level `if:` conditions that check whether a workflow was triggered by a
+  release event, use `github.event_name == 'release'` instead of
+  `startsWith(github.ref, 'refs/tags/')`.
+
+  If you need the full `refs/tags/v1.2.3` ref format, construct it from the event:
+  `refs/tags/${{ github.event.release.tag_name }}`
+fix_code:
+  - language: yaml
+    label: "Broken — version extraction via github.ref (intermittently empty)"
+    code: |
+      on:
+        release:
+          types: [published]
+
+      jobs:
+        publish:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Extract version
+              run: |
+                # ❌ BROKEN: github.ref is intermittently empty on release events
+                VERSION="${{ github.ref }}"
+                if [[ "$VERSION" == refs/tags/v* ]]; then
+                  TAG="${VERSION#refs/tags/}"
+                else
+                  echo "::error ::Could not determine version from ref: $VERSION"
+                  exit 1
+                fi
+
+            # Also fragile:
+            - if: startsWith(github.ref, 'refs/tags/')   # ❌ sometimes false when ref is empty
+              run: echo "Publishing release"
+
+  - language: yaml
+    label: "Fixed — use github.event.release.tag_name (always populated)"
+    code: |
+      on:
+        release:
+          types: [published]
+
+      jobs:
+        publish:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Extract version
+              run: |
+                # ✅ FIXED: event.release.tag_name is always populated correctly
+                TAG="${{ github.event.release.tag_name }}"
+                echo "Publishing version: $TAG"
+                echo "VERSION=$TAG" >> "$GITHUB_ENV"
+
+            # For if: conditions, use event_name check instead of ref check:
+            - if: github.event_name == 'release'   # ✅ Always correct
+              run: echo "Publishing release ${{ github.event.release.tag_name }}"
+
+            # If you need the refs/tags/... format, construct it:
+            - name: Construct full ref
+              run: |
+                FULL_REF="refs/tags/${{ github.event.release.tag_name }}"
+                echo "Full ref: $FULL_REF"
+
+  - language: yaml
+    label: "Fixed — defensive workaround using both sources"
+    code: |
+      on:
+        release:
+          types: [published]
+
+      jobs:
+        publish:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Determine tag with fallback
+              id: tag
+              run: |
+                # Primary: event object (always populated)
+                TAG="${{ github.event.release.tag_name }}"
+
+                # Fallback: parse from github.ref if event is empty (unlikely)
+                if [ -z "$TAG" ] && [ -n "${{ github.ref }}" ]; then
+                  TAG="${{ github.ref }}"
+                  TAG="${TAG#refs/tags/}"
+                fi
+
+                if [ -z "$TAG" ]; then
+                  echo "::error ::Could not determine release tag from either source"
+                  exit 1
+                fi
+                echo "tag=$TAG" >> "$GITHUB_OUTPUT"
+
+            - run: echo "Publishing ${{ steps.tag.outputs.tag }}"
+
+prevention:
+  - "Never parse release tags from `github.ref` — always use `github.event.release.tag_name` in release-triggered workflows."
+  - "Use `github.event_name == 'release'` in `if:` conditions rather than `startsWith(github.ref, 'refs/tags/')` to avoid empty-ref false negatives."
+  - "Add explicit error messages when tag extraction returns empty string so intermittent failures are visible rather than silent."
+  - "If a release workflow fails unexpectedly, check whether `github.ref` was empty by adding `run: echo \"ref=${{ github.ref }}\"; echo \"tag=${{ github.event.release.tag_name }}\"`."
+docs:
+  - url: 'https://github.com/actions/runner/issues/2788'
+    label: 'actions/runner#2788 — github.ref is empty for workflows triggered by release (65 reactions)'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/events-that-trigger-workflows#release'
+    label: 'GitHub Docs: Events that trigger workflows — release'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/contexts#github-context'
+    label: 'GitHub Docs: github context'
+  - url: 'https://github.com/orgs/community/discussions/64528'
+    label: 'GitHub Community: github.ref empty on release event (discussion)'

package/errors/triggers/triggers-073.yml

@@ -0,0 +1,173 @@
+id: triggers-073
+title: '`on: workflow_run: branches:` filter matches head_branch of triggering run — PR merge triggers are silently skipped when head_branch is the PR branch, not the merge target'
+category: triggers
+severity: silent-failure
+tags:
+  - workflow_run
+  - branches-filter
+  - head-branch
+  - pr-merge
+  - silent-skip
+  - trigger-not-firing
+  - deploy-workflow
+patterns:
+  - regex: 'workflow_run:[\s\S]{0,200}branches:'
+    flags: 'im'
+  - regex: 'github\.event\.workflow_run\.head_branch'
+    flags: 'i'
+  - regex: 'workflow_run.*branches.*\[.*main.*\]'
+    flags: 'i'
+error_messages:
+  - "workflow not triggering after PR merge"
+  - "workflow_run with branches filter not firing on merge to main"
+root_cause: |
+  The `branches:` filter in an `on: workflow_run:` trigger compares against
+  `github.event.workflow_run.head_branch` — the branch the **source workflow** ran on.
+
+  When a pull request is opened, the source workflow (e.g., CI) runs with
+  `head_branch` = the feature branch name (e.g., `feat/my-change`). When GitHub
+  handles the PR merge, it creates a push to `main`, but it **reuses the PR's existing
+  check suite** rather than creating a new check run for the merge commit. As a result,
+  the `workflow_run` event that fires after the merge has:
+
+  ```
+  github.event.workflow_run.head_branch = "feat/my-change"  # PR branch, not "main"
+  github.event.workflow_run.head_sha    = "<merge-commit-sha>"
+  ```
+
+  If a downstream workflow has `branches: [main]`, this filter is evaluated against
+  `head_branch` = `"feat/my-change"`. The filter does NOT match — the downstream
+  workflow **silently never runs** after the PR merge.
+
+  This is counterintuitive because developers expect `branches: [main]` to mean
+  "trigger my deployment workflow only when CI ran on the main branch," not "only
+  when the source workflow's head_branch exactly equals main." The distinction matters
+  specifically for PR merges, where the push IS to main but the check run is attributed
+  to the PR branch.
+
+  **Who is affected:**
+  - Any deploy-on-merge pattern using `workflow_run` with `branches: [main]` or
+    `branches: [master]`
+  - Workflows that use `workflow_run` to chain CI → deploy only for the default branch
+
+  **Note:** Workflows triggered by a direct push to `main` (not a PR merge) DO have
+  `head_branch = "main"` and ARE correctly triggered by the `branches: [main]` filter.
+  The problem is specific to PR merges that go through the PR check-suite flow.
+
+  Source: observed in production deployments (commit Skretzo/shortest-path@8254fb4),
+  GitHub docs issue github/docs#42813 (Feb 2026).
+fix: |
+  **Remove `branches:` from the `workflow_run` trigger** and instead enforce the branch
+  restriction in a **job-level `if:` condition** that explicitly checks
+  `github.event.workflow_run.head_branch`:
+
+  ```yaml
+  on:
+    workflow_run:
+      workflows: ["CI"]
+      types: [completed]
+      # ✗ Remove: branches: [main]
+
+  jobs:
+    deploy:
+      # ✓ Check head_branch here instead — this sees the actual branch
+      if: >-
+        github.event.workflow_run.conclusion == 'success' &&
+        github.event.workflow_run.head_branch == 'main'
+  ```
+
+  This approach works for both direct pushes to main AND PR merges to main,
+  because the `if:` condition is evaluated at job execution time with the full
+  `workflow_run` event payload, while the `branches:` filter is evaluated at
+  trigger time and uses different matching semantics.
+
+  Alternatively, use the `workflow_run` trigger WITHOUT a branches filter and
+  rely entirely on job conditions to control which branches proceed to deployment.
+fix_code:
+  - language: yaml
+    label: 'Broken — branches: [main] silently blocks PR merge triggers'
+    code: |
+      # .github/workflows/deploy.yml
+      on:
+        workflow_run:
+          workflows: ["CI"]
+          types: [completed]
+          branches: [main]    # ✗ Matches head_branch of triggering run
+                              #   PR merges have head_branch = PR branch name
+                              #   → deploy never fires after PR merges to main
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          if: github.event.workflow_run.conclusion == 'success'
+          steps:
+            - run: ./deploy.sh
+
+  - language: yaml
+    label: 'Fixed — remove branches filter; check head_branch in job condition'
+    code: |
+      # .github/workflows/deploy.yml
+      on:
+        workflow_run:
+          workflows: ["CI"]
+          types: [completed]
+          # ✓ No branches filter — let all workflow_run events through
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          # ✓ Check head_branch in the if: condition
+          #   head_branch == 'main' correctly identifies merges to main
+          if: >-
+            github.event.workflow_run.conclusion == 'success' &&
+            github.event.workflow_run.head_branch == 'main'
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                ref: ${{ github.event.workflow_run.head_sha }}
+            - run: ./deploy.sh
+
+  - language: yaml
+    label: 'Pattern — full deploy-on-merge via workflow_run with branch guard'
+    code: |
+      # .github/workflows/deploy.yml
+      # Runs after CI completes successfully on any branch,
+      # but only deploys when it ran on main (direct push OR PR merge)
+      name: Deploy
+
+      on:
+        workflow_run:
+          workflows: ["CI"]
+          types: [completed]
+
+      jobs:
+        deploy:
+          name: Deploy to production
+          runs-on: ubuntu-latest
+          if: >-
+            github.event.workflow_run.conclusion == 'success' &&
+            github.event.workflow_run.head_branch == 'main'
+
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                # ✓ Check out the exact commit that CI ran on
+                ref: ${{ github.event.workflow_run.head_sha }}
+
+            - name: Deploy
+              run: |
+                echo "Deploying commit ${{ github.event.workflow_run.head_sha }}"
+                ./deploy.sh
+
+prevention:
+  - 'Never use `branches:` in `on: workflow_run:` if your deployment pattern relies on PR merges — always enforce branch restrictions in `jobs.<id>.if` conditions instead.'
+  - 'Test the pattern by creating a PR, merging it, and checking the Actions tab — the `workflow_run` event should appear even without a `branches` filter.'
+  - 'Use `github.event.workflow_run.head_branch` in the `if:` condition to distinguish deploy-worthy runs from feature-branch CI runs.'
+  - 'Document this behavior in your workflow comments so future contributors understand why the `branches:` filter is not used.'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_run'
+    label: 'GitHub Docs: workflow_run trigger — branches filter behavior'
+  - url: 'https://github.com/github/docs/issues/42813'
+    label: 'github/docs#42813: Clarify branches filter on workflow_run (Feb 2026)'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#using-data-from-the-triggering-workflow'
+    label: 'GitHub Docs: Using data from the triggering workflow'

package/package.json

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