@htekdev/actions-debugger 1.0.15 → 1.0.16

package/errors/caching-artifacts/cache-save-same-key-html-conflict.yml

@@ -0,0 +1,109 @@
+id: caching-artifacts-020
+title: "actions/cache save fails with HTML error when identical key already exists for same ref"
+category: caching-artifacts
+severity: warning
+tags:
+  - cache
+  - cache-save
+  - 409-conflict
+  - pr-ref
+  - retry-loop
+  - key-collision
+patterns:
+  - regex: "Attempt \\d+ of \\d+ failed with error.*Unexpected token '<'"
+    flags: "i"
+  - regex: "cache.*already exists.*ref|key.*already.*saved.*ref"
+    flags: "i"
+  - regex: "Unexpected token '<'.*DOCTYPE|<!DOCTYPE.*cache"
+    flags: "im"
+error_messages:
+  - "Attempt 1 of 5 failed with error: Unexpected token '<', \"<!DOCTYPE ...\" is not valid JSON"
+  - "Failed to save: Unexpected token '<'"
+  - "Attempt 5 of 5 failed with error: Unexpected token '<'"
+root_cause: |
+  actions/cache v3 and v4 use the GitHub cache service to save cache entries
+  scoped to a key + ref combination. When a workflow run saves a cache entry
+  under a given key for refs/pull/N/merge, subsequent runs against the same
+  PR ref that produce the EXACT same cache key will attempt to save again.
+
+  The cache service rejects the duplicate write with an HTTP 409 response.
+  However, the response body is an HTML error page rather than a JSON error
+  object. The cache toolkit's retry logic does not recognize the HTML response
+  as a permanent, non-retryable conflict — it treats it as a transient network
+  error and retries up to 5 times with exponential backoff (~20-30 seconds
+  total wasted time before all attempts are exhausted).
+
+  The cache entry itself is not updated or overwritten (actions/cache v4 uses
+  immutable cache entries), but the 5-retry failure loop causes the post-job
+  cleanup step to report errors in the workflow log, adding noise and wasted
+  time to every successive commit pushed to a long-lived PR branch.
+
+  This is most visible in actions that use deterministic, content-addressed
+  cache keys (e.g., a Bun binary cache keyed on its checksum) where every
+  run produces the same key for the same PR.
+fix: |
+  Add a dynamic component to the cache key that changes between runs so that
+  consecutive runs on the same PR ref never attempt to save over an existing
+  entry. Using ${{ github.run_id }} or ${{ github.run_attempt }} as part of
+  the key ensures each run gets a unique save slot.
+
+  If you specifically want a stable cache that all runs on a PR share (only
+  save once), use restore-keys for lookup and add a save condition so the
+  save step only runs when a cache miss occurred:
+
+    if: steps.cache.outputs.cache-hit != 'true'
+
+  For large dependency caches, prefer restore-keys with a prefix approach so
+  partial hits are possible and saves only happen when the lockfile changes.
+fix_code:
+  - language: yaml
+    label: "Use restore-keys + conditional save to avoid same-key conflicts"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Cache Bun binary
+              id: bun-cache
+              uses: actions/cache@v4
+              with:
+                path: ~/.bun/install/cache
+                # Lock file hash in key + restore-keys for partial fallback
+                key: ${{ runner.os }}-bun-${{ hashFiles('bun.lockb') }}
+                restore-keys: |
+                  ${{ runner.os }}-bun-
+
+            # Only save if there was a cache miss — avoids HTML 409 on same PR
+            - name: Save Bun cache (miss only)
+              if: steps.bun-cache.outputs.cache-hit != 'true'
+              uses: actions/cache/save@v4
+              with:
+                path: ~/.bun/install/cache
+                key: ${{ steps.bun-cache.outputs.cache-primary-key }}
+  - language: yaml
+    label: "Include run_id in cache key to guarantee a unique save slot per run"
+    code: |
+      - uses: actions/cache@v4
+        with:
+          path: .build/
+          # run_id makes every run's save unique — no 409 conflicts
+          key: ${{ runner.os }}-build-${{ hashFiles('**/*.go') }}-${{ github.run_id }}
+          restore-keys: |
+            ${{ runner.os }}-build-${{ hashFiles('**/*.go') }}-
+            ${{ runner.os }}-build-
+prevention:
+  - "Use restore-keys for cache lookup and actions/cache/save with an if: cache-hit != 'true' guard to skip redundant saves"
+  - "Avoid fully deterministic cache keys that never change between runs on the same PR; add a per-run or per-lockfile component"
+  - "Treat 'Unexpected token <' in cache post-job as a 409 key-collision signal, not a network error"
+  - "Use actions/cache v4's separate save/restore actions for fine-grained control over when saves actually occur"
+docs:
+  - url: "https://github.com/actions/cache"
+    label: "actions/cache — GitHub Actions cache action documentation"
+  - url: "https://github.com/actions/cache/blob/main/tips-and-workarounds.md"
+    label: "actions/cache — Tips and workarounds (immutability, restore-keys)"
+  - url: "https://github.com/anthropics/claude-code-action/issues/1252"
+    label: "anthropics/claude-code-action#1252 — Cache save HTML 409 on same PR ref"
+  - url: "https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows#restrictions-for-accessing-a-cache"
+    label: "GitHub Docs — Cache restrictions and immutability"

package/errors/caching-artifacts/upload-artifact-v4-large-file-macos-hang.yml

@@ -0,0 +1,111 @@
+id: caching-artifacts-021
+title: "upload-artifact v4 Silently Hangs on Large Files (500MB+) on macOS Runners"
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - upload-artifact
+  - macos
+  - large-file
+  - hang
+  - timeout
+  - silent-failure
+  - v4
+patterns:
+  - regex: "Uploaded bytes \\d+"
+    flags: "i"
+  - regex: "upload-artifact.*stall|stall.*upload-artifact"
+    flags: "i"
+  - regex: "The operation was cancelled.*upload|upload.*operation was cancelled"
+    flags: "i"
+  - regex: "Error: The process.*took too long.*upload-artifact"
+    flags: "i"
+error_messages:
+  - "Uploaded bytes 8388608"
+  - "The runner has received a shutdown signal. This can happen when the runner service is stopped, or a manually started runner is canceled."
+root_cause: |
+  `actions/upload-artifact@v4` intermittently stalls during upload on macOS GitHub-hosted
+  runners (macos-13-xl-arm64, macos-14-xlarge, macos-15) when artifact size is approximately
+  500 MB or larger. The stall manifests as the upload progress halting after logging "Uploaded
+  bytes XXXXXXXXX" with no further output — the job then exceeds its timeout and is cancelled
+  by GitHub without an explicit error message.
+
+  This behavior was reported and tracked in actions/upload-artifact#527. The hang appears
+  intermittent (roughly 30–50% failure rate for affected workflows), which makes it difficult
+  to diagnose in standard CI logs — the workflow shows as "cancelled" rather than "failed",
+  masking the root cause.
+
+  Contributing factors observed in community reports:
+  - Large uncompressed artifacts (binaries, build artifacts, test reports with raw data)
+  - macOS ARM64 hosted runners appear more susceptible than Linux or Windows runners
+  - Compression level settings do not consistently prevent the hang
+
+  This is a silent failure because:
+  1. The upload simply stops with no error log entry
+  2. The job shows as "cancelled" (not "failed") in the GitHub UI
+  3. Downstream artifact-download steps fail with "no artifact found" — the real cause is upstream
+fix: |
+  Use one or more of these mitigations while the issue is tracked by the actions team:
+
+  1. **Split large artifacts**: Break large upload paths into multiple smaller upload steps, each
+     under ~200MB. This reduces the risk of hitting the hang threshold.
+
+  2. **Add an explicit timeout**: Set `timeout-minutes` on the upload step to detect hangs faster
+     and fail with a clear error rather than waiting for the job-level timeout.
+
+  3. **Retry the upload**: Wrap the upload step in a retry loop or use a community action like
+     `nick-fields/retry` to automatically re-attempt on failure.
+
+  4. **Use direct storage for very large artifacts**: For artifacts over 1GB, upload directly to
+     S3, Azure Blob Storage, or GCS using provider CLI tools. Use upload-artifact only for test
+     reports and smaller build outputs.
+
+  5. **Switch to Linux runners**: If macOS-specific features are not required for the upload
+     phase, run artifact collection on an ubuntu-latest runner where the hang does not occur.
+fix_code:
+  - language: yaml
+    label: "Add timeout and retry to upload step"
+    code: |
+      - name: Upload large artifact
+        uses: actions/upload-artifact@v4
+        timeout-minutes: 10   # fail fast instead of waiting for job timeout
+        with:
+          name: release-binaries
+          path: dist/
+          compression-level: 6
+          retention-days: 7
+  - language: yaml
+    label: "Split large artifact into parts to reduce hang risk"
+    code: |
+      - name: Upload binaries (part 1)
+        uses: actions/upload-artifact@v4
+        with:
+          name: binaries-part1
+          path: dist/platform-a/
+
+      - name: Upload binaries (part 2)
+        uses: actions/upload-artifact@v4
+        with:
+          name: binaries-part2
+          path: dist/platform-b/
+  - language: yaml
+    label: "Upload to S3 for very large artifacts (bypass upload-artifact)"
+    code: |
+      - name: Upload large artifact to S3
+        env:
+          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
+          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+        run: |
+          aws s3 cp dist/release.tar.gz s3://my-bucket/artifacts/${{ github.sha }}/release.tar.gz
+          echo "Uploaded to s3://my-bucket/artifacts/${{ github.sha }}/release.tar.gz"
+prevention:
+  - "Keep individual artifact uploads under 200MB per upload step on macOS runners to avoid the hang threshold."
+  - "Always set `timeout-minutes` on upload steps for large files so the CI job fails fast with a clear error instead of silently timing out."
+  - "Monitor for `cancelled` status on jobs that use upload-artifact on macOS — these may be silently failing uploads."
+  - "For release artifacts exceeding 1GB, use cloud storage (S3, Azure Blob, GCS) directly rather than upload-artifact."
+docs:
+  - url: "https://github.com/actions/upload-artifact/issues/527"
+    label: "actions/upload-artifact#527 — macOS large-file upload hang report and discussion"
+  - url: "https://github.com/actions/upload-artifact"
+    label: "actions/upload-artifact — official repository and documentation"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/storing-workflow-data-as-artifacts"
+    label: "GitHub Docs — storing workflow data as artifacts"

package/errors/known-unsolved/workflow-50-rerun-limit.yml

@@ -0,0 +1,110 @@
+id: known-unsolved-018
+title: "Workflow rerun limit of 50 exceeded — subsequent reruns fail permanently"
+category: known-unsolved
+severity: limitation
+tags:
+  - rerun
+  - retry
+  - automation
+  - limits
+  - platform-limit
+patterns:
+  - regex: "exceeded.*maximum.*reruns|maximum.*reruns.*exceeded"
+    flags: "i"
+  - regex: "rerun limit.*50|50.*rerun limit"
+    flags: "i"
+  - regex: "This workflow run was cancelled because it exceeded"
+    flags: "i"
+error_messages:
+  - "This workflow run exceeded the limit of 50 reruns"
+  - "exceeded the maximum number of reruns (50)"
+  - "Cannot rerun this workflow: rerun limit reached"
+root_cause: |
+  Since April 10, 2026, GitHub Actions enforces a hard limit of 50 reruns
+  per individual workflow run (counting both full reruns and re-runs of
+  individual job subsets). Once a workflow run reaches 50 attempts, any
+  further rerun request — whether triggered manually, via the GitHub CLI,
+  the REST API, or an automated rerun action — will fail with an error
+  annotation on the check suite.
+
+  The limit was introduced to stop automation patterns that use infinite-retry
+  loops (e.g., rerunning every failed job automatically, retrying flaky
+  infrastructure hundreds of times) from adding excessive load to GitHub's
+  infrastructure. The count is tied to the original workflow run ID — creating
+  a new workflow run by re-pushing or re-dispatching does NOT inherit the
+  count.
+
+  This limitation is most frequently encountered by:
+  - Flaky test environments that rely on automated rerun tooling
+    (k1LoW/rerun-action, lewagon/retry-workflow-action, etc.)
+  - Long-running deployment pipelines with retry-until-success patterns
+  - Teams using merge queues or merge trains that auto-requeue failed checks
+  - Internal automation that retries status checks repeatedly against a PR
+
+  There is no way to exceed this limit — it is enforced server-side with no
+  configuration option. The only resolution is to trigger a fresh workflow run.
+fix: |
+  There is no way to raise or bypass the 50-rerun limit. Mitigation strategies:
+
+  1. Fix the underlying flakiness so retries are rare (<50 per workflow run).
+  2. Trigger a fresh workflow run rather than retrying the same run ID:
+     - Re-push to the branch or rebase (creates new push event → new run)
+     - For pull_request: close and reopen the PR (creates new run ID)
+     - For workflow_dispatch: dispatch again (creates a completely new run)
+  3. Redesign retry logic to use a separate `workflow_run` triggered workflow
+     that dispatches a NEW workflow instead of rerunning the same one.
+  4. For flaky infra: fix at the infra layer (idempotent step design, retry
+     at the shell/script level within a single attempt) rather than rerunning
+     the entire workflow.
+fix_code:
+  - language: yaml
+    label: "Use shell-level retry for flaky steps instead of workflow-level rerun"
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Flaky deploy step with shell retry
+              run: |
+                # Retry up to 5 times with 30s backoff — no workflow rerun needed
+                for i in 1 2 3 4 5; do
+                  echo "Attempt $i..."
+                  ./scripts/deploy.sh && break || {
+                    if [ $i -lt 5 ]; then
+                      echo "Deploy failed, retrying in 30s..."
+                      sleep 30
+                    else
+                      echo "All $i attempts failed"
+                      exit 1
+                    fi
+                  }
+                done
+  - language: yaml
+    label: "Dispatch a new workflow run instead of rerunning the same run"
+    code: |
+      # If you need automated rerun logic, trigger a fresh dispatch
+      # rather than using gh run rerun (which increments the rerun counter)
+      jobs:
+        retry-via-dispatch:
+          runs-on: ubuntu-latest
+          if: failure()
+          steps:
+            - name: Trigger fresh run via workflow_dispatch
+              run: |
+                gh workflow run ci.yml \
+                  --ref ${{ github.ref }} \
+                  --field triggered_by=auto-retry
+              env:
+                GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+prevention:
+  - "Treat workflow reruns as a debugging tool, not a reliability mechanism — fix flakiness at the source"
+  - "Use shell-level retry loops (for loop with sleep) for individual steps that are inherently flaky"
+  - "Use workflow_dispatch to start a fresh run rather than rerunning the same run ID when automation needs to retry"
+  - "Monitor workflows that regularly exceed 5 reruns — they signal a deeper reliability problem that needs fixing"
+docs:
+  - url: "https://github.blog/changelog/2026-04-10-actions-workflows-are-limited-to-50-reruns/"
+    label: "GitHub Changelog — Actions workflows are limited to 50 reruns (Apr 2026)"
+  - url: "https://docs.github.com/en/actions/managing-workflow-runs/re-running-workflows-and-jobs"
+    label: "GitHub Docs — Re-running workflows and jobs"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_dispatch"
+    label: "GitHub Docs — workflow_dispatch event"

package/errors/permissions-auth/check-run-status-modification-blocked.yml

@@ -0,0 +1,134 @@
+id: permissions-auth-018
+title: "GITHUB_TOKEN cannot modify check run status or conclusion after March 2025"
+category: permissions-auth
+severity: error
+tags:
+  - check-runs
+  - github-token
+  - checks-api
+  - permissions
+  - breaking-change
+patterns:
+  - regex: "Check run status and conclusions can only be updated internally by GitHub Actions"
+    flags: "i"
+  - regex: "check_run.*status.*conclusion.*updated internally"
+    flags: "i"
+  - regex: "Changes to check run status modification"
+    flags: "i"
+error_messages:
+  - "Error: Check run status and conclusions can only be updated internally by GitHub Actions. Please see https://github.blog/changelog/2025-02-12-notice-of-upcoming-deprecations-and-breaking-changes-for-github-actions/#changes-to-check-run-status-modification"
+  - "Check run status and conclusions can only be updated internally by GitHub Actions"
+root_cause: |
+  GitHub deprecated external modification of check run status and conclusion
+  fields on March 31, 2025. Prior to this change, workflows and third-party
+  actions (e.g., LouisBrunner/checks-action, custom Checks API calls) could
+  use the repository's GITHUB_TOKEN to call the REST API and update the status
+  (queued, in_progress, completed) or conclusion (success, failure, etc.) of
+  an existing check run that was originally created by GitHub Actions.
+
+  GitHub blocked this pattern to prevent confusion and race conditions that
+  could arise when external code overwrote the status of a check run that
+  GitHub Actions was still managing. Starting March 31, 2025, any attempt
+  to PATCH an existing Actions-created check run's status or conclusion via
+  GITHUB_TOKEN returns an error.
+
+  This affects:
+  - Actions that wrap the GitHub Checks API to create multi-step annotations
+    (e.g., LouisBrunner/checks-action)
+  - Custom workflows that read a check_run ID from a prior step and patch it
+  - External tooling that patches check run state using the built-in token
+  - Any pattern where one step creates a check run and a later step or job
+    tries to set it to "completed"
+
+  Check runs that were NOT created by GitHub Actions (created via a GitHub App
+  or OAuth token) are not affected and can still be updated by their creator.
+fix: |
+  Workflows that need to update check run status or conclusion must create
+  those check runs with a non-GITHUB_TOKEN credential so that the same
+  credential can also update them later.
+
+  Option 1 (GitHub App): Use actions/create-github-app-token to generate an
+  installation token and create check runs with that token. The same GitHub App
+  token can then update the check runs it created.
+
+  Option 2 (Remove update steps): If the check run is only being updated to
+  mark it "completed" at the end of a job, let GitHub Actions manage the
+  conclusion automatically. Remove the final PATCH step.
+
+  Option 3 (Migrate to annotations): Replace custom check run status tracking
+  with GitHub Actions step annotations (::notice::, ::warning::, ::error::).
+  These use the workflow's built-in UI and require no Checks API calls.
+fix_code:
+  - language: yaml
+    label: "Create and update check runs using a GitHub App installation token"
+    code: |
+      jobs:
+        annotate:
+          runs-on: ubuntu-latest
+          permissions:
+            # id-token:write needed if using OIDC-based App token
+            contents: read
+          steps:
+            - name: Generate GitHub App token
+              id: app-token
+              uses: actions/create-github-app-token@v2
+              with:
+                app-id: ${{ vars.CHECKS_APP_ID }}
+                private-key: ${{ secrets.CHECKS_APP_PRIVATE_KEY }}
+
+            - name: Create check run
+              id: create-check
+              uses: actions/github-script@v7
+              with:
+                github-token: ${{ steps.app-token.outputs.token }}
+                script: |
+                  const { data } = await github.rest.checks.create({
+                    owner: context.repo.owner,
+                    repo: context.repo.repo,
+                    name: 'My Custom Check',
+                    head_sha: context.sha,
+                    status: 'in_progress',
+                  });
+                  return data.id;
+
+            - name: Do work...
+              run: echo "running checks..."
+
+            - name: Update check run to completed
+              uses: actions/github-script@v7
+              with:
+                # Use the App token — NOT github.token — to update the check
+                github-token: ${{ steps.app-token.outputs.token }}
+                script: |
+                  await github.rest.checks.update({
+                    owner: context.repo.owner,
+                    repo: context.repo.repo,
+                    check_run_id: ${{ steps.create-check.outputs.result }},
+                    status: 'completed',
+                    conclusion: 'success',
+                  });
+  - language: yaml
+    label: "Use built-in step annotations instead of custom check runs"
+    code: |
+      - name: Emit warning annotation
+        run: echo "::warning file=src/main.js,line=42::Deprecated API usage detected"
+
+      - name: Emit error annotation (fails step)
+        run: echo "::error title=Lint Failed::3 lint violations found in src/"
+
+      # These annotations appear in the workflow summary and PR checks UI
+      # without any Checks API calls or external tokens
+prevention:
+  - "Never use GITHUB_TOKEN to PATCH the status or conclusion of an Actions-created check run"
+  - "Create custom check runs using a GitHub App installation token so the same credential owns them end-to-end"
+  - "Prefer built-in step annotations (::warning::, ::error::) over custom Checks API calls for simple annotation needs"
+  - "Audit third-party actions that wrap the Checks API (e.g., LouisBrunner/checks-action) for compatibility with the March 2025 change"
+docs:
+  - url: "https://github.blog/changelog/2025-02-12-notice-of-upcoming-deprecations-and-breaking-changes-for-github-actions/#changes-to-check-run-status-modification"
+    label: "GitHub Changelog — Changes to check run status modification (Feb 2025)"
+  - url: "https://docs.github.com/en/rest/checks/runs"
+    label: "GitHub REST API — Check Runs"
+  - url: "https://github.com/LouisBrunner/checks-action/issues/369"
+    label: "LouisBrunner/checks-action#369 — Error after March 2025 enforcement"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#setting-a-warning-message"
+    label: "GitHub Docs — Workflow commands for annotations"

package/errors/runner-environment/macos-13-deprecation-brownout.yml

@@ -0,0 +1,93 @@
+id: runner-environment-050
+title: "macOS 13 Runner Deprecated and Removed — Jobs Fail During Brownout Windows"
+category: runner-environment
+severity: error
+tags:
+  - macos-13
+  - runner-deprecation
+  - brownout
+  - migration
+  - macos-14
+  - runner-images
+patterns:
+  - regex: "The label 'macos-13' is not present on any runner"
+    flags: "i"
+  - regex: "No runner matching the specified labels was found.*macos-13"
+    flags: "i"
+  - regex: "macos-13.*deprecated|deprecated.*macos-13"
+    flags: "i"
+  - regex: "Request 'macos-13'.*could not be satisfied"
+    flags: "i"
+error_messages:
+  - "The label 'macos-13' is not present on any runner"
+  - "No runner matching the specified labels was found: macos-13"
+root_cause: |
+  GitHub deprecated and eventually removed the `macos-13` and `macos-13-xlarge` runner labels
+  in 2025 (announced in runner-images#13046). GitHub applied brownout windows before full removal:
+  during these windows the macOS 13 label is temporarily unavailable and any job requesting it
+  either hangs waiting for a runner or immediately fails with a "label not present" error.
+
+  After the final retirement date, the label is gone entirely. The retirement schedule followed
+  the same brownout → retirement pattern used for Ubuntu 20.04 and Windows 2019.
+
+  Common workflows affected:
+  - iOS/macOS app CI that pinned to `macos-13` for Xcode 15 compatibility
+  - Workflows that avoided `macos-14` (Apple Silicon) due to architecture differences
+  - Repos that never updated after initially picking `macos-13` at release time
+fix: |
+  Migrate `runs-on: macos-13` to a supported macOS label. Recommended choices:
+
+  - `macos-latest` — automatically follows GitHub's current default (tracks major version bumps)
+  - `macos-15` — macOS 15 Sequoia, ARM64 (Apple Silicon), Xcode 16+
+  - `macos-14` — macOS 14 Sonoma, ARM64 (Apple Silicon), well-supported
+  - `macos-15-intel` or `macos-14-large` — for workflows requiring x86-64 architecture
+
+  Note: macOS 14+ runners are ARM64 by default. If your build toolchain requires x86-64, use
+  an explicitly-labeled Intel variant. Test Homebrew packages, build scripts, and any binary
+  tools on the new architecture before fully migrating.
+fix_code:
+  - language: yaml
+    label: "Migrate from macos-13 to macos-15 (ARM64)"
+    code: |
+      jobs:
+        build:
+          # Before: runs-on: macos-13
+          runs-on: macos-15   # macOS 15 Sequoia, ARM64, Xcode 16+
+          steps:
+            - uses: actions/checkout@v4
+            - name: Build and test
+              run: xcodebuild test -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 16'
+  - language: yaml
+    label: "Use macos-latest for automatic version tracking"
+    code: |
+      jobs:
+        build:
+          runs-on: macos-latest   # tracks GitHub's current recommended version
+          steps:
+            - uses: actions/checkout@v4
+            - name: Build
+              run: swift build
+  - language: yaml
+    label: "Matrix testing across macOS versions"
+    code: |
+      jobs:
+        test:
+          strategy:
+            matrix:
+              os: [macos-14, macos-15]
+          runs-on: ${{ matrix.os }}
+          steps:
+            - uses: actions/checkout@v4
+            - run: swift test
+prevention:
+  - "Subscribe to runner-images announcements to learn about deprecation timelines before brownout windows start."
+  - "Use `macos-latest` when your workflow does not require a specific OS version — it automatically follows GitHub's supported default."
+  - "Test on the new image in a feature branch before the official retirement date to catch Xcode, SDK, or toolchain differences."
+  - "For x86-64-specific toolchains, check whether an Intel variant label is available before the migration deadline."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/13046"
+    label: "runner-images#13046 — macOS 13 deprecation and brownout schedule"
+  - url: "https://github.com/actions/runner-images/releases"
+    label: "runner-images releases — current supported macOS image versions"
+  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners"
+    label: "GitHub Docs — supported GitHub-hosted runner labels"

package/errors/runner-environment/multi-runtime-nov2025-removal.yml

@@ -0,0 +1,120 @@
+id: runner-environment-051
+title: "Node.js 18, Ruby 3.1, Android NDK 26, GCC 9/10 Removed from Runner Images (Nov 2025)"
+category: runner-environment
+severity: error
+tags:
+  - nodejs-18
+  - ruby-31
+  - android-ndk
+  - gcc
+  - tool-removal
+  - ubuntu
+  - runner-images
+  - eol
+patterns:
+  - regex: "node: command not found|node: not found"
+    flags: "i"
+  - regex: "ruby: command not found|ruby: not found"
+    flags: "i"
+  - regex: "ndk-build: command not found|NDK.*not found"
+    flags: "i"
+  - regex: "gcc-9: command not found|gcc-10: command not found|g\\+\\+-9: command not found"
+    flags: "i"
+  - regex: "Could not find the requested version of Node.*18"
+    flags: "i"
+error_messages:
+  - "node: command not found"
+  - "ruby: command not found"
+  - "ndk-build: command not found"
+  - "gcc-9: command not found"
+  - "gcc-10: command not found"
+  - "Could not find the requested version of Node 18"
+root_cause: |
+  In November 2025, GitHub removed several EOL (end-of-life) tool versions from the preinstalled
+  toolcache of Ubuntu and Windows runner images as part of their scheduled tool maintenance policy
+  (announced in runner-images#12898). The removals included:
+
+  - **Node.js 18** — reached EOL April 2025; removed from toolcache November 2025
+  - **Ruby 3.1** — reached EOL March 2025; removed from toolcache November 2025
+  - **Android NDK 26** — superseded by NDK 27/28; removed from images November 2025
+  - **GCC 9 and GCC 10** — superseded by GCC 11+; removed from Ubuntu images November 2025
+
+  Workflows that assumed these runtimes were preinstalled either fail with `command not found`
+  (if the tool was used without an explicit setup step) or fail during the setup action phase
+  (if a setup action is used but the requested version is no longer in the toolcache and
+  compilation from source fails in the time limit).
+
+  This is a particularly common failure pattern for:
+  - Legacy Android NDK builds using exact NDK version pinning
+  - Older Ruby gems/Fastlane pipelines that required Ruby 3.1 specifically
+  - C/C++ projects that specified `gcc-9` or `gcc-10` explicitly in their Makefiles or CMake configs
+  - Any workflow that ran `node --version` expecting v18.x without a prior setup-node step
+fix: |
+  Explicitly install the required runtime version in the workflow using the appropriate setup
+  action, or migrate to a supported version that remains preinstalled on the runner.
+
+  **Node.js 18 → Node.js 22 (LTS):**
+  Upgrade to Node.js 22 (currently LTS) or at minimum Node.js 20 if v18-specific behavior
+  is required. Use `actions/setup-node` for explicit installation.
+
+  **Ruby 3.1 → Ruby 3.3+:**
+  Use `ruby/setup-ruby` to explicitly pin any Ruby version. Ruby 3.3 is the current stable release.
+
+  **Android NDK 26 → NDK 27/28:**
+  Update `ndk-version` in `actions/setup-android` or manually install the required NDK version
+  via the Android SDK manager.
+
+  **GCC 9/10 → GCC 12+:**
+  Use `apt-get install gcc-12 g++-12` or update your Makefile/CMake to target a supported GCC
+  version (GCC 11, 12, 13 remain available on Ubuntu 22.04 runners).
+fix_code:
+  - language: yaml
+    label: "Explicitly install Node.js 18 (or upgrade to 22)"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-node@v4
+              with:
+                node-version: '22'   # or '18' to pin if still needed
+                cache: 'npm'
+            - run: npm ci && npm test
+  - language: yaml
+    label: "Install a specific Ruby version via setup-ruby"
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - uses: ruby/setup-ruby@v1
+              with:
+                ruby-version: '3.3'   # pin explicitly; never rely on preinstalled ruby
+                bundler-cache: true
+            - run: bundle exec rspec
+  - language: yaml
+    label: "Install GCC 9 explicitly on Ubuntu (for legacy C++ code)"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-22.04   # Ubuntu 22.04 still has apt packages for gcc-9
+          steps:
+            - uses: actions/checkout@v4
+            - run: sudo apt-get install -y gcc-9 g++-9
+            - run: make CC=gcc-9 CXX=g++-9
+prevention:
+  - "Never assume a specific tool version is preinstalled. Always add an explicit setup step (`setup-node`, `setup-ruby`, `setup-android`) with a pinned version."
+  - "Subscribe to runner-images announcements and act before the removal deadline — GitHub typically gives 3-6 months notice."
+  - "Use the [runner-images software lists](https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2204-Readme.md) to verify which versions are available before assuming they exist."
+  - "When a CI tool version is EOL, plan the upgrade at EOL time — not when GitHub removes it from the runner."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/12898"
+    label: "runner-images#12898 — Nov 2025 tool removals announcement (Node 18, Ruby 3.1, NDK 26, GCC 9/10)"
+  - url: "https://github.com/actions/setup-node"
+    label: "actions/setup-node — explicitly install any Node.js version"
+  - url: "https://github.com/ruby/setup-ruby"
+    label: "ruby/setup-ruby — install any Ruby version"
+  - url: "https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2204-Readme.md"
+    label: "runner-images — Ubuntu 22.04 software list (verify what is preinstalled)"

package/errors/runner-environment/ubuntu-2004-retirement-brownout.yml

@@ -0,0 +1,107 @@
+id: runner-environment-049
+title: "ubuntu-20.04 runner retired — jobs fail during brownouts or after full removal"
+category: runner-environment
+severity: error
+tags:
+  - ubuntu
+  - ubuntu-20-04
+  - runner-retirement
+  - image-removal
+  - brownout
+  - eol
+patterns:
+  - regex: "scheduled Ubuntu 20\\.04 retirement|Ubuntu 20\\.04.*retirement"
+    flags: "i"
+  - regex: "ubuntu-20\\.04.*removed|ubuntu-20\\.04.*unavailable"
+    flags: "i"
+  - regex: "ubuntu-20\\.04.*runner will be removed"
+    flags: "i"
+  - regex: "No hosted runner.*ubuntu-20|ubuntu-20\\.04.*no.*runner"
+    flags: "i"
+error_messages:
+  - "This is a scheduled Ubuntu 20.04 retirement. Ubuntu 20.04 LTS runner will be removed on 2025-04-15. For more details, see https://github.com/actions/runner-images/issues/11101"
+  - "ubuntu-20.04 is no longer available. Please use ubuntu-22.04 or ubuntu-24.04 instead."
+  - "No hosted runner was found that matches the requested labels: ubuntu-20.04"
+root_cause: |
+  Ubuntu 20.04 LTS (Focal Fossa) reached end of standard support on April 2,
+  2025. GitHub followed by retiring the ubuntu-20.04 GitHub-hosted runner
+  image on April 15, 2025, after a series of intentional brownout windows
+  that began in March 2025 (March 4, 11, 18, 25 and April 1, 8).
+
+  During each brownout window (13:00–21:00 UTC), any job using runs-on:
+  ubuntu-20.04 was deliberately failed with an explicit retirement message.
+  After April 15, 2025, the image was permanently removed and no longer
+  available as a runner label on GitHub.com.
+
+  Workflows that hardcode ubuntu-20.04 in their runs-on: field now fail
+  immediately with "No hosted runner was found that matches the requested
+  labels: ubuntu-20.04". This also affects:
+  - Actions pinned inside third-party repos that ship their own workflow
+    files using ubuntu-20.04
+  - Reusable workflow templates or starter workflows referencing ubuntu-20.04
+  - Matrix strategies that include ubuntu-20.04 as one of several OS targets
+  - Composite actions or action.yml files in public actions that list
+    ubuntu-20.04 as a required environment
+
+  Self-hosted runners with the ubuntu-20.04 label are NOT affected — they
+  only match the name locally and keep running as long as the self-hosted
+  runner agent is online.
+fix: |
+  Replace ubuntu-20.04 with ubuntu-22.04 or ubuntu-24.04 (ubuntu-latest).
+
+  For most workflows, ubuntu-22.04 is the most compatible drop-in replacement:
+  it shares glibc 2.35 which supports binaries built on Ubuntu 20. However,
+  several packages and tools differ between 20.04 and 22.04:
+  - Python 3.8 and 3.9 are no longer pre-installed on ubuntu-22.04+
+  - libssl1.1 is absent; libssl3 is the current version
+  - Some apt package versions differ
+
+  For ubuntu-24.04:
+  - Python 3.11 is the default (3.8/3.9/3.10 absent)
+  - libssl3 only
+  - Node 18 removed from toolcache
+
+  Run your workflow with ubuntu-22.04 first. Address any package-version
+  failures before migrating to ubuntu-24.04.
+fix_code:
+  - language: yaml
+    label: "Upgrade hardcoded ubuntu-20.04 references to ubuntu-22.04"
+    code: |
+      jobs:
+        build:
+          # Replace deprecated image with supported LTS
+          runs-on: ubuntu-22.04  # was: ubuntu-20.04
+          steps:
+            - uses: actions/checkout@v4
+            - name: Install dependencies
+              run: sudo apt-get install -y libssl-dev  # libssl3 on 22.04, libssl1.1 on 20.04
+            - run: make build
+  - language: yaml
+    label: "Migrate matrix strategy that included ubuntu-20.04"
+    code: |
+      jobs:
+        test:
+          strategy:
+            matrix:
+              os:
+                - ubuntu-22.04   # was ubuntu-20.04
+                - ubuntu-24.04   # was ubuntu-latest (if you want explicit LTS pin)
+                - windows-latest
+                - macos-latest
+          runs-on: ${{ matrix.os }}
+          steps:
+            - uses: actions/checkout@v4
+            - run: make test
+prevention:
+  - "Use ubuntu-latest instead of pinning specific Ubuntu versions to avoid hard failures on retirement"
+  - "If you need a specific Ubuntu LTS, pin to ubuntu-22.04 or ubuntu-24.04 — never a version past its support window"
+  - "Subscribe to runner-images retirement notifications on GitHub (watch actions/runner-images for Issues)"
+  - "Add a monthly workflow audit job that fails if any runs-on: references a known-retired image label"
+  - "Check third-party action.yml files in your dependency tree for hardcoded ubuntu-20.04 references"
+docs:
+  - url: "https://github.com/actions/runner-images/issues/11101"
+    label: "runner-images#11101 — Ubuntu 20.04 retirement announcement and timeline"
+  - url: "https://github.blog/changelog/2025-02-12-notice-of-upcoming-deprecations-and-breaking-changes-for-github-actions/"
+    label: "GitHub Changelog — Ubuntu 20.04 brownout schedule (Feb 2025)"
+  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources"
+    label: "GitHub Docs — Supported GitHub-hosted runner images"

package/errors/yaml-syntax/continue-on-error-env-context-rejected.yml

@@ -0,0 +1,130 @@
+id: yaml-syntax-022
+title: "env Context Rejected in continue-on-error and Other Job-Level Boolean Attributes"
+category: yaml-syntax
+severity: error
+tags:
+  - continue-on-error
+  - env-context
+  - expression
+  - job-level
+  - unrecognized-named-value
+  - context-availability
+patterns:
+  - regex: "Unrecognized named-value: 'env'"
+    flags: "i"
+  - regex: "Unexpected value.*env\\."
+    flags: "i"
+  - regex: "continue-on-error.*env\\.|env\\..*continue-on-error"
+    flags: "i"
+  - regex: "The workflow is not valid.*Unrecognized named-value: 'env'"
+    flags: "i"
+error_messages:
+  - "The workflow is not valid. .github/workflows/ci.yml (Line X, Col Y): Unrecognized named-value: 'env'. Located at position 1 within expression: env.MY_FLAG"
+  - "Unexpected value '${{ contains(env.MY_LIST, matrix.value) }}'"
+root_cause: |
+  The `env` context is NOT available in all workflow attribute positions. Specifically,
+  job-level and step-level attributes that accept boolean values or simple flags — such as
+  `continue-on-error`, `timeout-minutes` (value expressions), and similar fields — do not
+  support the `env` context in their expression evaluations.
+
+  This is a known GitHub Actions platform limitation documented in actions/runner#1492. The
+  error occurs because these attributes are evaluated at workflow parse/validation time (before
+  the job runs), when environment variables have not yet been set in the runner context.
+
+  Contexts available in `continue-on-error`:
+  - ✅ `github`, `needs`, `strategy`, `matrix`
+  - ❌ `env`, `secrets`, `steps`, `jobs`
+
+  A common pattern that fails:
+  ```yaml
+  steps:
+    - run: ./build.sh
+      continue-on-error: ${{ contains(env.SUPPORTED_VERSIONS, matrix.version) }}
+  ```
+
+  Even if `env.SUPPORTED_VERSIONS` was set in the `env:` block at the top of the workflow,
+  the expression fails because `env` is not a supported context in that attribute.
+fix: |
+  Move the boolean logic into a step output computed earlier in the job, then reference the
+  step output in `continue-on-error`. Alternatively, restructure the workflow to avoid needing
+  `env`-based expressions in boolean job/step attributes.
+
+  **Option 1**: Compute the flag in an earlier step and use `steps` context:
+  ```yaml
+  - id: check
+    run: echo "should_skip=$([[ "$MY_FLAG" == "true" ]] && echo true || echo false)" >> $GITHUB_OUTPUT
+  - run: ./potentially-failing-task.sh
+    continue-on-error: ${{ steps.check.outputs.should_skip == 'true' }}
+  ```
+
+  **Option 2**: Use `matrix` context directly (supported in continue-on-error):
+  ```yaml
+  strategy:
+    matrix:
+      experimental: [true, false]
+  steps:
+    - run: ./build.sh
+      continue-on-error: ${{ matrix.experimental }}
+  ```
+
+  **Option 3**: Wrap the step in a conditional run script that handles the error inline.
+fix_code:
+  - language: yaml
+    label: "Use step output to control continue-on-error dynamically"
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          env:
+            EXPERIMENTAL_VERSIONS: "3.12 3.13"
+          steps:
+            - uses: actions/checkout@v4
+
+            # ❌ This FAILS: env context not available in continue-on-error
+            # - run: pytest
+            #   continue-on-error: ${{ contains(env.EXPERIMENTAL_VERSIONS, matrix.python) }}
+
+            # ✅ Compute the flag first, then reference via steps context
+            - id: flags
+              run: |
+                if echo "$EXPERIMENTAL_VERSIONS" | grep -qw "${{ matrix.python }}"; then
+                  echo "experimental=true" >> $GITHUB_OUTPUT
+                else
+                  echo "experimental=false" >> $GITHUB_OUTPUT
+                fi
+            - run: pytest
+              continue-on-error: ${{ steps.flags.outputs.experimental == 'true' }}
+  - language: yaml
+    label: "Use matrix boolean directly (no env needed)"
+    code: |
+      jobs:
+        test:
+          strategy:
+            matrix:
+              include:
+                - python: "3.11"
+                  experimental: false
+                - python: "3.12"
+                  experimental: true
+                - python: "3.13"
+                  experimental: true
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-python@v5
+              with:
+                python-version: ${{ matrix.python }}
+            - run: pytest
+              continue-on-error: ${{ matrix.experimental }}   # ✅ matrix context IS supported
+prevention:
+  - "Check the GitHub Actions context availability table before using any context in job-level attributes — not all contexts are available everywhere."
+  - "When you need dynamic boolean flags in `continue-on-error`, compute them in an earlier step and read via `steps.<id>.outputs`."
+  - "The `matrix` context is fully supported in `continue-on-error` — prefer encoding experimental flags in the matrix definition."
+  - "Run `actionlint` on your workflow to catch context-availability errors before pushing."
+docs:
+  - url: "https://github.com/actions/runner/issues/1492"
+    label: "actions/runner#1492 — env context not available in continue-on-error (original report)"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#context-availability"
+    label: "GitHub Docs — context availability table (where each context can be used)"
+  - url: "https://github.com/rhysd/actionlint"
+    label: "actionlint — static analyzer that catches context-availability errors"

package/package.json

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