@htekdev/actions-debugger 1.0.127 → 1.0.129

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

@@ -0,0 +1,141 @@
+id: caching-artifacts-076
+title: 'actions/cache 429 rate limit on restore not retried — workflow silently falls through to cache miss'
+category: caching-artifacts
+severity: warning
+tags:
+  - actions-cache
+  - rate-limit
+  - 429
+  - restore
+  - cache-miss
+  - silent-fallthrough
+patterns:
+  - regex: 'Failed to restore.*Rate limited.*429|rate limit exceeded.*GetCacheEntryDownloadURL'
+    flags: 'i'
+  - regex: 'You.ve hit a rate limit.*rate limit will reset'
+    flags: 'i'
+  - regex: 'Failed to GetCacheEntryDownloadURL.*Too Many Requests'
+    flags: 'i'
+error_messages:
+  - "Warning: You've hit a rate limit, your rate limit will reset in 18 seconds"
+  - "Warning: Failed to restore: Failed to GetCacheEntryDownloadURL: Rate limited: Failed request: (429) Too Many Requests: rate limit exceeded"
+  - "Cache not found for input keys: <key>"
+root_cause: |
+  When the GitHub Actions cache service returns HTTP 429 (Too Many Requests) on the
+  **restore/download path**, `actions/cache` does NOT implement retry logic for this
+  specific error. Instead, it:
+
+  1. Logs `Warning: You've hit a rate limit, your rate limit will reset in X seconds`
+  2. Logs `Warning: Failed to restore: Failed to GetCacheEntryDownloadURL: Rate limited`
+  3. Falls through to `Cache not found for input keys: <key>` — treating it as a cache miss
+  4. Continues workflow execution as if the cache doesn't exist
+
+  **Important distinction from upload 429:** The existing entry `cache-service-429-upload-ebadf-crash.yml`
+  covers HTTP 429 during cache UPLOAD causing an EBADF crash (a different, harder failure).
+  This entry covers 429 during cache RESTORE, which silently falls through without crashing
+  but causes unnecessary full rebuilds.
+
+  **Impact:** Workflows with many concurrent runs hitting the same cache key simultaneously
+  (e.g. a heavily-used monorepo's `node_modules` or `~/.cargo/registry` cache) can exceed
+  the per-key request rate limit. All concurrent runs that get rate-limited then execute a
+  full dependency install/build from scratch, multiplying CI time and cost. The 429 response
+  includes a reset time in the warning message but `actions/cache` ignores it.
+
+  **When it happens:** Most commonly seen in:
+  - Monorepos with many parallel jobs all restoring the same cache key
+  - High-frequency push workflows where many runs are active simultaneously
+  - Nightly builds on large teams where multiple jobs race for the same cache
+
+  Source: actions/cache#1758 (May 13, 2026), also reported via oxidecomputer/hubris#2535
+fix: |
+  No retry mechanism exists in `actions/cache` for restore-path 429 errors. The
+  following strategies reduce exposure:
+
+  **Option 1: Add job-level cache-key uniqueness to reduce simultaneous key contention**
+
+  Use a cache key that includes the job name or runner index, so parallel runs don't all
+  hit the exact same cache entry at once.
+
+  **Option 2: Add a retry wrapper around the restore step**
+
+  Use a loop + `cache-hit` output check to retry on miss within a reasonable window.
+
+  **Option 3: Use `actions/cache/restore` + `actions/cache/save` split and add `fail-on-cache-miss: false`**
+
+  Explicitly handle the miss and emit a warning rather than silently rebuilding.
+
+  **Option 4: File a +1 on actions/cache#1758**
+
+  The correct fix is for `actions/cache` to detect the 429 reset time and wait/retry
+  instead of falling through. Adding reactions encourages prioritization.
+fix_code:
+  - language: yaml
+    label: 'Recognize the 429 pattern and add explicit retry logic'
+    code: |
+      # The standard cache step falls through silently on 429.
+      # Add a retry wrapper to explicitly detect and retry:
+      steps:
+        - name: Restore cache (with 429 retry)
+          id: cache-restore
+          uses: actions/cache@v4
+          with:
+            path: ~/.npm
+            key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+            restore-keys: |
+              ${{ runner.os }}-node-
+
+        # Detect rate-limit fallthrough: cache appears to miss but key exists
+        - name: Retry cache if rate-limited
+          if: steps.cache-restore.outputs.cache-hit != 'true'
+          uses: actions/cache/restore@v4
+          with:
+            path: ~/.npm
+            key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+            restore-keys: |
+              ${{ runner.os }}-node-
+
+  - language: yaml
+    label: 'Reduce cache contention — add job index to key for parallel runs'
+    code: |
+      # When many parallel jobs restore the same cache key, add job uniqueness
+      # to distribute reads across different cache entries:
+      strategy:
+        matrix:
+          shard: [1, 2, 3, 4]
+
+      steps:
+        - uses: actions/cache@v4
+          with:
+            path: ~/.npm
+            # Use matrix shard to reduce simultaneous same-key requests
+            key: ${{ runner.os }}-node-shard${{ matrix.shard }}-${{ hashFiles('**/package-lock.json') }}
+            restore-keys: |
+              ${{ runner.os }}-node-shard${{ matrix.shard }}-
+              ${{ runner.os }}-node-
+  - language: yaml
+    label: 'Observe the rate limit in workflow logs'
+    code: |
+      # What the rate limit looks like in workflow output:
+      # (these are Warning lines, not Error — easy to miss)
+      #
+      # Run actions/cache@v4
+      # Received 0 cache(s) from cache.githubusercontent.com
+      # Warning: You've hit a rate limit, your rate limit will reset in 18 seconds
+      # Warning: Failed to restore: Failed to GetCacheEntryDownloadURL: Rate limited:
+      #          Failed request: (429) Too Many Requests: rate limit exceeded
+      # Cache not found for input keys: linux-node-abc123, linux-node-
+      #
+      # The workflow then continues as if cache was never created.
+      # Silent "success" hides wasted rebuild time.
+prevention:
+  - "When running many parallel jobs on a shared cache key, add per-job cache key suffixes (e.g. matrix index, job name) to distribute read load across different cache entries."
+  - "Monitor CI timing for unexplained slowdowns — a sudden increase in dependency install time across all parallel jobs is a signal that cache restoration is being rate-limited."
+  - "Cache keys with very high read frequency (multiple runs per minute across many jobs) are most susceptible. Use granular keys to avoid this."
+  - "Check that your cache key is stable (not changing per-run) — flapping keys force repeated cache service requests for new key registrations, increasing rate limit exposure."
+docs:
+  - url: 'https://github.com/actions/cache/issues/1758'
+    label: 'actions/cache#1758 — Handle rate limit on restore (no retry implemented)'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows#usage-limits-and-eviction-policy'
+    label: 'GitHub Docs: Cache usage limits and eviction policy'
+  - url: 'https://github.com/actions/cache'
+    label: 'actions/cache repository'

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

@@ -0,0 +1,158 @@
+id: caching-artifacts-077
+title: 'upload-artifact fails with "Bad Request" on self-hosted runners behind HTTPS proxy — Azure BlobClient not configured with proxy transport'
+category: caching-artifacts
+severity: error
+tags:
+  - upload-artifact
+  - proxy
+  - https-proxy
+  - azure-blob
+  - self-hosted
+  - bad-request
+patterns:
+  - regex: 'Error: Bad Request.*upload.*artifact|upload.*artifact.*Error: Bad Request'
+    flags: 'i'
+  - regex: 'BlobClient.*proxy|blob.*core.*windows.*proxy.*Bad Request'
+    flags: 'i'
+  - regex: 'Beginning upload of artifact content to blob storage[\s\S]*?Error: Bad Request'
+    flags: 'i'
+error_messages:
+  - "Error: Bad Request"
+  - "Beginning upload of artifact content to blob storage\nError: Bad Request"
+  - "Uploading artifact: <name>\nBeginning upload of artifact content to blob storage\nError: Bad Request"
+root_cause: |
+  When `HTTPS_PROXY` (or `https_proxy`) is set in the self-hosted runner environment,
+  `actions/upload-artifact` (v4+) fails with `Error: Bad Request` during the blob upload
+  step.
+
+  **Root cause:** `@actions/artifact` creates an Azure `BlobClient` from `@azure/storage-blob`
+  using only the pre-signed upload URL — no proxy transport configuration is passed:
+
+  ```typescript
+  const blobClient = new BlobClient(authenticatedUploadURL)
+  const blockBlobClient = blobClient.getBlockBlobClient()
+  ```
+
+  The Azure SDK creates its own internal HTTP pipeline that does not honor the environment's
+  `HTTPS_PROXY` variable. The CONNECT tunnel may appear to succeed (proxy returns 200) but
+  the Azure SDK's TLS negotiation through the proxy tunnel fails or sends incorrect frames,
+  producing a `Bad Request` response after a ~75-second stall.
+
+  **Affected actions:** Any action using `@actions/artifact` for blob uploads:
+  - `actions/upload-artifact` v4+
+  - Any third-party action built on `@actions/artifact`
+
+  **Same root cause in the runner itself:** The runner's C# `BlobClient` also lacks proxy
+  transport configuration, causing step logs and diagnostic uploads to stall similarly
+  (see actions/runner#4351).
+
+  **Proxy logs show the pattern:**
+  ```
+  CONNECT productionresultssa6.blob.core.windows.net:443 → status=200 (ALLOWED)
+    requestSize=~17 KB  (partial upload)
+    latency=~75 seconds  (stalled, not completing)
+  ```
+
+  **curl and Python upload the same blob endpoint in <1s through the same proxy** — the
+  issue is specific to the Azure SDK's pipeline construction when created without proxy opts.
+
+  Source: actions/toolkit#2377 (Apr 15, 2026), actions/runner#4351
+fix: |
+  **Workaround (recommended): Add `.blob.core.windows.net` to NO_PROXY**
+
+  Bypass the proxy for Azure Blob Storage traffic. Artifacts upload directly to Azure Blob
+  Storage endpoints (`*.blob.core.windows.net`), not through `api.github.com`.
+
+  Set `NO_PROXY` in the runner's environment (`.env` file, systemd unit, or runner config):
+  ```
+  NO_PROXY=.blob.core.windows.net,.actions.githubusercontent.com
+  ```
+
+  **Important:** This bypasses proxy inspection for Azure Blob traffic. If your security
+  policy requires proxy inspection for all egress, you must configure the proxy to pass
+  TLS-tunneled connections to `*.blob.core.windows.net` without re-signing.
+
+  **Permanent fix (pending upstream):**
+  The `@actions/artifact` package needs to pass `proxyOptions` when constructing `BlobClient`.
+  Monitor actions/toolkit#2377 for the fix. Once released, upgrading to the fixed version
+  of `actions/upload-artifact` will resolve the issue without needing `NO_PROXY`.
+fix_code:
+  - language: yaml
+    label: 'Workaround — set NO_PROXY to bypass proxy for Azure Blob Storage'
+    code: |
+      # In your runner's .env file (located at: <runner-dir>/.env)
+      # Add Azure Blob Storage and GitHub Actions results endpoints to NO_PROXY:
+      #
+      # HTTPS_PROXY=http://your-proxy:8080
+      # NO_PROXY=.blob.core.windows.net,.actions.githubusercontent.com,localhost,127.0.0.1
+      #
+      # Restart the runner service after editing .env:
+      #   sudo ./svc.sh stop
+      #   sudo ./svc.sh start
+
+      # If using ARC/Kubernetes, set as environment variables in the runner pod spec:
+      # spec:
+      #   containers:
+      #   - name: runner
+      #     env:
+      #     - name: HTTPS_PROXY
+      #       value: "http://your-proxy:8080"
+      #     - name: NO_PROXY
+      #       value: ".blob.core.windows.net,.actions.githubusercontent.com"
+
+  - language: yaml
+    label: 'Set NO_PROXY in the workflow as a fallback for managed runners'
+    code: |
+      # For managed self-hosted runners where you cannot edit the .env file,
+      # set NO_PROXY as a job-level env override before the upload step.
+      # Note: This only applies to workflow steps, not the runner service itself.
+      jobs:
+        build:
+          runs-on: [self-hosted]
+          env:
+            # Ensure Azure Blob Storage bypasses proxy for artifact uploads
+            NO_PROXY: '.blob.core.windows.net,.actions.githubusercontent.com'
+          steps:
+            - uses: actions/checkout@v4
+            - run: make build
+            - uses: actions/upload-artifact@v4
+              with:
+                name: build-output
+                path: dist/
+  - language: yaml
+    label: 'Confirm the root cause from workflow logs'
+    code: |
+      # Affected workflow output looks like:
+      #
+      # Run actions/upload-artifact@v4
+      # With the provided path, there will be 1 file uploaded
+      # Artifact name is valid!
+      # Root directory input is valid!
+      # Uploading artifact: my-artifact
+      # Beginning upload of artifact content to blob storage
+      # Error: Bad Request
+      #
+      # The "Beginning upload of artifact content to blob storage" line appears
+      # followed immediately (after ~75 seconds) by "Error: Bad Request".
+      # No detailed error, no retry, no stack trace.
+      #
+      # Workaround confirmation — after setting NO_PROXY correctly:
+      #
+      # Uploading artifact: my-artifact
+      # Beginning upload of artifact content to blob storage
+      # Artifact upload has finished successfully.
+      # Artifact 'my-artifact' has been successfully uploaded!
+prevention:
+  - "When deploying self-hosted runners behind a corporate HTTPS proxy, always configure `NO_PROXY` to include `.blob.core.windows.net` — this is where GitHub Actions stores artifacts and build outputs."
+  - "Test artifact upload and download on a new self-hosted runner deployment before declaring it production-ready. A quick test workflow with `actions/upload-artifact` and `actions/download-artifact` will reveal proxy issues immediately."
+  - "Include `.actions.githubusercontent.com` and `.blob.core.windows.net` in your proxy allow-list or NO_PROXY config — these are required for GitHub Actions to function correctly."
+  - "Monitor actions/toolkit#2377 for the upstream fix that adds proxy transport configuration to the Azure BlobClient. Once released, upgrade `actions/upload-artifact` to the fixed version."
+docs:
+  - url: 'https://github.com/actions/toolkit/issues/2377'
+    label: 'actions/toolkit#2377 — BlobClient upload fails with "Bad Request" through HTTPS proxy'
+  - url: 'https://github.com/actions/runner/issues/4351'
+    label: 'actions/runner#4351 — Runner Azure Blob uploads stall through HTTPS proxy (same root cause)'
+  - url: 'https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners#internet-access-for-self-hosted-runners'
+    label: 'GitHub Docs: Internet access requirements for self-hosted runners'
+  - url: 'https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/using-self-hosted-runners-in-a-workflow'
+    label: 'GitHub Docs: Using self-hosted runners in a workflow'

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-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/runner-environment/runner-environment-239.yml

@@ -0,0 +1,121 @@
+id: runner-environment-239
+title: 'setup-python fails on Ubuntu 26.04 container in self-hosted runners — Python version not in manifest'
+category: runner-environment
+severity: error
+tags:
+  - setup-python
+  - ubuntu-26
+  - manifest
+  - self-hosted
+  - container
+  - python-version
+patterns:
+  - regex: 'The version.*with architecture.*was not found for this operating system'
+    flags: 'i'
+  - regex: 'setup-python.*ubuntu.*26|ubuntu.*26.*setup-python'
+    flags: 'i'
+  - regex: 'version.*not found.*operating system.*ubuntu'
+    flags: 'i'
+error_messages:
+  - "Error: The version '3.13' with architecture 'x64' was not found for this operating system."
+  - "Error: The version '3.12' with architecture 'x64' was not found for this operating system."
+  - "Error: The version '3.11' with architecture 'x64' was not found for this operating system."
+root_cause: |
+  When a new Ubuntu LTS version (e.g. 26.04) is released, pre-built Python binaries for
+  that OS are NOT immediately added to the versions manifest at
+  `https://raw.githubusercontent.com/actions/python-versions/main/versions-manifest.json`.
+
+  `actions/setup-python` reads this manifest to locate and download pre-compiled Python
+  binaries matching the requested version and architecture. When the running OS identifier
+  is not present in the manifest, all version requests fail — even for Python versions that
+  exist for other Ubuntu releases (22.04, 24.04).
+
+  **Why GitHub-hosted runners succeed:** On GitHub-hosted `ubuntu-latest` runners, Python
+  versions are pre-installed in the toolcache. `setup-python` resolves from cache without
+  downloading, so the missing manifest entry doesn't matter.
+
+  **Why self-hosted runners fail:** Self-hosted runners typically don't have pre-installed
+  toolcaches. When `setup-python` tries to download the version for the container OS, the
+  manifest lookup fails because `ubuntu-26.04` is absent.
+
+  This is a recurring pattern. The same issue occurred when Ubuntu 24.04 launched
+  (see setup-python#854). Pre-built binaries are added only after the runner image reaches
+  general availability in `actions/runner-images`, which lags the OS release.
+
+  **Affected configurations:**
+  - `runs-on: [self-hosted]` + `container: ubuntu:latest` (resolves to Ubuntu 26.04)
+  - `runs-on: [self-hosted]` + `container: ubuntu:26.04`
+  - Any self-hosted runner setup where Python must be downloaded on demand for ubuntu 26.04
+
+  Source: actions/setup-python#1309 (May 5, 2026)
+fix: |
+  **Option 1 (recommended, temporary): Pin container to Ubuntu 24.04**
+
+  Until Ubuntu 26.04 Python binaries are added to the versions manifest, use an explicit
+  Ubuntu 24.04 container. This is the fastest fix with no other workflow changes.
+
+  **Option 2: Use a GitHub-hosted runner for Python setup**
+
+  GitHub-hosted `ubuntu-latest` runners have Python pre-installed in the toolcache and do
+  not require a manifest download. If you need a self-hosted runner for other reasons, you
+  can split: run setup-python on a hosted runner and transfer artifacts to the self-hosted
+  runner.
+
+  **Option 3: Pre-install Python in your container image**
+
+  Build a custom container image with Python pre-installed (via `apt`, `deadsnakes`, or
+  `pyenv`) so `setup-python` finds it in the system Python path rather than downloading.
+
+  **Option 4: Wait for manifest update**
+
+  Ubuntu 26.04 Python binaries will be added to the manifest after `ubuntu-26.04` reaches
+  GA status in `actions/runner-images`. Monitor setup-python#1309 for the fix notification.
+fix_code:
+  - language: yaml
+    label: 'Workaround — pin container to Ubuntu 24.04 until Ubuntu 26.04 is in manifest'
+    code: |
+      jobs:
+        build:
+          runs-on: [self-hosted]
+          # Pin to ubuntu:24.04 until ubuntu:26.04 is in the versions manifest
+          # Unpin once actions/setup-python#1309 is resolved
+          container: ubuntu:24.04   # was: ubuntu:latest or ubuntu:26.04
+          steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-python@v6
+              with:
+                python-version: '3.13'
+            - run: python --version
+  - language: yaml
+    label: 'Alternative — pre-install Python in a custom container image'
+    code: |
+      # Dockerfile — base image with Python already installed
+      FROM ubuntu:26.04
+      RUN apt-get update && apt-get install -y python3.13 python3.13-venv python3-pip && \
+          ln -s /usr/bin/python3.13 /usr/bin/python
+      # In workflow: container: your-registry/ubuntu-python:26.04
+      # Then skip actions/setup-python entirely — Python is pre-installed
+
+      # workflow.yml
+      jobs:
+        build:
+          runs-on: [self-hosted]
+          container: your-registry/ubuntu-python:26.04
+          steps:
+            - uses: actions/checkout@v4
+            # No setup-python needed — Python already in container
+            - run: python --version
+prevention:
+  - "When using `ubuntu:latest` as a container image, be aware that it will track the latest Ubuntu release. On new LTS releases, pin to an explicit version (e.g. `ubuntu:24.04`) until `actions/setup-python` adds manifest support."
+  - "Subscribe to the relevant `actions/setup-python` issues when Ubuntu LTS versions are released — Python manifest support lags by several weeks after the GA runner image is available."
+  - "If your self-hosted runners MUST use the newest Ubuntu release, pre-install Python in your base container image rather than relying on `setup-python` to download it."
+  - "Check the versions manifest directly to confirm OS support before adopting new Ubuntu versions in CI: https://raw.githubusercontent.com/actions/python-versions/main/versions-manifest.json"
+docs:
+  - url: 'https://github.com/actions/setup-python/issues/1309'
+    label: 'setup-python#1309 — Failing to fetch version from manifest when using Ubuntu 26.04 container'
+  - url: 'https://github.com/actions/setup-python/issues/854'
+    label: 'setup-python#854 — Same issue when Ubuntu 24.04 launched (historical precedent)'
+  - url: 'https://github.com/actions/python-versions/blob/main/versions-manifest.json'
+    label: 'Python versions manifest — check OS support'
+  - url: 'https://docs.github.com/en/actions/using-containerized-services/about-service-containers'
+    label: 'GitHub Docs: About service containers'

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

@@ -0,0 +1,140 @@
+id: runner-environment-240
+title: 'ARC v0.14.1 listener pods enter infinite crash-loop after upgrade — scaleset v0.3.0 treats broker EOF as fatal'
+category: runner-environment
+severity: error
+tags:
+  - arc
+  - actions-runner-controller
+  - kubernetes
+  - listener
+  - crash-loop
+  - scaleset
+  - ephemeral-runners
+patterns:
+  - regex: 'Listener pod is terminated.*reason.*Error'
+    flags: 'i'
+  - regex: 'scaleset.*v0\.3\.[0-9].*EOF|EOF.*broker.*fatal|EOF.*scaleset.*crash'
+    flags: 'i'
+  - regex: 'AutoscalingListener.*recreate.*loop|listener.*restart.*loop'
+    flags: 'i'
+error_messages:
+  - 'Listener pod is terminated  {"reason": "Error", "message": ""}'
+  - 'level=FATAL source=github.com/actions/scaleset@v0.3.0/listener/listener.go msg="EOF from broker"'
+  - 'AutoscalingListener: listener terminated unexpectedly, recreating'
+root_cause: |
+  ARC (Actions Runner Controller) v0.14.1 upgraded the internal `scaleset` library from
+  v0.2.0 to v0.3.0. The v0.3.0 library introduced a "Restore job acquisition flow" change
+  (scaleset PR #90) that treats **EOF responses from the GitHub Actions broker service**
+  (`broker.actions.githubusercontent.com`) as a **fatal error** instead of a transient
+  condition to retry.
+
+  **Before v0.3.0 (ARC v0.14.0):** EOF from the broker long-poll endpoint was treated as a
+  reconnect signal — the listener would gracefully retry the connection and continue.
+
+  **After v0.3.0 (ARC v0.14.1):** EOF causes the listener to exit with a non-zero status
+  code. The ARC controller detects the pod termination via `Listener pod is terminated`
+  with `reason: "Error"` and immediately recreates the listener pod. The new pod hits
+  another EOF and crashes again — producing an infinite restart loop.
+
+  **Note:** scaleset v0.4.0 does NOT fix this. It addresses a different (message ordering)
+  issue. The EOF-as-fatal regression is still present in v0.4.0.
+
+  **Impact:** All `AutoscalingRunnerSet` resources in the cluster enter crash-loop behavior.
+  Jobs queue but no runners are dispatched. Production ARC deployments can accumulate dozens
+  of error terminations within a 30-60 minute window.
+
+  **GitHub-hosted runners are unaffected** — this only impacts organizations using ARC
+  (self-hosted Kubernetes runners) via Helm chart `gha-runner-scale-set-controller`.
+
+  Source: actions/actions-runner-controller#4488 (May 6, 2026, 4 reactions)
+fix: |
+  **Option 1 (recommended): Downgrade to ARC v0.14.0**
+
+  Roll back the `gha-runner-scale-set-controller` Helm chart to the previous stable version:
+
+  ```
+  helm upgrade gha-runner-scale-set-controller \
+    --namespace arc-systems \
+    actions-runner-controller/gha-runner-scale-set-controller \
+    --version 0.14.0
+  ```
+
+  **Option 2: Wait for ARC v0.14.2+ with the EOF fix**
+
+  Monitor the ARC changelog and release notes at:
+  https://github.com/actions/actions-runner-controller/blob/master/docs/gha-runner-scale-set-controller/README.md#changelog
+
+  **Option 3 (partial mitigation): Reduce listener restart pressure**
+
+  Set `minRunners: 0` on affected `AutoscalingRunnerSet` resources to reduce the frequency
+  of broker long-poll connections that can EOF. This reduces symptom frequency but does
+  not eliminate the crash-loop.
+
+  **How to confirm the root cause:**
+  Check controller logs in the `arc-systems` namespace:
+  ```
+  kubectl logs -n arc-systems -l app=gha-runner-scale-set-controller --since=1h | grep "terminated"
+  ```
+  If you see repeated `Listener pod is terminated {"reason": "Error"}` entries cycling
+  every 1-5 minutes, this is the scaleset v0.3.0 EOF regression.
+fix_code:
+  - language: yaml
+    label: 'Identify crash-loop in controller logs'
+    code: |
+      # Check controller logs for the crash-loop pattern
+      # kubectl logs -n arc-systems deployment/gha-runner-scale-set-controller
+      # Look for repeated:
+      #   Listener pod is terminated  {"reason": "Error", "message": ""}
+      #   AutoscalingListener: recreating listener pod
+
+      # Also check the listener pod itself before it's deleted:
+      # kubectl logs -n arc-systems <listener-pod-name>
+      # Look for scaleset@v0.3.0 in the source path:
+      #   time=... source=github.com/actions/scaleset@v0.3.0/listener/listener.go:179
+      #            msg="Getting next message"
+  - language: yaml
+    label: 'Downgrade ARC controller Helm chart to v0.14.0'
+    code: |
+      # Downgrade via Helm — replace the controller chart version
+      # helm upgrade gha-runner-scale-set-controller \
+      #   --namespace arc-systems \
+      #   actions-runner-controller/gha-runner-scale-set-controller \
+      #   --version 0.14.0
+
+      # Or in your values/ArgoCD/Flux manifest, pin the chart version:
+      # Chart.yaml / helmrelease / kustomize reference:
+      apiVersion: helm.toolkit.fluxcd.io/v2
+      kind: HelmRelease
+      metadata:
+        name: gha-runner-scale-set-controller
+        namespace: arc-systems
+      spec:
+        chart:
+          spec:
+            chart: gha-runner-scale-set-controller
+            version: '0.14.0'   # Pin until EOF crash-loop is fixed in 0.14.2+
+            sourceRef:
+              kind: HelmRepository
+              name: actions-runner-controller
+  - language: yaml
+    label: 'Partial mitigation — set minRunners to 0 to reduce EOF pressure'
+    code: |
+      # gha-runner-scale-set values.yaml
+      # Reducing minRunners to 0 means the listener doesn't stay
+      # permanently connected to the broker, reducing EOF frequency.
+      # NOT a full fix — crash-loop still occurs but less frequently.
+      githubConfigUrl: 'https://github.com/<org>'
+      minRunners: 0     # Reduce from default to limit constant broker connections
+      maxRunners: 10
+prevention:
+  - "Before upgrading ARC to a new minor version, review the changelog at https://github.com/actions/actions-runner-controller/blob/master/docs/gha-runner-scale-set-controller/README.md#changelog for breaking changes in the scaleset library."
+  - "Deploy ARC upgrades to a staging cluster first. Monitor listener pod restarts for 30-60 minutes before rolling out to production."
+  - "Set up alerting on `Listener pod is terminated` log patterns in your ARC controller namespace — frequent terminations signal a crash-loop before it causes widespread job queuing failures."
+  - "Subscribe to release notifications for `actions/actions-runner-controller` to receive timely notice of regression fixes."
+docs:
+  - url: 'https://github.com/actions/actions-runner-controller/issues/4488'
+    label: 'ARC#4488 — Listener pods crash-loop after upgrading to ARC v0.14.1 (4 reactions)'
+  - url: 'https://github.com/actions/actions-runner-controller/blob/master/docs/gha-runner-scale-set-controller/README.md#changelog'
+    label: 'ARC Changelog — gha-runner-scale-set-controller release notes'
+  - url: 'https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/troubleshooting-actions-runner-controller-errors'
+    label: 'GitHub Docs: Troubleshooting Actions Runner Controller errors'

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/package.json

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