@htekdev/actions-debugger 1.0.125 → 1.0.127

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/concurrency-timing/concurrency-timing-059.yml

@@ -0,0 +1,146 @@
+id: concurrency-timing-059
+title: 'Skipped downstream job satisfies required status check — PR merges despite upstream job failure'
+category: concurrency-timing
+severity: silent-failure
+tags:
+  - needs
+  - skipped
+  - required-status-check
+  - branch-protection
+  - dependency
+  - silent-merge
+  - job-conclusion
+patterns:
+  - regex: 'This job was skipped'
+    flags: 'i'
+  - regex: 'Result: skipped'
+    flags: 'i'
+  - regex: 'needs\.[a-zA-Z0-9_-]+\.result.*skipped'
+    flags: 'i'
+error_messages:
+  - "This job was skipped."
+  - "Skipping this job because a previous job in the chain was skipped or failed."
+root_cause: |
+  GitHub Actions marks a downstream job as `skipped` (not `failure`) when an upstream
+  `needs:` dependency fails or is cancelled and the downstream job has no explicit `if:`
+  condition to handle that state.
+
+  Since April 2023, GitHub's branch protection rules treat a `skipped` check conclusion
+  as **passing** — equivalent to `success` — to support the common "aggregator job"
+  pattern. This means:
+
+  1. `build` job fails.
+  2. `test-results` job (which `needs: [build]`) is marked `skipped`.
+  3. Branch protection rule requires `test-results` to pass.
+  4. GitHub sees conclusion = `skipped` → treats it as satisfied → merge is allowed.
+
+  The PR can be merged even though the `build` step failed. There is no warning or
+  error in the UI — the required check shows a green checkmark (or neutral status)
+  rather than a red blocking indicator.
+
+  This behavior is distinct from:
+  - `cancel-in-progress` cancelling a required check (conclusion = `cancelled`, which
+    blocks merging — a separate issue).
+  - Path-filter causing a workflow to never run (check stays "Expected" / pending).
+  - The general skipped-needs cascade (which documents that downstream jobs skip, but
+    not the branch protection bypass consequence).
+fix: |
+  Add an explicit **catch-all aggregator job** that runs whenever any dependency failed
+  or was cancelled, and exits with a non-zero code:
+
+  ```yaml
+  ci-gate:
+    if: ${{ always() && (contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled')) }}
+    needs: [build, test, lint]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Fail — one or more required jobs did not succeed
+        run: |
+          echo "Required jobs: ${{ toJSON(needs.*.result) }}"
+          exit 1
+  ```
+
+  Set `ci-gate` as the sole required status check in branch protection. This aggregator
+  job only runs (and fails) when something upstream fails. When all upstream jobs
+  succeed, `ci-gate` is `skipped` → satisfies the required check. When any upstream
+  fails, `ci-gate` runs and explicitly fails → blocks the merge.
+
+  Alternatively, use the pattern that always runs the aggregator:
+
+  ```yaml
+  ci-gate:
+    if: always()
+    needs: [build, test, lint]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check all required jobs passed
+        run: |
+          results='${{ toJSON(needs.*.result) }}'
+          if echo "$results" | grep -qE '"failure"|"cancelled"'; then
+            echo "One or more jobs failed: $results"
+            exit 1
+          fi
+          echo "All required jobs passed."
+  ```
+fix_code:
+  - language: yaml
+    label: 'Broken — downstream skipped check silently satisfies branch protection'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - run: ./build.sh   # Fails
+
+        test-results:
+          needs: [build]        # Skipped when build fails
+          runs-on: ubuntu-latest
+          # ⚠ No if: condition — job is skipped when build fails
+          # ⚠ Branch protection requires test-results to "pass"
+          # ⚠ skipped = passing in GitHub's branch protection evaluation
+          steps:
+            - run: ./test.sh
+
+  - language: yaml
+    label: 'Fixed — explicit catch-all aggregator job that fails on upstream failure'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - run: ./build.sh
+
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - run: ./test.sh
+
+        ci-gate:
+          if: always()
+          needs: [build, test]
+          runs-on: ubuntu-latest
+          steps:
+            - name: All required jobs must succeed
+              run: |
+                results='${{ toJSON(needs.*.result) }}'
+                if echo "$results" | grep -qE '"failure"|"cancelled"'; then
+                  echo "Pipeline failed: $results"
+                  exit 1
+                fi
+                echo "All jobs passed: $results"
+
+      # In branch protection: require "ci-gate" — not "build" or "test" individually
+
+prevention:
+  - 'Use a single aggregator job (`ci-gate`) as the required status check instead of individual job names.'
+  - 'Always include `if: always()` on the aggregator and explicitly check `needs.*.result` for failure/cancelled.'
+  - 'Do NOT rely on `needs:` skipping to propagate failures to branch protection — skipped is treated as passing.'
+  - 'After changing which jobs are required status checks, verify by letting a build fail and confirm the PR is blocked.'
+  - 'actionlint does not detect this misconfiguration — manual testing is required.'
+docs:
+  - url: 'https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/troubleshooting-required-status-checks'
+    label: 'GitHub Docs: Troubleshooting required status checks'
+  - url: 'https://github.com/actions/runner/issues/2566'
+    label: 'actions/runner#2566: Skipped jobs satisfy required checks (many reactions)'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-conditions-to-control-job-execution'
+    label: 'GitHub Docs: Using conditions to control job execution'

package/errors/concurrency-timing/concurrency-timing-060.yml

@@ -0,0 +1,144 @@
+id: concurrency-timing-060
+title: 'cancel-in-progress: false still silently drops older pending run when third concurrent dispatch arrives — GitHub enforces a 1-active + 1-pending hard limit per concurrency group'
+category: concurrency-timing
+severity: silent-failure
+tags:
+  - concurrency
+  - cancel-in-progress
+  - pending
+  - silent-cancel
+  - dispatch
+  - queue
+  - lost-run
+patterns:
+  - regex: 'This run was cancelled'
+    flags: 'i'
+  - regex: 'cancel-in-progress:\s*false'
+    flags: 'i'
+  - regex: 'Run was cancelled'
+    flags: 'i'
+error_messages:
+  - "This run was cancelled."
+  - "Run was cancelled."
+root_cause: |
+  Setting `cancel-in-progress: false` in a concurrency group does NOT mean "queue all
+  runs indefinitely." It means "do not cancel the currently *in-progress* run."
+
+  GitHub Actions enforces a hard internal limit of **1 in-progress + 1 pending** run
+  per concurrency group (when using the default or `cancel-in-progress: false`).
+  When a third concurrent run arrives:
+
+  1. Run A is **in-progress** (held in slot 1).
+  2. Run B is **pending** (held in slot 2, waiting for Run A to finish).
+  3. Run C arrives → GitHub silently cancels Run B to free slot 2, then queues Run C.
+
+  The net effect: Run B is lost. Run C is now pending and will eventually execute.
+  With `cancel-in-progress: false`, *only Run A is protected* from cancellation — not
+  Run B. The arriving run always displaces the previously pending one.
+
+  This surprises developers who read `cancel-in-progress: false` as "let all runs
+  queue and execute in order." The actual semantics are: "don't kill the in-flight
+  run, but still replace any queued-but-not-yet-running run."
+
+  There is no log entry showing Run B was cancelled by Run C's arrival; the cancellation
+  shows as "This run was cancelled" with no attribution.
+
+  To allow more than 1 pending run, use `queue: max` (up to 100 pending slots) — but
+  note that `queue: max` and `cancel-in-progress: true` cannot be combined.
+fix: |
+  Choose the concurrency strategy that matches your desired behavior:
+
+  **Option 1 — Allow up to 100 queued runs (strict ordering, no drops):**
+  Use `queue: max`. Every run is preserved and executes in arrival order. The 101st
+  concurrent run silently cancels the oldest pending run (see concurrency-timing-058
+  for the queue:max overflow edge case).
+
+  **Option 2 — Cancel stale runs, always run the latest (most common for CI):**
+  Use `cancel-in-progress: true`. Stale pending runs are cancelled; only the most
+  recent push/dispatch runs.
+
+  **Option 3 — Fine-grained concurrency keys to prevent grouping:**
+  Include `github.sha` or `github.run_id` in the group key so each run gets its own
+  isolated slot and nothing is ever cancelled or queued against another run.
+
+  **Option 4 — Accept the default behavior:**
+  Understand that `cancel-in-progress: false` means 1-active + 1-pending, and design
+  your pipeline around this. For example, if you need every commit tested, use
+  `cancel-in-progress: true` so you always test the latest commit, or `queue: max`
+  if you need every commit tested in order.
+fix_code:
+  - language: yaml
+    label: 'Broken — cancel-in-progress: false does NOT queue all runs; 3rd run drops 2nd'
+    code: |
+      on: push
+
+      concurrency:
+        group: deploy-${{ github.ref }}
+        cancel-in-progress: false   # ❌ Only protects the in-progress run (slot 1)
+                                    # ❌ Slot 2 (pending) is still replaced when a 3rd run arrives
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - run: ./deploy.sh
+
+  - language: yaml
+    label: 'Fixed — use queue: max to preserve all pending runs (up to 100)'
+    code: |
+      on: push
+
+      concurrency:
+        group: deploy-${{ github.ref }}
+        queue: max    # ✅ Up to 100 pending runs preserved, executed in order
+                      # ✅ No run is silently dropped until the 101st arrives
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - run: ./deploy.sh
+
+  - language: yaml
+    label: 'Alternative — cancel stale runs, keep only the latest (typical CI pattern)'
+    code: |
+      on: push
+
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.ref }}
+        cancel-in-progress: true   # ✅ Latest commit always runs; stale runs cancelled
+
+      jobs:
+        ci:
+          runs-on: ubuntu-latest
+          steps:
+            - run: ./test.sh
+
+  - language: yaml
+    label: 'Alternative — unique key per run (no cancellation, no queueing)'
+    code: |
+      on: push
+
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.run_id }}   # ✅ Each run is isolated
+        cancel-in-progress: false
+
+      jobs:
+        ci:
+          runs-on: ubuntu-latest
+          steps:
+            - run: ./test.sh
+
+prevention:
+  - 'Read `cancel-in-progress: false` as "protect the running job, not all pending jobs."'
+  - 'Use `queue: max` when you need every dispatched run to eventually execute.'
+  - '`queue: max` and `cancel-in-progress: true` cannot be combined — validation error.'
+  - 'Include `github.sha` or `github.run_id` in the group key to give each run its own isolated slot.'
+  - 'Monitor the Actions tab for unexplained cancellations after rapid pushes to confirm you are hitting the 1-pending limit.'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/control-the-concurrency-of-workflows-and-jobs'
+    label: 'GitHub Docs: Control the concurrency of workflows and jobs'
+  - url: 'https://github.com/orgs/community/discussions/5435'
+    label: 'GitHub Community #5435: cancel-in-progress: false still cancels pending runs'
+  - url: 'https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#concurrency'
+    label: 'GitHub Docs: Workflow syntax — concurrency'

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

@@ -0,0 +1,172 @@
+id: known-unsolved-073
+title: '`timeout-minutes:` does not accept expressions — must be a literal integer; variables, inputs, and secrets are unsupported'
+category: known-unsolved
+severity: limitation
+tags:
+  - timeout-minutes
+  - expressions
+  - limitation
+  - no-dynamic-value
+  - job-timeout
+  - step-timeout
+  - vars-context
+patterns:
+  - regex: 'timeout-minutes:\s*\$\{\{'
+    flags: 'i'
+  - regex: 'timeout-minutes.*vars\.|timeout-minutes.*inputs\.|timeout-minutes.*env\.'
+    flags: 'i'
+  - regex: 'Unexpected value.*timeout-minutes|timeout-minutes.*invalid'
+    flags: 'i'
+error_messages:
+  - "The workflow is not valid. .github/workflows/ci.yml (Line: N, Col: M): Unexpected value 'true'"
+  - "timeout-minutes: unexpected value"
+  - "Expected Integer, String"
+root_cause: |
+  The `timeout-minutes:` field at both the **job level** and the **step level** only
+  accepts a **literal integer** (e.g., `30`, `120`). GitHub Actions does not evaluate
+  expressions (`${{ }}`) in this field.
+
+  Attempting to use any of the following will either produce a YAML validation error
+  or silently fall back to the default timeout (6 hours for jobs, unlimited for steps):
+
+  - `timeout-minutes: ${{ vars.JOB_TIMEOUT }}`      — variables context
+  - `timeout-minutes: ${{ inputs.timeout }}`         — inputs context
+  - `timeout-minutes: ${{ env.TIMEOUT_MINUTES }}`    — env context
+  - `timeout-minutes: ${{ 30 * 2 }}`                 — arithmetic expression
+  - `timeout-minutes: ${{ matrix.timeout }}`         — matrix value
+
+  This is a long-standing feature request (actions/runner#1242, opened 2021, 500+
+  reactions) with no official resolution as of June 2026. GitHub's position is that
+  expression support in `timeout-minutes:` is not currently planned.
+
+  actionlint (>=1.6.x) correctly flags `timeout-minutes: ${{ ... }}` as a type error:
+  "type of expression at 'timeout-minutes' must be number but found string type."
+  However, some older actionlint versions or CI linting setups may not catch this,
+  allowing the invalid value to reach production where it silently uses the default.
+
+  Common motivation for wanting dynamic timeouts:
+  - Different environments (staging vs production) need different timeouts.
+  - A reusable workflow caller wants to pass a timeout as an input.
+  - Matrix jobs with different test suites need proportional timeouts.
+  - Organizational policies want to set timeouts via repository variables.
+fix: |
+  There is no native fix — expressions in `timeout-minutes:` are not supported.
+
+  **Workaround 1 — Hardcode multiple job variants with `if:` conditions:**
+  Create separate job definitions for each timeout scenario, each with a hardcoded
+  `timeout-minutes:` and an `if:` condition that selects the appropriate one based
+  on the context. This is verbose but fully supported.
+
+  **Workaround 2 — Use a wrapper script with a timeout command:**
+  Instead of relying on job-level timeout, implement a timeout inside the step's run
+  script using the OS `timeout` command (Linux/macOS) or PowerShell's `Wait-Process`:
+  ```yaml
+  steps:
+    - name: Build with dynamic timeout
+      env:
+        BUILD_TIMEOUT: ${{ vars.BUILD_TIMEOUT_SECONDS || '1800' }}
+      run: timeout "$BUILD_TIMEOUT" ./build.sh
+  ```
+  This gives dynamic timeout behavior but does NOT release the runner immediately —
+  the job continues running (idle) after the script times out until the job-level
+  `timeout-minutes:` (hardcoded) fires.
+
+  **Workaround 3 — Hardcode a generous upper bound:**
+  Set `timeout-minutes:` to the maximum acceptable value for any scenario, and rely
+  on internal script logic to exit early when needed. Ensures the runner is eventually
+  released even in worst-case scenarios.
+
+  **Workaround 4 — For reusable workflows, hardcode per caller:**
+  If a reusable workflow needs caller-specified timeouts, duplicate the job definition
+  per timeout tier or create multiple reusable workflows with different timeouts.
+fix_code:
+  - language: yaml
+    label: 'Does NOT work — expression in timeout-minutes is not supported'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          timeout-minutes: ${{ vars.JOB_TIMEOUT_MINUTES }}   # ❌ Expression not supported
+          steps:
+            - run: ./build.sh
+
+      # Also does NOT work:
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          timeout-minutes: ${{ inputs.timeout || 30 }}        # ❌ inputs not supported here
+          steps:
+            - run: ./test.sh
+
+  - language: yaml
+    label: 'Workaround — use OS timeout command inside step for dynamic behavior'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          timeout-minutes: 60    # ✅ Hardcoded upper bound (releases runner if script hangs)
+          steps:
+            - uses: actions/checkout@v4
+            - name: Build with dynamic timeout from variable
+              env:
+                # Variable in seconds: default 1800 (30 min), override via repo var
+                BUILD_TIMEOUT: ${{ vars.BUILD_TIMEOUT_SECONDS || '1800' }}
+              run: timeout "$BUILD_TIMEOUT" ./build.sh
+              # The job-level 60-minute timeout catches runaway cases
+
+  - language: yaml
+    label: 'Workaround — conditional job variants for different timeout requirements'
+    code: |
+      jobs:
+        build-short:
+          if: ${{ github.event_name == 'pull_request' }}
+          runs-on: ubuntu-latest
+          timeout-minutes: 15    # ✅ Short timeout for PR checks
+          steps:
+            - uses: actions/checkout@v4
+            - run: ./build.sh --quick
+
+        build-full:
+          if: ${{ github.ref == 'refs/heads/main' }}
+          runs-on: ubuntu-latest
+          timeout-minutes: 60    # ✅ Full timeout for main branch builds
+          steps:
+            - uses: actions/checkout@v4
+            - run: ./build.sh --full
+
+  - language: yaml
+    label: 'Reusable workflow workaround — hardcode tiers, expose as separate workflows'
+    code: |
+      # .github/workflows/ci-fast.yml — for PRs
+      on:
+        workflow_call:
+      jobs:
+        ci:
+          runs-on: ubuntu-latest
+          timeout-minutes: 15   # ✅ Fast tier
+          steps:
+            - run: ./ci.sh
+
+      # .github/workflows/ci-full.yml — for main branch
+      on:
+        workflow_call:
+      jobs:
+        ci:
+          runs-on: ubuntu-latest
+          timeout-minutes: 60   # ✅ Full tier
+          steps:
+            - run: ./ci.sh
+
+prevention:
+  - 'Accept that `timeout-minutes:` requires a literal integer — design your timeouts with hardcoded values from the start.'
+  - 'Use actionlint in CI to catch `timeout-minutes: ${{ ... }}` during PR review before it reaches production.'
+  - 'Set `timeout-minutes:` to a safe upper bound to ensure runners are eventually released even when scripts hang.'
+  - 'Use step-level `run: timeout N command` for dynamic per-step timeouts without changing job-level `timeout-minutes:`.'
+  - 'Upvote actions/runner#1242 — expression support in timeout-minutes is a high-demand feature request.'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idtimeout-minutes'
+    label: 'GitHub Docs: Workflow syntax — jobs.<id>.timeout-minutes (literal integer only)'
+  - url: 'https://github.com/actions/runner/issues/1242'
+    label: 'actions/runner#1242: Support expressions in timeout-minutes (500+ reactions, open since 2021)'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepstimeout-minutes'
+    label: 'GitHub Docs: Workflow syntax — jobs.<id>.steps[*].timeout-minutes'

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/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/triggers/triggers-072.yml

@@ -0,0 +1,150 @@
+id: triggers-072
+title: 'Scheduled workflow silently disabled after 60 days of public repository inactivity — distinct from the fork schedule disabling rule'
+category: triggers
+severity: silent-failure
+tags:
+  - schedule
+  - cron
+  - disabled
+  - inactivity
+  - public-repo
+  - silent-disable
+  - 60-days
+patterns:
+  - regex: 'on:\s*\n\s+schedule:'
+    flags: 'im'
+  - regex: 'This workflow was disabled'
+    flags: 'i'
+  - regex: 'Workflow.*disabled.*inactiv'
+    flags: 'i'
+error_messages:
+  - "This workflow was disabled."
+  - "Scheduled workflows are disabled for repositories with no recent activity."
+root_cause: |
+  GitHub automatically disables scheduled (`on: schedule:`) workflows in **public
+  repositories** that have had no activity for more than **60 days**. "Activity"
+  includes pushes, pull requests, issue comments, or other events that generate
+  a repository event payload. Pure time-passing without any interaction does not
+  reset the timer.
+
+  The disabling happens silently:
+  - No email notification is sent to repository owners or workflow authors.
+  - No GitHub notification appears in the repository's notification feed.
+  - The scheduled run simply does not appear in the Actions run history.
+  - The workflow file is not changed — the `on: schedule:` trigger is still present
+    in the YAML, but the schedule is inactive in GitHub's internal scheduler.
+
+  The Actions tab will show the workflow listed but with a note that it has been
+  disabled. The **"Enable workflow"** button must be clicked manually to re-activate it.
+
+  This behavior is separate from the fork schedule-disabling rule (where ALL
+  scheduled workflows are disabled on forked repos regardless of activity). The
+  inactivity rule applies to non-fork public repositories.
+
+  Common scenarios:
+  - Maintenance scripts (e.g., weekly dependency updates, cleanup jobs) in repos
+    that receive no push activity between runs.
+  - Documentation or static-site repos where content is rarely updated but a nightly
+    build/deploy workflow is expected to run.
+  - Monitoring or alerting workflows in repos with no other CI triggers.
+  - Open-source libraries with stable codebases and monthly or quarterly releases.
+fix: |
+  **Immediate fix:** Navigate to the repository → Actions tab → find the disabled
+  workflow → click "Enable workflow."
+
+  **Prevent future silent disabling — Option 1 (Recommended): Add a dummy commit
+  or workflow_dispatch trigger:**
+  Add `workflow_dispatch:` to the workflow so it can be triggered manually and also
+  resets the inactivity timer. Then use `gh workflow run` or the UI to manually
+  trigger it if needed.
+
+  **Prevent future silent disabling — Option 2: Artificially keep the repo active:**
+  Add a companion workflow that runs on schedule and updates a file (e.g., a
+  `last-run.txt` with the current timestamp) via a commit. This creates repository
+  activity and resets the 60-day timer. Warning: this generates commit noise.
+
+  **Prevent future silent disabling — Option 3: Convert to a self-hosted or
+  external scheduler:**
+  Use an external cron service (e.g., a cron job in a cloud provider) to trigger
+  the workflow via `workflow_dispatch` or `repository_dispatch`. External triggers
+  count as activity and keep the workflow enabled.
+
+  **Long-term design:** For workflows that are truly meant to run on a schedule
+  without any other repo activity, always add `workflow_dispatch:` as a co-trigger.
+  This makes the workflow manually invocable AND provides a path to re-enable it if
+  it is ever silently disabled.
+fix_code:
+  - language: yaml
+    label: 'At-risk — schedule-only workflow in a low-activity public repo'
+    code: |
+      # ⚠ This workflow will be silently disabled after 60 days with no repo activity
+      name: Weekly Dependency Update
+
+      on:
+        schedule:
+          - cron: '0 9 * * 1'   # Every Monday at 09:00 UTC
+
+      jobs:
+        update:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm update && npm audit fix
+
+  - language: yaml
+    label: 'Fixed — add workflow_dispatch to keep the workflow manageable and prevent inactivity disable'
+    code: |
+      name: Weekly Dependency Update
+
+      on:
+        schedule:
+          - cron: '0 9 * * 1'   # Every Monday at 09:00 UTC
+        workflow_dispatch:       # ✅ Allows manual trigger; manual runs also reset the inactivity timer
+
+      jobs:
+        update:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm update && npm audit fix
+
+  - language: yaml
+    label: 'Alternative — heartbeat workflow that commits a timestamp to keep the repo active'
+    code: |
+      name: Activity Heartbeat (prevents schedule auto-disable)
+
+      on:
+        schedule:
+          - cron: '0 0 * * 0'   # Every Sunday midnight UTC — reset 60-day timer
+        workflow_dispatch:
+
+      permissions:
+        contents: write
+
+      jobs:
+        heartbeat:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - name: Update heartbeat timestamp
+              run: |
+                echo "$(date -u +%Y-%m-%dT%H:%M:%SZ)" > .github/heartbeat.txt
+                git config user.name 'github-actions[bot]'
+                git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
+                git add .github/heartbeat.txt
+                git diff --staged --quiet || git commit -m 'chore: activity heartbeat [skip ci]'
+                git push
+
+prevention:
+  - 'Always add `workflow_dispatch:` alongside `on: schedule:` for any workflow that should run reliably in a low-activity repo.'
+  - 'Check the Actions tab after a period of low repository activity to verify scheduled workflows are still enabled.'
+  - 'The 60-day inactivity rule applies to non-fork public repositories — private repos are NOT subject to this rule.'
+  - 'This is distinct from the fork schedule-disabling rule: forks disable schedules immediately on fork creation, not after inactivity.'
+  - 'Set up a GitHub Actions alert or monitoring workflow that notifies you if expected scheduled runs stop appearing.'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#schedule'
+    label: 'GitHub Docs: Events that trigger workflows — schedule (inactivity disable note)'
+  - url: 'https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/disabling-and-enabling-a-workflow'
+    label: 'GitHub Docs: Disabling and enabling a workflow'
+  - url: 'https://github.com/orgs/community/discussions/134086'
+    label: 'GitHub Community #134086: Scheduled workflows not running — inactivity disable reports'

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.125",
+  "version": "1.0.127",
   "description": "65+ real GitHub Actions errors, queryable by agents. CLI + MCP server + Copilot skills + error database.",
   "type": "module",
   "main": "./dist/index.js",