@htekdev/actions-debugger 1.0.24 → 1.0.26

package/errors/known-unsolved/environment-deployment-false-custom-protection.yml

@@ -0,0 +1,93 @@
+id: known-unsolved-029
+title: "deployment:false environment key incompatible with custom deployment protection rules"
+category: known-unsolved
+severity: limitation
+tags:
+  - environment
+  - deployment
+  - protection-rules
+  - custom-deployment-protection
+  - no-fix
+
+patterns:
+  - regex: "You cannot (use|disable) deployment.*custom deployment protection"
+    flags: "i"
+  - regex: "deployment: false.*is not supported.*protection rule"
+    flags: "i"
+
+error_messages:
+  - "You cannot use deployment: false when a custom deployment protection rule is configured for this environment."
+  - "Environments with custom deployment protection rules require automatic deployment tracking. Remove deployment: false to proceed."
+
+root_cause: |
+  GitHub Actions added deployment: false as a new key for environments in March 2026
+  (changelog 2026-03-19). This key lets workflows use environment secrets and variables
+  without creating a GitHub Deployment record, which was a long-requested feature for
+  teams who want secrets management without polluting the Deployments tab.
+
+  However, the deployment: false key is fundamentally incompatible with custom deployment
+  protection rules. Custom deployment protection rules (third-party apps registered via
+  the GitHub API to gate deployments) rely on GitHub Deployment events being created —
+  the protection rule callback fires when a deployment is created, approves or rejects it,
+  and the workflow proceeds based on the response.
+
+  When deployment: false is set, no Deployment record is created, so there is no event
+  to trigger the custom protection rule callback. GitHub therefore blocks the combination
+  entirely rather than silently skipping the protection rule check, which could create
+  a security bypass.
+
+  This is a platform-level design constraint with no workaround. Teams that need custom
+  deployment protection rules cannot use deployment: false and must keep auto-deployment
+  enabled.
+
+fix: |
+  There is no workaround. If your environment uses a custom deployment protection rule
+  (a third-party app that approves or rejects deployments), you cannot use deployment: false.
+
+  Options:
+  1. Remove the custom deployment protection rule if it is no longer needed, then use
+     deployment: false to stop creating Deployment records.
+  2. Keep auto-deployment enabled (omit deployment: false) and accept that deployments
+     will appear in the Deployments tab.
+  3. Use a different secrets management strategy (repository secrets, organization secrets,
+     or HashiCorp Vault) if you want to avoid environment-scoped secrets entirely.
+
+fix_code:
+  - language: yaml
+    label: "Valid: deployment:false without custom protection rules"
+    code: |
+      # Works only when the environment has NO custom deployment protection rules
+      jobs:
+        deploy:
+          environment:
+            name: staging
+            deployment: false   # Suppresses Deployment record creation
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Using ${{ secrets.STAGING_API_KEY }} without creating a deployment"
+
+  - language: yaml
+    label: "Required: keep deployment enabled when custom protection rules are configured"
+    code: |
+      # When a custom deployment protection rule (third-party app) is registered
+      # on the environment, omit deployment:false entirely
+      jobs:
+        deploy:
+          environment:
+            name: production   # Has custom protection rule — must create deployment
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Deployment record created; custom protection rule fires and must approve"
+
+prevention:
+  - "Check environment settings in Settings > Environments before adding deployment: false to confirm no custom protection rules are registered."
+  - "Document which environments use custom protection rules so team members know deployment: false is unavailable for those environments."
+  - "If you need both secrets management and no deployment records, consider migrating secrets to organization-level secrets with repository access restrictions."
+
+docs:
+  - url: "https://github.blog/changelog/2026-03-19-github-actions-late-march-2026-updates/"
+    label: "GitHub Changelog 2026-03-19: Environments without auto-deployment (deployment: false)"
+  - url: "https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment#using-an-environment-without-auto-deployment"
+    label: "GitHub Docs: Using an environment without auto-deployment"
+  - url: "https://docs.github.com/en/actions/deployment/protecting-deployments/creating-custom-deployment-protection-rules"
+    label: "GitHub Docs: Creating custom deployment protection rules"

package/errors/permissions-auth/checkout-v6-cross-repo-token-override.yml

@@ -0,0 +1,103 @@
+id: permissions-auth-029
+title: "checkout@v6 http.extraheader overrides inline token for cross-repository push"
+category: permissions-auth
+severity: error
+tags:
+  - checkout
+  - v6
+  - cross-repo
+  - extraheader
+  - token
+  - push
+  - persist-credentials
+
+patterns:
+  - regex: "remote: Permission to .+ denied to github-actions\\[bot\\]"
+    flags: "i"
+  - regex: "fatal: unable to access '.+': The requested URL returned error: 403"
+    flags: "i"
+  - regex: "The requested URL returned error: 403"
+    flags: "i"
+
+error_messages:
+  - "remote: Permission to org/other-repo.git denied to github-actions[bot]."
+  - "fatal: unable to access 'https://github.com/org/other-repo.git/': The requested URL returned error: 403"
+
+root_cause: |
+  checkout@v6 changed how credentials are stored compared to v4/v5. Instead of writing the
+  GITHUB_TOKEN directly into .git/config, v6 stores credentials in a separate file under
+  $RUNNER_TEMP and registers it via a git includeIf directive. This injects an
+  http.extraheader = Authorization: Bearer <GITHUB_TOKEN> for ALL https://github.com/ URLs.
+
+  When a workflow adds a second remote using an inline Personal Access Token (PAT) in the URL
+  (e.g., https://PAT@github.com/other-org/other-repo.git), git still sends the checkout-injected
+  Authorization header alongside the URL-embedded token. The injected GITHUB_TOKEN header takes
+  precedence over the URL-embedded PAT, and since GITHUB_TOKEN only has access to the current
+  repository, the push to the other repository is rejected with 403 Forbidden.
+
+  This regression is specific to workflows that push to repositories other than the one that
+  was checked out. Workflows that only interact with the current repository are unaffected.
+
+fix: |
+  Option 1 (recommended): Set persist-credentials: false in the checkout step. This prevents
+  checkout@v6 from injecting the extraheader entirely. Configure authentication explicitly in
+  subsequent steps using the token in the remote URL or via GH_TOKEN environment variable.
+
+  Option 2 (targeted): Explicitly unset the http extraheader before performing cross-repo
+  operations. Add a step that clears the auth override for github.com URLs before pushing
+  to the other repository.
+
+  Option 3 (fallback): Pin to checkout@v5 for workflows that require cross-repo push
+  until a v6 upstream fix is available (actions/checkout#2424 is open).
+
+fix_code:
+  - language: yaml
+    label: "Option 1: Disable persist-credentials to prevent extraheader injection"
+    code: |
+      steps:
+        - name: Checkout current repo
+          uses: actions/checkout@v6
+          with:
+            persist-credentials: false   # No extraheader injected; manual auth required
+
+        - name: Push tag to target repository
+          env:
+            TARGET_PAT: ${{ secrets.TARGET_REPO_PAT }}
+          run: |
+            # Token embedded in remote URL; no competing extraheader present
+            TARGET_REMOTE="https://x-access-token:${TARGET_PAT}@github.com/org/target-repo.git"
+            git remote add target "${TARGET_REMOTE}"
+            git tag -f nightly
+            git push -f target nightly
+
+  - language: yaml
+    label: "Option 2: Clear the injected extraheader before cross-repo operations"
+    code: |
+      steps:
+        - uses: actions/checkout@v6
+
+        # ... build steps ...
+
+        - name: Unset checkout extraheader for cross-repo push
+          run: git config --unset-all "http.https://github.com/.extraheader" || true
+
+        - name: Push tag to target repository
+          env:
+            TARGET_PAT: ${{ secrets.TARGET_REPO_PAT }}
+          run: |
+            git remote add target "https://x-access-token:${TARGET_PAT}@github.com/org/target-repo.git"
+            git push -f target nightly
+
+prevention:
+  - "Use persist-credentials: false on all checkout steps in workflows that interact with multiple repositories."
+  - "Avoid embedding tokens directly in remote URLs when checkout@v6 is used without persist-credentials:false."
+  - "Test cross-repo operations in a staging branch after upgrading from checkout@v4 or v5 to v6."
+  - "Check actions/checkout release notes for credential storage changes when upgrading major versions."
+
+docs:
+  - url: "https://github.com/actions/checkout/issues/2424"
+    label: "actions/checkout#2424: Unable to create tags in another repo with v6"
+  - url: "https://github.com/actions/checkout/releases/tag/v6.0.0"
+    label: "checkout@v6.0.0 release notes — persist-credentials storage change"
+  - url: "https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication"
+    label: "GitHub Docs: Automatic token authentication and GITHUB_TOKEN scopes"

package/errors/runner-environment/macos-dotnet-root-env-var-removed.yml

@@ -0,0 +1,90 @@
+id: runner-environment-078
+title: "macOS Runner DOTNET_ROOT Environment Variable Removed — .NET SDK Path Discovery Fails"
+category: runner-environment
+severity: error
+tags:
+  - macos
+  - dotnet
+  - dotnet-root
+  - environment-variable
+  - sdk-discovery
+  - breaking-change
+  - runner-images
+patterns:
+  - regex: 'DOTNET_ROOT.*not set|DOTNET_ROOT.*undefined|DOTNET_ROOT.*empty'
+    flags: "i"
+  - regex: 'A compatible \.NET SDK was not found|It was not possible to find any installed \.NET'
+    flags: "i"
+  - regex: 'dotnet.*not found|No \.NET SDKs were found'
+    flags: "i"
+error_messages:
+  - "A compatible .NET SDK was not found."
+  - "It was not possible to find any installed .NET Core SDKs."
+  - "No .NET SDKs were found."
+  - "DOTNET_ROOT is not set."
+root_cause: |
+  Starting January 12, 2026, GitHub removed the DOTNET_ROOT environment variable from
+  all macOS runner images: macOS-14, macOS-14-arm64, macOS-15, macOS-15-arm64,
+  macOS-26, and macOS-26-arm64 (runner-images#13470, driven by #13365).
+
+  The variable was previously predefined in the runner image environment to help
+  .NET tooling locate installed SDKs. It was removed because modern .NET SDK versions
+  can discover installations without it, and keeping the hardcoded path caused
+  inconsistent behavior when multiple .NET versions were installed side-by-side.
+
+  Workflows affected:
+  1. Custom scripts that use $DOTNET_ROOT or $env:DOTNET_ROOT to invoke the dotnet CLI
+     without first running actions/setup-dotnet.
+  2. Docker containers started from the runner that inherit the host environment
+     and previously relied on DOTNET_ROOT being present.
+  3. Third-party .NET tools or build scripts that call into the .NET host resolver
+     and expect the environment to provide a root path.
+
+  Note: Windows and Ubuntu runner images are NOT affected by this change — only macOS.
+  Workflows using actions/setup-dotnet are unaffected as it sets DOTNET_ROOT itself.
+fix: |
+  Set DOTNET_ROOT manually in the job env block, OR use actions/setup-dotnet which
+  sets it correctly as part of its own setup. For most GitHub Actions workflows that
+  install .NET via setup-dotnet, no change is needed. Custom scripts that reference
+  $DOTNET_ROOT directly must set it explicitly.
+
+  The canonical path for user-scoped .NET installs is $HOME/.dotnet (Unix) or
+  $env:USERPROFILE\.dotnet (Windows). actions/setup-dotnet uses $RUNNER_TOOL_CACHE.
+fix_code:
+  - language: yaml
+    label: "Set DOTNET_ROOT manually in the job env block"
+    code: |
+      jobs:
+        build:
+          runs-on: macos-latest
+          env:
+            DOTNET_ROOT: ${{ runner.home }}/.dotnet
+          steps:
+            - uses: actions/checkout@v4
+            - name: Build
+              run: dotnet build src/MyApp.csproj
+  - language: yaml
+    label: "Use actions/setup-dotnet — sets DOTNET_ROOT automatically"
+    code: |
+      jobs:
+        build:
+          runs-on: macos-latest
+          steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-dotnet@v4
+              with:
+                dotnet-version: '9.x'
+            # DOTNET_ROOT is now set by setup-dotnet automatically
+            - run: dotnet test --configuration Release
+prevention:
+  - "Use actions/setup-dotnet in all .NET workflows on macOS — it sets DOTNET_ROOT and handles version management."
+  - "Audit scripts for direct $DOTNET_ROOT or $env:DOTNET_ROOT references and add explicit env: blocks for macOS jobs."
+  - "Test .NET workflows on macOS runner versions after image update cycles."
+  - "Subscribe to runner-images pinned announcements to stay ahead of environment variable removals."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/13470"
+    label: "runner-images#13470: DOTNET_ROOT environment variable will be removed from macOS on January 12th, 2026"
+  - url: "https://github.com/actions/setup-dotnet"
+    label: "actions/setup-dotnet: Installs .NET SDK and sets DOTNET_ROOT correctly"
+  - url: "https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-environment-variables#dotnet_root-dotnet_rootx86"
+    label: "Microsoft Docs: DOTNET_ROOT environment variable reference"

package/errors/runner-environment/maven-gradle-403-cache-backend-outage.yml

@@ -0,0 +1,116 @@
+id: runner-environment-075
+title: "Maven/Gradle 403 Forbidden when GitHub Actions cache backend is degraded"
+category: runner-environment
+severity: error
+tags:
+  - maven
+  - gradle
+  - 403
+  - cache-backend
+  - outage
+  - rate-limit
+  - sonatype
+  - dependency-download
+
+patterns:
+  - regex: "Received status code 403 from server"
+    flags: "i"
+  - regex: "Could not transfer artifact .+ from .+ Forbidden"
+    flags: "i"
+  - regex: "Our services aren't available right now"
+    flags: "i"
+  - regex: "Received HTTP 403 from Maven Repository"
+    flags: "i"
+
+error_messages:
+  - "Could not transfer artifact org.springframework:spring-core:jar:6.1.0 from/to central (https://repo.maven.apache.org/maven2): Received status code 403 from server: Forbidden"
+  - "Received status code 403 from server: Forbidden"
+  - "Our services aren't available right now\nWe're working to restore all services as soon as possible. Please check back soon."
+  - "Exception in thread \"main\" org.gradle.api.UncheckedIOException: com.amazonaws.SdkClientException: Unable to execute HTTP request: The target server failed to respond"
+
+root_cause: |
+  GitHub Actions cache backend (actions/cache) is an eventually-consistent distributed storage
+  system. During degradation incidents, cache restore operations fail with the message
+  "Our services aren't available right now" and exit 0 (the job continues). Maven and Gradle
+  builds that normally cache artifacts under .m2/repository or .gradle/caches fall through
+  to downloading all dependencies directly from Maven Central (repo.maven.apache.org).
+
+  GitHub-hosted runners share IP address ranges across thousands of concurrent workflow runs.
+  During a cache backend outage, every affected build simultaneously requests artifacts
+  from Maven Central. Sonatype (which operates Maven Central) rate-limits abusive traffic
+  patterns from shared IP ranges, returning HTTP 403 Forbidden. This creates a cascading
+  failure: one cache service incident causes all Java/Kotlin/Scala CI pipelines to fail
+  until the cache backend recovers.
+
+  The failure is misleading because the error comes from Maven Central, not GitHub, so
+  developers often suspect repository permissions, network configuration, or Sonatype policy
+  changes rather than GitHub infrastructure.
+
+fix: |
+  Short-term: Check GitHub Status (githubstatus.com) for cache service incidents before
+  debugging Maven/Gradle configuration. Retry the workflow after the incident resolves.
+
+  Medium-term: Add Maven retry configuration to pom.xml or build.gradle to tolerate
+  transient 403/429 responses. Configure a secondary mirror as a fallback to reduce
+  direct Maven Central dependency.
+
+  Long-term: Host a private artifact cache (Nexus, Artifactory, or AWS CodeArtifact)
+  that proxies Maven Central. This prevents GitHub runner IP ranges from hitting Maven
+  Central directly and provides a stable fallback during GitHub cache outages.
+
+fix_code:
+  - language: yaml
+    label: "Workflow: Add retry wrapper step for Maven builds during cache degradation"
+    code: |
+      steps:
+        - uses: actions/cache@v4
+          id: maven-cache
+          with:
+            path: ~/.m2/repository
+            key: ${{ runner.os }}-maven-${{ hashFiles('**/pom.xml') }}
+            restore-keys: |
+              ${{ runner.os }}-maven-
+
+        - name: Check cache status and set retry flag
+          if: steps.maven-cache.outputs.cache-hit != 'true'
+          run: echo "MAVEN_OPTS=-Dmaven.artifact.threads=5" >> $GITHUB_ENV
+
+        - name: Build with Maven
+          run: mvn --batch-mode --no-transfer-progress -T 1C verify
+
+  - language: yaml
+    label: "Maven settings.xml: Add mirror fallback to reduce direct Maven Central load"
+    code: |
+      # .github/maven-settings.xml — add to repository root
+      # Reference in workflow: mvn -s .github/maven-settings.xml ...
+      #
+      # <settings>
+      #   <mirrors>
+      #     <mirror>
+      #       <id>central-mirror</id>
+      #       <mirrorOf>central</mirrorOf>
+      #       <url>https://repo1.maven.org/maven2/</url>
+      #     </mirror>
+      #   </mirrors>
+      # </settings>
+      #
+      # Then in workflow:
+      - name: Build with Maven (mirror fallback)
+        run: mvn -s .github/maven-settings.xml --batch-mode verify
+
+prevention:
+  - "Monitor githubstatus.com/history for GitHub Actions cache incidents before assuming build failures are configuration errors."
+  - "Add --no-transfer-progress to Maven commands to reduce output noise; add -Dmaven.artifact.threads=3 to reduce concurrent Central requests."
+  - "Configure restore-keys fallback in actions/cache so partial cache hits reduce Maven Central traffic."
+  - "Consider self-hosted Nexus or AWS CodeArtifact as a Maven Central proxy for production CI pipelines."
+  - "Add 'if: always()' or cache-miss detection to skip cache restore wait during known outages."
+
+docs:
+  - url: "https://github.com/actions/runner/issues/4180"
+    label: "actions/runner#4180: CI Runners Failing with 403 Forbidden for Maven/Gradle (75 reactions)"
+  - url: "https://www.githubstatus.com/"
+    label: "GitHub Status — check for Actions cache service incidents"
+  - url: "https://central.sonatype.org/faq/rate-limiting/"
+    label: "Sonatype Maven Central: Rate limiting and fair use policy"
+  - 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/powershell-76-dotnet10-httpclient-breaking-changes.yml

@@ -0,0 +1,109 @@
+id: runner-environment-079
+title: "PowerShell 7.6 on Runners Ships .NET 10 Runtime — HttpWebRequest and WebClient Throw NotSupportedException"
+category: runner-environment
+severity: error
+tags:
+  - powershell
+  - powershell-76
+  - dotnet-10
+  - dotnet-8
+  - runner-images
+  - breaking-change
+  - httpclient
+  - webclient
+patterns:
+  - regex: 'NotSupportedException.*HttpWebRequest|WebClient.*NotSupportedException'
+    flags: "i"
+  - regex: 'ServicePointManager.*SecurityProtocol.*not supported|The method or operation is not implemented'
+    flags: "i"
+  - regex: 'MissingMethodException.*ServicePointManager|System\.Net\.WebException.*NotSupported'
+    flags: "i"
+  - regex: 'WildcardPattern\.Escape.*backtick|Join-Path.*ChildPath.*string\[\]'
+    flags: "i"
+error_messages:
+  - "System.NotSupportedException: WebClient has been removed from .NET"
+  - "System.NotSupportedException: HttpWebRequest is not supported on this platform"
+  - "System.MissingMethodException: Method not found: 'Void System.Net.ServicePointManager.set_SecurityProtocol'"
+root_cause: |
+  PowerShell 7.4 was built on .NET 8. PowerShell 7.6 is built on .NET 10.
+  Beginning June 8-15, 2026, all GitHub-hosted runner images upgraded from PS 7.4
+  to PS 7.6 LTS (runner-images#14150). This introduces several .NET 10 breaking changes:
+
+  1. HttpWebRequest and WebClient have been fully removed in .NET 10.
+     Any PowerShell script that uses New-Object System.Net.WebClient or
+     [System.Net.HttpWebRequest]::Create() now throws NotSupportedException.
+     Both classes were deprecated in .NET 5 and are gone in .NET 10.
+
+  2. ServicePointManager.SecurityProtocol setter is not supported in .NET 10.
+     Workflows that manually set TLS protocol versions with
+     [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.SecurityProtocolType]::Tls12
+     now throw MissingMethodException. .NET 10 negotiates TLS automatically.
+
+  3. WildcardPattern.Escape now correctly escapes lone backtick characters (PS #25211).
+     Scripts that relied on the previous (incorrect) unescaped behavior may match
+     different patterns than expected.
+
+  4. Join-Path -ChildPath parameter changed from string to string[]. Code that relied
+     on positional argument behavior for this parameter may bind differently.
+
+  This is distinct from the ThreadJob module rename (runner-environment-075 entry).
+  These are .NET runtime-level breaking changes, not module renames.
+fix: |
+  Replace HttpWebRequest / WebClient with Invoke-RestMethod or Invoke-WebRequest,
+  which are the PowerShell-native HTTP clients backed by HttpClient (supported in all
+  .NET versions). Remove ServicePointManager.SecurityProtocol assignments entirely;
+  .NET 10 negotiates TLS 1.2/1.3 automatically and no longer accepts manual overrides.
+fix_code:
+  - language: yaml
+    label: "Replace WebClient (removed in .NET 10) with Invoke-WebRequest"
+    code: |
+      steps:
+        - name: Download file
+          shell: pwsh
+          run: |
+            # BEFORE (.NET 10 throws NotSupportedException):
+            # $wc = New-Object System.Net.WebClient
+            # $wc.DownloadFile($env:URL, $env:DEST)
+
+            # AFTER — use Invoke-WebRequest (works across .NET 6/8/10)
+            Invoke-WebRequest -Uri $env:ARTIFACT_URL -OutFile $env:DEST_PATH -UseBasicParsing
+          env:
+            ARTIFACT_URL: 'https://example.com/artifact.zip'
+            DEST_PATH: 'artifact.zip'
+  - language: yaml
+    label: "Remove ServicePointManager.SecurityProtocol (not needed in .NET 10)"
+    code: |
+      steps:
+        - name: Call API
+          shell: pwsh
+          run: |
+            # BEFORE (.NET 10 throws MissingMethodException):
+            # [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.SecurityProtocolType]::Tls12
+
+            # AFTER — .NET 10 negotiates TLS 1.3/1.2 automatically, no manual override needed
+            $response = Invoke-RestMethod -Uri 'https://api.example.com/data' -Method Get
+            $response | ConvertTo-Json
+  - language: yaml
+    label: "Check PowerShell version in workflow to detect the upgrade"
+    code: |
+      steps:
+        - name: Verify PowerShell version and .NET runtime
+          shell: pwsh
+          run: |
+            $PSVersionTable
+            [System.Environment]::Version
+prevention:
+  - "Audit all PowerShell scripts in workflows for WebClient and HttpWebRequest usage before the June 8-15 image rollout."
+  - "Replace New-Object System.Net.WebClient with Invoke-WebRequest or Invoke-RestMethod throughout."
+  - "Remove all [System.Net.ServicePointManager]::SecurityProtocol assignments — they are no-ops at best in .NET 10."
+  - "Test workflows locally with PowerShell 7.6 (winget install Microsoft.PowerShell) before the image rollout completes."
+  - "The ThreadJob module rename is a separate issue — see runner-environment-075 entry for that breaking change."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/14150"
+    label: "runner-images#14150: PowerShell will be updated from 7.4 to 7.6 LTS on all runner images"
+  - url: "https://learn.microsoft.com/en-us/powershell/scripting/whats-new/what-s-new-in-powershell-76"
+    label: "Microsoft Docs: What's new in PowerShell 7.6"
+  - url: "https://learn.microsoft.com/en-us/dotnet/core/whats-new/dotnet-10/overview"
+    label: "Microsoft Docs: Breaking changes in .NET 10"
+  - url: "https://github.com/PowerShell/PowerShell/releases/tag/v7.6.0"
+    label: "PowerShell 7.6.0 Release Notes"

package/errors/runner-environment/ubuntu-24-04-chrome-148-webdriverio-hang.yml

@@ -0,0 +1,91 @@
+id: runner-environment-077
+title: "Chrome 148.0.7778.178 on Ubuntu 24.04 Causes WebdriverIO and Browser Tests to Hang"
+category: runner-environment
+severity: error
+tags:
+  - ubuntu-24.04
+  - chrome
+  - chromium
+  - webdriverio
+  - browser-testing
+  - regression
+  - selenium
+  - playwright
+patterns:
+  - regex: 'Failed to create session|chrome not reachable|connect ECONNREFUSED.*9515'
+    flags: "i"
+  - regex: 'ChromeDriver.*unable to receive message|WebDriver.*timed out'
+    flags: "i"
+  - regex: 'google-chrome.*148\.0\.7778\.17[89]|148\.0\.7778\.17[89]'
+    flags: "i"
+error_messages:
+  - "Error: Failed to create session."
+  - "Error: chrome not reachable"
+  - "Error: connect ECONNREFUSED 127.0.0.1:9515"
+  - "DevTools protocol message timeout"
+root_cause: |
+  Chrome 148.0.7778.178 was shipped in ubuntu-24.04 runner image 20260525.161.1
+  (May 25, 2026). This build introduced an upstream regression that causes WebdriverIO,
+  Selenium, and other CDP-based browser automation frameworks to hang indefinitely
+  when launching Chrome. The Chrome process starts but the DevTools Protocol endpoint
+  never becomes reachable, causing session creation to time out.
+
+  GitHub installs Chrome from the official stable channel on each image build and does
+  not pin versions. The previous image (20260518.149.1) shipped Chrome 148.0.7778.167
+  which was unaffected. GitHub confirmed they will not roll back the image and are
+  waiting for an upstream Google Chrome fix (tracked as Chromium issue #517079992).
+
+  WebdriverIO tests that previously ran reliably on GitHub-hosted ubuntu-24.04 runners
+  will hang silently or time out after this image version update. Switching to
+  ubuntu-22.04 does not guarantee relief as it also installs stable Chrome.
+fix: |
+  Pin Chrome to version 148.0.7778.167 (the last known-good stable build) using
+  browser-actions/setup-chrome, which installs from Chrome for Testing CDN — an
+  immutable, version-pinned registry that does not auto-update. Point WebdriverIO at
+  the pinned Chrome binary via environment variables rather than using system Chrome.
+fix_code:
+  - language: yaml
+    label: "Pin Chrome to last known-good build (runner-images#14169 workaround)"
+    code: |
+      jobs:
+        e2e:
+          runs-on: ubuntu-24.04
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Install pinned Chrome (workaround for runner-images#14169)
+              id: setup-chrome
+              uses: browser-actions/setup-chrome@v1
+              with:
+                chrome-version: '148.0.7778.167'
+                install-dependencies: true
+                install-chromedriver: true
+
+            - name: Run E2E tests with pinned Chrome
+              env:
+                CHROME_BIN: ${{ steps.setup-chrome.outputs.chrome-path }}
+                CHROMEWEBDRIVER: ${{ steps.setup-chrome.outputs.chromedriver-path }}
+              run: npx wdio run wdio.conf.js
+  - language: yaml
+    label: "WebdriverIO capability config pointing to pinned Chrome binary"
+    code: |
+      # wdio.conf.js — use CHROME_BIN from the setup-chrome step, not system Chrome
+      capabilities: [{
+        browserName: 'chrome',
+        'goog:chromeOptions': {
+          binary: process.env.CHROME_BIN,
+          args: ['--headless=new', '--no-sandbox', '--disable-dev-shm-usage'],
+        },
+      }]
+prevention:
+  - "Never rely on the system Chrome version in CI — pin via browser-actions/setup-chrome for reproducible builds."
+  - "Configure WebdriverIO to use CHROME_BIN environment variable instead of auto-detecting /usr/bin/google-chrome."
+  - "Subscribe to actions/runner-images#14169 to learn when a fixed Chrome stable is shipped."
+  - "Consider Playwright (brings its own browser binaries) as a long-term alternative to avoid runner image Chrome updates."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/14169"
+    label: "runner-images#14169: Ubuntu 24.04 image update causes WebdriverIO tests with updated Chrome to hang"
+  - url: "https://github.com/browser-actions/setup-chrome"
+    label: "browser-actions/setup-chrome: Install pinned Chrome for Testing builds"
+  - url: "https://googlechromelabs.github.io/chrome-for-testing/"
+    label: "Chrome for Testing: Immutable Chrome binaries by version (CDN)"

package/errors/runner-environment/ubuntu-24-04-kernel-read-ahead-kb-io-thrashing.yml

@@ -0,0 +1,94 @@
+id: runner-environment-076
+title: "Ubuntu 24.04 Kernel read_ahead_kb Regression Causes I/O Thrashing and Workflow Hangs"
+category: runner-environment
+severity: error
+tags:
+  - ubuntu-24.04
+  - kernel
+  - io-thrashing
+  - memory
+  - docker
+  - read-ahead
+  - performance
+patterns:
+  - regex: 'The hosted runner lost communication with the server'
+    flags: "i"
+  - regex: 'Free memory is lower than 5%|Currently used: 9[0-9]\.[0-9]+%'
+    flags: "i"
+  - regex: 'Out of memory, malloc failed|fatal: the remote end hung up unexpectedly'
+    flags: "i"
+error_messages:
+  - "The hosted runner lost communication with the server. Anything in your workflow that terminates the runner process, starves it for CPU/Memory, or blocks its network access can cause this error."
+  - "##[warning]Free memory is lower than 5%; Currently used: 95.55%"
+  - "fatal: Out of memory, malloc failed (tried to allocate 217 bytes)"
+  - "fatal: the remote end hung up unexpectedly"
+root_cause: |
+  Starting with kernel 6.14.0-1017-azure (shipped in ubuntu-24.04 image 20260224.36.1
+  and continuing with 6.17.0-1008-azure in 20260302.42.1 through current), the default
+  read_ahead_kb block device value was changed from 128 KB to 4096 KB. This causes
+  the Linux page cache to speculatively read 32x more data from disk for each I/O
+  operation, flooding available RAM with unused prefetched data.
+
+  The effect is severe for workloads with large files accessed non-sequentially
+  (many build systems, compilation), Docker-in-Docker setups, database integration
+  tests (Postgres, MySQL, Redis) under I/O load, and large repository operations.
+
+  The page cache exhaustion triggers OOM conditions, process starvation, and eventually
+  causes the Actions runner process to lose connectivity to the GitHub Actions broker,
+  manifesting as "The hosted runner lost communication with the server."
+
+  GitHub confirmed this is a kernel-level change they do not control and cannot roll
+  back. The fix must be applied in the workflow. Independently documented by the
+  RavenDB team for the same Azure kernel change.
+fix: |
+  Add a step at the beginning of the job to reset read_ahead_kb to 128 KB (the
+  safe pre-regression value). This must run before any I/O-intensive steps.
+  The step requires sudo access, which is available on all GitHub-hosted runners.
+fix_code:
+  - language: yaml
+    label: "Reset read_ahead_kb before I/O-intensive steps (kernel regression workaround)"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-24.04
+          steps:
+            - name: Reset block device read-ahead (kernel regression workaround for runner-images#13770)
+              run: |
+                for dev in /sys/block/sd*/queue/read_ahead_kb; do
+                  echo 128 | sudo tee "$dev" > /dev/null
+                done
+                echo "read_ahead_kb reset to 128 on all block devices"
+
+            - uses: actions/checkout@v4
+            - name: Build
+              run: make
+  - language: yaml
+    label: "Diagnose memory pressure before applying the workaround"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-24.04
+          steps:
+            - name: Show current read_ahead_kb and available memory
+              run: |
+                cat /sys/block/sda/queue/read_ahead_kb || true
+                free -h
+
+            - name: Reset read_ahead_kb to safe value
+              run: |
+                for dev in /sys/block/sd*/queue/read_ahead_kb; do
+                  echo 128 | sudo tee "$dev" > /dev/null
+                done
+                cat /sys/block/sda/queue/read_ahead_kb
+prevention:
+  - "Always reset read_ahead_kb to 128 on ubuntu-24.04 runners for workflows with Docker containers or database integration tests."
+  - "Use ubuntu-22.04 as a temporary mitigation — kernel 6.8.0 is unaffected by this regression."
+  - "Add memory diagnostics (free -h) before heavy build steps to catch exhaustion early."
+  - "Monitor actions/runner-images#13770 for a permanent kernel fix from Canonical and GitHub."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/13770"
+    label: "runner-images#13770: ubuntu-latest builds hanging in 20260302.42.1 runner image (kernel regression)"
+  - url: "https://github.com/ravendb/ravendb/discussions/22410"
+    label: "RavenDB: Azure kernel read_ahead_kb change causing I/O thrashing"
+  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners"
+    label: "GitHub Docs: GitHub-hosted runner hardware resources"

package/errors/silent-failures/undefined-env-expression-empty-string-silent.yml

@@ -12,7 +12,7 @@ tags:
 patterns:
   - regex: '\$\{\{\s*env\.[A-Za-z_][A-Za-z0-9_]*\s*\}\}'
     flags: "i"
-  - regex: "expression.*evaluates.*empty.*string|undefined.*variable.*no.*error"
+  - regex: 'expression.*evaluates.*empty.*string|undefined.*variable.*no.*error'
     flags: "i"
 error_messages:
   - "(no error shown -- undefined env/context variables produce empty strings silently)"

package/errors/yaml-syntax/case-function-runner-version-too-old.yml

@@ -0,0 +1,100 @@
+id: yaml-syntax-031
+title: "case() expression function fails with 'Unrecognized function' on runners older than 2.329.0"
+category: yaml-syntax
+severity: error
+tags:
+  - case-function
+  - expressions
+  - runner-version
+  - self-hosted
+  - composite-action
+  - if-condition
+
+patterns:
+  - regex: "Unrecognized function: 'case'"
+    flags: "i"
+  - regex: "The workflow is not valid.*Unrecognized function.*case"
+    flags: "i"
+
+error_messages:
+  - "Unrecognized function: 'case'. Located at position 1 within expression: case(github.event_name == 'push', 'deploy', github.event_name == 'pull_request', 'review', 'skip')"
+  - "The workflow is not valid. .github/workflows/deploy.yml (Line: 24, Col: 16): Unrecognized function: 'case'"
+
+root_cause: |
+  GitHub introduced the case() expression function in runner version 2.329.0 (January 2026,
+  announced in the GitHub Actions changelog on 2026-01-29). The case() function enables
+  conditional branching similar to SQL CASE expressions, supporting if-else and switch-case
+  patterns in workflow expressions.
+
+  Self-hosted runners that have not been updated to version 2.329.0 or later do not recognize
+  case() as a valid function. When any workflow step, job-level if: condition, output mapping,
+  or composite action uses ${{ case(...) }}, the runner throws "Unrecognized function: 'case'"
+  and the job fails immediately.
+
+  GitHub-hosted runners (ubuntu-latest, windows-latest, macos-latest) receive runner updates
+  automatically and are not affected. Only self-hosted runners with version pinning or delayed
+  update policies encounter this error.
+
+  A secondary regression occurred in runner 2.333.0 (March 2026) where case() was temporarily
+  broken for composite actions specifically, producing the same error. This was resolved in
+  2.333.1.
+
+fix: |
+  For self-hosted runners: Update the runner to version 2.329.0 or later. Runner updates
+  can be applied via the GitHub Actions runner update script or by re-registering the runner
+  with the latest version from the GitHub Actions runner releases page.
+
+  To verify your runner version: check Settings > Actions > Runners in your repository or
+  organization, or inspect the runner binary with ./actions-runner/config.sh --version.
+
+  Temporary workaround: Rewrite case() expressions using nested ternary-style expressions
+  that work on all runner versions, then migrate to case() once runners are updated.
+
+fix_code:
+  - language: yaml
+    label: "New (requires runner 2.329.0+): using case() for conditional output"
+    code: |
+      jobs:
+        determine-env:
+          runs-on: self-hosted
+          outputs:
+            environment: ${{ steps.set-env.outputs.env }}
+          steps:
+            - id: set-env
+              run: echo "env=${{ case(github.ref == 'refs/heads/main', 'production', github.ref == 'refs/heads/staging', 'staging', 'development') }}" >> $GITHUB_OUTPUT
+
+  - language: yaml
+    label: "Fallback for runners older than 2.329.0 (works on all versions)"
+    code: |
+      jobs:
+        determine-env:
+          runs-on: self-hosted
+          outputs:
+            environment: ${{ steps.set-env.outputs.env }}
+          steps:
+            - id: set-env
+              run: |
+                REF="${{ github.ref }}"
+                if [[ "$REF" == "refs/heads/main" ]]; then
+                  echo "env=production" >> $GITHUB_OUTPUT
+                elif [[ "$REF" == "refs/heads/staging" ]]; then
+                  echo "env=staging" >> $GITHUB_OUTPUT
+                else
+                  echo "env=development" >> $GITHUB_OUTPUT
+                fi
+
+prevention:
+  - "Pin runner version in self-hosted runner documentation and set up automated update notifications."
+  - "Add a workflow step that logs the runner version (echo $ACTIONS_RUNNER_VERSION) to surface version mismatches early."
+  - "Test new expression functions on GitHub-hosted runners first; then roll out to self-hosted after confirming the runner version."
+  - "Configure runner auto-update policies — GitHub recommends keeping self-hosted runners within 2 major versions of the latest."
+
+docs:
+  - url: "https://github.blog/changelog/2026-01-29-github-actions-smarter-editing-clearer-debugging-and-a-new-case-function/"
+    label: "GitHub Changelog 2026-01-29: New case() function introduction"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/evaluate-expressions-in-workflows-and-actions"
+    label: "GitHub Docs: Expressions — case() function reference"
+  - url: "https://github.com/actions/runner/issues/4315"
+    label: "actions/runner#4315: Runner v2.333.0 breaks case function (regression)"
+  - url: "https://github.com/actions/runner/releases"
+    label: "GitHub Actions Runner releases — version history"

package/package.json

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