@htekdev/actions-debugger 1.0.2 → 1.0.3

package/errors/caching-artifacts/artifact-download-no-artifacts-found.yml

@@ -0,0 +1,118 @@
+id: caching-artifacts-010
+title: "Artifact Download Fails — Unable to Find Any Artifacts for Run"
+category: caching-artifacts
+severity: error
+tags:
+  - artifact
+  - download
+  - run-id
+  - cross-workflow
+  - upload-artifact
+  - download-artifact
+patterns:
+  - regex: "Unable to find any artifacts for the associated workflow"
+    flags: "i"
+  - regex: "No artifacts found for run"
+    flags: "i"
+  - regex: "Error: Unable to find any artifacts"
+    flags: "i"
+error_messages:
+  - "Unable to find any artifacts for the associated workflow"
+  - "Error: Unable to find any artifacts for the associated workflow"
+  - "No artifacts were found with the provided name and filters."
+root_cause: |
+  GitHub Actions artifacts are scoped to a specific workflow run. The
+  `actions/download-artifact@v4` action (and v3 with `run-id:`) will fail with
+  "Unable to find any artifacts" when:
+
+  1. **Wrong or stale run-id** — The run ID is hard-coded or fetched from a
+     prior run that no longer has the expected artifact (artifacts expire after
+     the configured retention period, default 90 days).
+
+  2. **Upload step never ran** — The producing workflow job was cancelled, the
+     upload step was skipped due to a failed prior step, or the `if:` condition
+     on the upload step evaluated to false.
+
+  3. **Name mismatch** — The `name:` specified in `download-artifact` doesn't
+     exactly match the name used in `upload-artifact` (case-sensitive).
+
+  4. **Cross-workflow download without explicit run-id** — In v4, downloading
+     artifacts from a different workflow run requires an explicit `run-id:`.
+     Omitting it defaults to the current run, which may not have those artifacts.
+
+  Documented in GitHub Community discussion #109905.
+fix: |
+  For cross-workflow artifact sharing:
+  1. Capture the producing workflow's run-id dynamically using the GitHub REST
+     API or by passing it as a workflow_dispatch input or repository_dispatch payload.
+  2. Verify the upload step ran successfully in the producer workflow before
+     downloading in a consumer workflow.
+  3. Ensure `name:` matches exactly (case-sensitive) between upload and download.
+  4. For same-workflow jobs, omit `run-id:` — download-artifact v4 defaults to
+     the current run automatically.
+fix_code:
+  - language: yaml
+    label: "WRONG — hard-coded run-id that may be stale"
+    code: |
+      - uses: actions/download-artifact@v4
+        with:
+          name: build-output
+          run-id: 12345678  # ❌ hard-coded run ID — stale if re-run or wrong workflow
+  - language: yaml
+    label: "RIGHT — same-workflow, no run-id needed"
+    code: |
+      # Job A (producer)
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - run: make build
+            - uses: actions/upload-artifact@v4
+              with:
+                name: build-output       # ✅ exact name matters
+                path: dist/
+
+        test:
+          needs: build
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/download-artifact@v4
+              with:
+                name: build-output       # ✅ same name, no run-id needed for current run
+  - language: yaml
+    label: "RIGHT — cross-workflow download, run-id from API"
+    code: |
+      - name: Get latest successful run ID
+        id: get-run
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          RUN_ID=$(gh run list \
+            --workflow=build.yml \
+            --branch=main \
+            --status=success \
+            --limit=1 \
+            --json databaseId \
+            --jq '.[0].databaseId')
+          echo "run_id=$RUN_ID" >> $GITHUB_OUTPUT
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: build-output
+          run-id: ${{ steps.get-run.outputs.run_id }}  # ✅ dynamic run ID
+          github-token: ${{ github.token }}
+prevention:
+  - "Never hard-code run-id values — always fetch them dynamically via the GitHub API or pass them as workflow inputs."
+  - "Always verify artifact upload completed successfully before writing a consuming workflow that depends on it."
+  - "Use exact case-matching artifact names — `build-output` and `Build-Output` are different artifacts."
+  - "For same-workflow artifact sharing between jobs, omit `run-id:` entirely — it defaults to the current run."
+  - "Check artifact retention settings — artifacts expire after 90 days (public) or 400 days (private) by default."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/storing-and-sharing-data-from-a-workflow"
+    label: "Storing and sharing data from a workflow"
+  - url: "https://github.com/actions/download-artifact"
+    label: "actions/download-artifact — README and cross-run download docs"
+  - url: "https://github.com/orgs/community/discussions/109905"
+    label: "GitHub Community #109905 — Unable to find any artifacts troubleshooting"
+  - url: "https://stackoverflow.com/questions/78238187/unable-to-find-any-artifacts-for-the-associated-workflow-github-actions"
+    label: "Stack Overflow — Unable to find any artifacts for the associated workflow"

package/errors/runner-environment/macos-14-sonoma-eol.yml

@@ -0,0 +1,89 @@
+id: runner-environment-018
+title: "macOS 14 Sonoma Runner Deprecation — EOL November 2026"
+category: runner-environment
+severity: warning
+tags:
+  - macos
+  - deprecation
+  - runner-image
+  - eol
+  - migration
+patterns:
+  - regex: "##\\[error\\]This request was rejected because.*macos-14"
+    flags: "i"
+  - regex: "Image.*macos-14.*deprecated|macos-14.*no longer supported"
+    flags: "i"
+  - regex: "The requested image.*macos-14.*not available"
+    flags: "i"
+error_messages:
+  - "##[error]This request was rejected because the runner label 'macos-14' is no longer supported."
+  - "The macOS 14 image has been retired. Please update to macos-15 or macos-latest."
+root_cause: |
+  GitHub announced the deprecation of `macOS 14 Sonoma` runner images on the following schedule:
+  - **Deprecation begins**: July 6, 2026 — longer queue times during peak hours, brownout periods
+  - **Full retirement**: November 2, 2026 — jobs using `macos-14` will fail permanently
+
+  GitHub maintains only the latest two stable macOS major versions. Since macOS 26 Tahoe is now
+  GA on GitHub Actions, macOS 14 is the oldest and must retire.
+
+  **Brownout schedule** (jobs deliberately failed during these windows to force migration):
+  - October 5, 14:00 UTC – October 6, 00:00 UTC
+  - October 12, 14:00 UTC – October 13, 00:00 UTC
+  - October 16–30, 14:00 UTC – next day 00:00 UTC (escalating weekly)
+
+  Affected labels: `macos-14`, `macos-14-large`, `macos-14-xlarge`.
+fix: |
+  Update your workflow's `runs-on` label to a supported macOS version:
+
+  | Old label | Replace with |
+  |-----------|--------------|
+  | `macos-14` | `macos-latest` or `macos-15` or `macos-26` |
+  | `macos-14-large` | `macos-latest-large` or `macos-15-large` |
+  | `macos-14-xlarge` | `macos-latest-xlarge` or `macos-15-xlarge` or `macos-26-xlarge` |
+
+  If your workflow depends on macOS 14-specific software versions (e.g., Xcode 15, older
+  Python/Ruby), test carefully against macOS 15 before switching `macos-latest`.
+  See runner-environment-017 for macOS 15 → 26 migration notes if moving to `macos-latest`.
+fix_code:
+  - language: yaml
+    label: "Migrate from macos-14 to macos-15 (conservative) or macos-latest"
+    code: |
+      jobs:
+        build:
+          # Before:
+          # runs-on: macos-14
+
+          # Conservative: macos-15 (similar software stack, no OpenSSL jump)
+          runs-on: macos-15
+
+          # OR accept latest (currently macos-26 after June 15 2026):
+          # runs-on: macos-latest
+
+          steps:
+            - uses: actions/checkout@v4
+  - language: yaml
+    label: "Strategy matrix: test across multiple macOS versions during migration"
+    code: |
+      jobs:
+        build:
+          strategy:
+            matrix:
+              os: [macos-15, macos-26]
+          runs-on: ${{ matrix.os }}
+          steps:
+            - uses: actions/checkout@v4
+            - name: Build and test
+              run: make test
+prevention:
+  - "Subscribe to actions/runner-images GitHub Issues announcements label to receive deprecation notices well in advance."
+  - "Avoid pinning to specific macOS point versions (`macos-14`, `macos-15`) in long-lived workflows — use `macos-latest` and test proactively against the next version."
+  - "Run a matrix strategy against `macos-latest` and your pinned version to detect incompatibilities before they cause production failures."
+  - "Search your organization's workflows periodically for deprecated runner labels using: `gh search code 'runs-on: macos-14' --owner YOUR_ORG`."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/13518"
+    label: "GitHub Announcement: macOS 14 Sonoma deprecation timeline"
+  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources"
+    label: "Supported GitHub-hosted runner labels"
+source:
+  article: "https://htek.dev/articles/github-actions-debugging-guide"
+  section: "Runner deprecation and EOL"

package/errors/runner-environment/macos-latest-to-macos-26.yml

@@ -0,0 +1,127 @@
+id: runner-environment-017
+title: "macos-latest Label Now Points to macOS 26 Tahoe"
+category: runner-environment
+severity: error
+tags:
+  - macos
+  - runner-image
+  - breaking-change
+  - openssl
+  - xcode
+  - migration
+patterns:
+  - regex: "Error opening configuration file.*openssl"
+    flags: "i"
+  - regex: "SSL_CTX_new.*failed|SSL_connect.*SYSCALL error"
+    flags: "i"
+  - regex: "Could not find Xcode.*version.*16\\.\\d"
+    flags: "i"
+  - regex: "ruby.*requires.*Ruby (2|3\\.0|3\\.1|3\\.2|3\\.3)"
+    flags: "i"
+  - regex: "dyld.*Library not loaded.*libssl\\.1\\.1"
+    flags: "i"
+error_messages:
+  - "dyld[]: Library not loaded: /usr/local/opt/openssl@1.1/lib/libssl.1.1.dylib"
+  - "Could not find Xcode version '16.4'"
+  - "SSL_connect returned=1 errno=0 state=error: certificate verify failed"
+  - "Your Ruby version is 3.3.x, but your Gemfile specified ~> 3.3"
+  - "npm warn old lockfile"
+root_cause: |
+  The `macos-latest` label in GitHub Actions was migrated to point to macOS 26 Tahoe
+  beginning June 15, 2026 (completing by July 15, 2026). Previously it pointed to macOS 15
+  Sequoia. This migration includes several major software version changes that silently break
+  workflows:
+
+  - **OpenSSL**: 1.1.1w → 3.6.2 — The biggest breaking change. Many C/C++ projects,
+    Ruby gems (openssl), and Python packages that link against the system OpenSSL dynamically
+    will fail at runtime because libssl.1.1.dylib no longer ships with macOS 26.
+  - **Xcode**: Default changes from 16.4 to 26.4.1 (Xcode 26 series). Workflows pinning
+    `xcode-version: '16.4'` or relying on Clang 17 will break — Clang/LLVM jumps from 17 → 21.
+  - **Ruby**: 3.3.x → 3.4.x — Minor version bump can cause Gemfile constraint failures and
+    gem native extension compilation issues.
+  - **Node.js**: Default moves from 22 → 24 (though both images include Node 24 in cached tools).
+  - **npm**: 10.x → 11.x — Major npm version. Package-lock.json format changes possible.
+  - **Homebrew LLVM**: 18 → 20 (major version jump for workflows using `llvm@18` explicitly).
+fix: |
+  **Immediate mitigation:** Pin to `macos-15` to restore previous behavior while you migrate:
+
+  ```yaml
+  runs-on: macos-15
+  ```
+
+  **Proper fix** — address each breaking dependency:
+
+  1. **OpenSSL**: Brew-install a pinned OpenSSL version and set library paths:
+     ```bash
+     brew install openssl@1.1
+     export LDFLAGS="-L$(brew --prefix openssl@1.1)/lib"
+     export CPPFLAGS="-I$(brew --prefix openssl@1.1)/include"
+     ```
+     Or migrate to OpenSSL 3.x compatible code.
+
+  2. **Xcode**: Pin the Xcode version explicitly using `maxim-lobanov/setup-xcode`:
+     ```yaml
+     - uses: maxim-lobanov/setup-xcode@v1
+       with:
+         xcode-version: '16.4'
+     ```
+     Or migrate your project to Xcode 26.
+
+  3. **Ruby**: Update your Gemfile to accept 3.4.x (`~> 3.4`) or use `ruby/setup-ruby` to
+     pin a specific version:
+     ```yaml
+     - uses: ruby/setup-ruby@v1
+       with:
+         ruby-version: '3.3'
+     ```
+fix_code:
+  - language: yaml
+    label: "Pin to macos-15 for immediate rollback"
+    code: |
+      jobs:
+        build:
+          runs-on: macos-15   # pinned until macos-26 migration complete
+          steps:
+            - uses: actions/checkout@v4
+  - language: yaml
+    label: "Full macos-26 compatible workflow — pin Xcode, Ruby, and OpenSSL"
+    code: |
+      jobs:
+        build:
+          runs-on: macos-latest  # now macos-26
+          steps:
+            - uses: actions/checkout@v4
+
+            # Pin Xcode version explicitly
+            - uses: maxim-lobanov/setup-xcode@v1
+              with:
+                xcode-version: '26.4'
+
+            # Pin Ruby if needed
+            - uses: ruby/setup-ruby@v1
+              with:
+                ruby-version: '3.3'
+                bundler-cache: true
+
+            # If OpenSSL 1.1 is needed, install and export paths
+            - name: Install OpenSSL 1.1
+              run: |
+                brew install openssl@1.1
+                echo "LDFLAGS=-L$(brew --prefix openssl@1.1)/lib" >> $GITHUB_ENV
+                echo "CPPFLAGS=-I$(brew --prefix openssl@1.1)/include" >> $GITHUB_ENV
+prevention:
+  - "Avoid relying on `macos-latest` for builds that depend on specific system library versions (OpenSSL, LLVM). Pin to a concrete label like `macos-15`."
+  - "Subscribe to the actions/runner-images repository announcements to get advance notice of `macos-latest` label migrations."
+  - "Use `ruby/setup-ruby`, `actions/setup-node`, and `actions/setup-python` to pin language runtimes instead of relying on runner image defaults."
+  - "Test your macOS workflows against the new image early by substituting `macos-26` before the `macos-latest` migration completes."
+  - "Audit all dylib/framework dependencies — anything linking to libssl.1.1 must be migrated to OpenSSL 3.x or brew-pinned."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/14167"
+    label: "GitHub Announcement: macos-latest will use macos-26 in June 2026"
+  - url: "https://github.com/actions/runner-images/blob/main/images/macos/macos-26-arm64-Readme.md"
+    label: "macOS 26 arm64 image README — full software list"
+  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners"
+    label: "About GitHub-hosted runners — supported runner labels"
+source:
+  article: "https://htek.dev/articles/github-actions-debugging-guide"
+  section: "Runner image migrations"

package/errors/runner-environment/powershell-74-to-76-upgrade.yml

@@ -0,0 +1,112 @@
+id: runner-environment-019
+title: "PowerShell 7.4 → 7.6 LTS Upgrade Breaks pwsh Scripts"
+category: runner-environment
+severity: warning
+tags:
+  - powershell
+  - pwsh
+  - runner-image
+  - breaking-change
+  - windows
+  - linux
+patterns:
+  - regex: "The term 'ThreadJob\\\\\\\\Start-ThreadJob' is not recognized"
+    flags: "i"
+  - regex: "Cannot bind parameter.*ChildPath.*expected.*String.*got.*Array"
+    flags: "i"
+  - regex: "WildcardPattern.*backtick|escape.*pattern.*unexpected"
+    flags: "i"
+  - regex: "New-EventLog.*source.*trailing|event source.*not found"
+    flags: "i"
+error_messages:
+  - "The term 'ThreadJob\\Start-ThreadJob' is not recognized as a name of a cmdlet, function, script file, or executable program."
+  - "Cannot bind parameter 'ChildPath'. Cannot convert the 'System.Object[]' value of type 'System.Object[]' to type 'System.String'."
+  - "Start-ThreadJob : The term 'ThreadJob\\Start-ThreadJob' is not recognized"
+root_cause: |
+  GitHub Actions upgraded PowerShell from 7.4.x to 7.6 LTS on all runner images beginning
+  June 8, 2026 (completing June 15, 2026). This affects every runner OS: ubuntu-22.04,
+  ubuntu-24.04, ubuntu-slim, macos-14/15/26, windows-2022/2025/2025-vs2026.
+
+  PowerShell 7.6 is built on .NET 10 (7.4 was on .NET 8). The documented breaking changes are:
+
+  1. **ThreadJob module renamed**: `ThreadJob` module is now `Microsoft.PowerShell.ThreadJob`.
+     Scripts calling `ThreadJob\Start-ThreadJob` with the old module-qualified name will throw
+     a "not recognized" error. The cmdlet itself (`Start-ThreadJob`) still works without prefix.
+
+  2. **`Join-Path -ChildPath` now accepts `string[]`**: Parameter binding changed from `string`
+     to `string[]`. Existing code that passes multiple -ChildPath args may see binding errors
+     depending on how arguments were constructed.
+
+  3. **`WildcardPattern.Escape` now correctly escapes lone backticks**: Scripts that relied on
+     the previous (incorrect) behavior of backtick handling in wildcard patterns may produce
+     different results.
+
+  4. **Event source name trailing space removed**: New-EventLog / Write-EventLog source names
+     no longer have a trailing space. Scripts that matched exact event source names including
+     the trailing space (e.g., `"MySource "`) will fail to match.
+
+  5. **.NET 10 runtime**: Any `pwsh` script using .NET types or reflection that was tested
+     against .NET 8 behavior may see subtle differences.
+fix: |
+  **ThreadJob module name** — the most common breaking change:
+  Replace `ThreadJob\Start-ThreadJob` with `Microsoft.PowerShell.ThreadJob\Start-ThreadJob`,
+  or just call `Start-ThreadJob` without the module qualifier.
+
+  **Event source name** — if you match exact source names:
+  Trim any trailing spaces from source name comparisons.
+
+  **Pin PowerShell version** if you need time to migrate (not recommended long-term):
+  Install a specific pwsh version in your workflow before running scripts.
+
+  **Test locally**: Install PowerShell 7.6 (`winget install Microsoft.PowerShell`) and run
+  your scripts to catch any remaining issues before they surface in CI.
+fix_code:
+  - language: yaml
+    label: "Fix ThreadJob module-qualified name"
+    code: |
+      # In your PowerShell script — change this:
+      #   ThreadJob\Start-ThreadJob -ScriptBlock { ... }
+      # To either:
+      #   Start-ThreadJob -ScriptBlock { ... }          # simplest fix
+      #   Microsoft.PowerShell.ThreadJob\Start-ThreadJob -ScriptBlock { ... }  # fully qualified
+  - language: yaml
+    label: "Pin PowerShell version as a temporary workaround"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            # Pin pwsh to 7.4.x temporarily while migrating
+            - name: Install PowerShell 7.4
+              run: |
+                wget -q "https://github.com/PowerShell/PowerShell/releases/download/v7.4.10/powershell_7.4.10-1.deb_amd64.deb"
+                sudo dpkg -i powershell_7.4.10-1.deb_amd64.deb
+
+            - name: Run PowerShell script
+              shell: pwsh
+              run: ./scripts/build.ps1
+  - language: yaml
+    label: "Fix event source name trailing-space match"
+    code: |
+      # Before (broken on 7.6):
+      # if ($event.Source -eq "MyApp ") { ... }
+      #
+      # After (works on 7.4 and 7.6):
+      # if ($event.Source.Trim() -eq "MyApp") { ... }
+prevention:
+  - "Subscribe to actions/runner-images announcements for PowerShell upgrade notices well before they ship."
+  - "Always use unqualified cmdlet names (`Start-ThreadJob`) rather than module-qualified names (`ThreadJob\\Start-ThreadJob`) to avoid module-rename breakage."
+  - "Run your PowerShell scripts through PSScriptAnalyzer with the latest rule set after any PS version upgrade."
+  - "Test pwsh workflows in a matrix with the previous and new PS version during runner image transition periods."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/14150"
+    label: "GitHub Announcement: PowerShell 7.4 → 7.6 upgrade on all runner images"
+  - url: "https://learn.microsoft.com/en-us/powershell/scripting/whats-new/what-s-new-in-powershell-76"
+    label: "PowerShell 7.6 release notes and breaking changes"
+  - url: "https://learn.microsoft.com/en-us/powershell/scripting/install/powershell-support-lifecycle"
+    label: "PowerShell support lifecycle"
+source:
+  article: "https://htek.dev/articles/github-actions-debugging-guide"
+  section: "Runner image tool version changes"

package/errors/runner-environment/service-container-unhealthy.yml

@@ -0,0 +1,126 @@
+id: runner-environment-021
+title: "Service Container Marked Unhealthy — Health Check Timeout"
+category: runner-environment
+severity: error
+tags:
+  - service-container
+  - healthcheck
+  - docker
+  - timeout
+  - postgres
+  - redis
+  - rabbitmq
+patterns:
+  - regex: "service is unhealthy"
+    flags: "i"
+  - regex: "Failed to initialize.*service is unhealthy"
+    flags: "i"
+  - regex: "##\\[error\\]Failed to initialize.*service"
+    flags: "i"
+  - regex: "container_id.*unhealthy"
+    flags: "i"
+error_messages:
+  - "##[error]Failed to initialize, rabbitmq service is unhealthy."
+  - "##[error]Failed to initialize, postgres service is unhealthy."
+  - "##[error]Failed to initialize, redis service is unhealthy."
+  - "unhealthy"
+  - "service is starting, waiting 29 seconds before checking again."
+root_cause: |
+  GitHub Actions checks the Docker HEALTHCHECK status of service containers
+  before allowing dependent job steps to run. If the container does not
+  transition to `healthy` within the runner's fixed retry window, the job
+  fails with "service is unhealthy".
+
+  This commonly occurs because:
+  1. **No options specified** — Docker uses the image's built-in HEALTHCHECK,
+     which may be missing, too aggressive, or unsuitable for the CI environment.
+  2. **Startup time** — services like PostgreSQL, RabbitMQ, or Elasticsearch
+     take longer to initialize on GitHub-hosted runners than on local machines,
+     and the default health-check interval/retries expire before they're ready.
+  3. **Wrong health-check command** — a network ping health check may fail if
+     the service port isn't yet bound even though the process is running.
+  4. **Missing `--health-start-period`** — without a start period, Docker counts
+     health-check failures from container start, before the service has had time
+     to initialize.
+
+  Documented in actions/example-services issue #3.
+fix: |
+  Add `options:` to the service container definition with explicit health-check
+  parameters suited to the service and GitHub-hosted runner environment:
+
+  - `--health-cmd`: Use a service-native health check command, not a TCP probe.
+    Examples:
+      PostgreSQL: `pg_isready -U postgres`
+      Redis:      `redis-cli ping`
+      MySQL:      `mysqladmin ping -h localhost`
+      RabbitMQ:   `rabbitmqctl node_health_check`
+
+  - `--health-interval 10s`: Check every 10 seconds
+  - `--health-timeout 5s`: Allow up to 5 seconds per check
+  - `--health-retries 5`: Retry up to 5 times before marking unhealthy
+  - `--health-start-period 30s`: Give 30 seconds before counting failures
+
+  If the image lacks a health check and the options approach is insufficient,
+  add an explicit wait step after job start using the service label name to
+  poll readiness with a loop.
+fix_code:
+  - language: yaml
+    label: "PostgreSQL service container with proper health check"
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          services:
+            postgres:
+              image: postgres:16
+              env:
+                POSTGRES_PASSWORD: postgres
+                POSTGRES_DB: testdb
+              ports:
+                - 5432:5432
+              options: >-
+                --health-cmd "pg_isready -U postgres"
+                --health-interval 10s
+                --health-timeout 5s
+                --health-retries 5
+                --health-start-period 30s
+          steps:
+            - run: psql postgresql://postgres:postgres@localhost:5432/testdb -c "SELECT 1"
+  - language: yaml
+    label: "Redis service container with proper health check"
+    code: |
+      services:
+        redis:
+          image: redis:7
+          ports:
+            - 6379:6379
+          options: >-
+            --health-cmd "redis-cli ping"
+            --health-interval 10s
+            --health-timeout 5s
+            --health-retries 5
+  - language: yaml
+    label: "Fallback — explicit wait step if health check unreliable"
+    code: |
+      steps:
+        - name: Wait for PostgreSQL to be ready
+          run: |
+            until pg_isready -h localhost -p 5432 -U postgres; do
+              echo "Waiting for postgres..."
+              sleep 2
+            done
+          timeout-minutes: 2
+prevention:
+  - "Always specify `options:` with `--health-cmd`, `--health-interval`, `--health-retries`, and `--health-start-period` for every service container."
+  - "Use service-native health check commands (pg_isready, redis-cli ping) rather than generic TCP probes."
+  - "Add `--health-start-period` of 20-30 seconds for services with slow initialization (PostgreSQL, Elasticsearch, RabbitMQ)."
+  - "Test health check timing locally in Docker before relying on it in CI: `docker run --health-cmd '...' --health-interval 5s <image>`."
+docs:
+  - url: "https://docs.github.com/en/actions/using-containerized-services/about-service-containers"
+    label: "About service containers"
+  - url: "https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idservicesservice_idoptions"
+    label: "Workflow syntax — services options"
+  - url: "https://github.com/actions/example-services/issues/3"
+    label: "actions/example-services #3 — Service container health check questions and fixes"
+  - url: "https://stackoverflow.com/questions/66763353/how-to-health-check-a-service-in-github"
+    label: "Stack Overflow — How to health check a service in GitHub Actions"

package/errors/runner-environment/windows-latest-vs2026-migration.yml

@@ -0,0 +1,131 @@
+id: runner-environment-020
+title: "windows-latest Now Uses Visual Studio 2026 — VS 2022 Components Removed"
+category: runner-environment
+severity: error
+tags:
+  - windows
+  - visual-studio
+  - runner-image
+  - breaking-change
+  - msbuild
+  - dotnet
+patterns:
+  - regex: "MSB[0-9]+.*Visual Studio 2022|The tools version.*15\\.0.*is not available"
+    flags: "i"
+  - regex: "Dotfuscator.*not found|dotfuscator.*missing"
+    flags: "i"
+  - regex: "Component.*Azure.ServiceFabric.Tools.*not installed"
+    flags: "i"
+  - regex: "VC\\.Tools\\.ARM.*not found|Microsoft\\.VisualStudio\\.Component\\.VC\\.Tools\\.ARM"
+    flags: "i"
+  - regex: "error.*NETSDK1045.*The current .NET SDK does not support targeting .NET (5|6|7)"
+    flags: "i"
+  - regex: "Visual Studio.*version 17\\.[0-9]+.*not found|MSBuild.*17\\.[0-9]+.*not available"
+    flags: "i"
+error_messages:
+  - "MSB4019: The imported project 'Microsoft.CppBuild.targets' was not found."
+  - "Error: Dotfuscator is not installed. Please install Dotfuscator Community."
+  - "The component 'Microsoft.VisualStudio.Component.Azure.ServiceFabric.Tools' is not installed."
+  - "MSBUILD : error MSB1009: Project file does not exist. Switch: /version:17"
+  - "The current .NET SDK does not support targeting .NET 7.0."
+root_cause: |
+  The `windows-latest` and `windows-2025` labels in GitHub Actions were migrated to use
+  **Windows Server 2025 with Visual Studio 2026** beginning June 8, 2026 (completing
+  June 15, 2026). Previously these labels ran Visual Studio 2022 (version 17.x).
+
+  Visual Studio 2026 (version 18.x) ships with MSBuild 18 and removes several VS 2022
+  components that workflows may depend on:
+
+  **Removed VS components:**
+  - `Component.Dotfuscator` — .NET obfuscation tool
+  - `Microsoft.VisualStudio.Component.Azure.ServiceFabric.Tools`
+  - `Microsoft.VisualStudio.Component.TestTools.CodedUITest`
+  - `Microsoft.VisualStudio.Component.TestTools.WebLoadTest`
+  - `Microsoft.VisualStudio.Component.VC.Tools.ARM` — ARM cross-compilation toolchain
+  - `Microsoft.VisualStudio.Component.VC.Modules.x86.x64`
+  - `Microsoft.VisualStudio.Component.VC.Runtimes.ARM.Spectre`
+  - `Microsoft.VisualStudio.Component.VC.MFC.ARM` and `.ARM.Spectre`
+  - `Microsoft.VisualStudio.Component.VC.ATL.ARM` and `.ARM.Spectre`
+  - `Microsoft.VisualStudio.ComponentGroup.Azure.CloudServices`
+  - `Microsoft.VisualStudio.ComponentGroup.Azure.ResourceManager.Tools`
+
+  **Other changes:**
+  - CMake updated from 3.31.6 → 4.3.2 (adds VS 18 2026 generator, deprecates some older generators)
+  - Android Command Line Tools updated from 16.0 → 19.0
+  - MSVC v143 toolset is added as a compatibility shim for projects requiring it
+fix: |
+  **Immediate rollback:** Pin to `windows-2022` to keep Visual Studio 2022:
+  ```yaml
+  runs-on: windows-2022
+  ```
+  Note: `windows-2022` continues to run VS 2022 (version 17.x) and will remain supported.
+
+  **For removed components:**
+  - **Dotfuscator**: Remove from build pipeline, or install manually via the Dotfuscator
+    Community installer in a workflow step. Consider alternatives like ConfuserEx.
+  - **ARM VC toolchain** (`VC.Tools.ARM`): Use the separate `windows-11-arm64` runner label
+    for native ARM64 builds, or cross-compile via MSVC v143 shim that ships with VS 2026.
+  - **Azure Service Fabric Tools**: Install the Service Fabric SDK directly via PowerShell
+    if your workflow requires it.
+  - **CMake generator**: Update your CMake invocation from `-G "Visual Studio 17 2022"` to
+    `-G "Visual Studio 18 2026"`.
+fix_code:
+  - language: yaml
+    label: "Pin to windows-2022 for immediate rollback (VS 2022)"
+    code: |
+      jobs:
+        build:
+          # Temporarily pin to VS 2022 while migrating
+          runs-on: windows-2022
+          steps:
+            - uses: actions/checkout@v4
+            - name: Build
+              run: msbuild MyProject.sln /p:Configuration=Release
+  - language: yaml
+    label: "Migrate to VS 2026 — update CMake generator and toolset"
+    code: |
+      jobs:
+        build:
+          runs-on: windows-latest  # now VS 2026
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Configure CMake (VS 2026 generator)
+              run: |
+                cmake -B build -G "Visual Studio 18 2026" -A x64 `
+                  -DCMAKE_BUILD_TYPE=Release
+
+            - name: Build
+              run: cmake --build build --config Release
+
+            # If you need MSVC v143 (VS 2022 toolset) compatibility:
+            # cmake -B build -G "Visual Studio 18 2026" -A x64 -T v143
+  - language: yaml
+    label: "Test against both VS 2022 and VS 2026 during migration"
+    code: |
+      jobs:
+        build:
+          strategy:
+            matrix:
+              os: [windows-2022, windows-latest]
+          runs-on: ${{ matrix.os }}
+          steps:
+            - uses: actions/checkout@v4
+            - name: Build and test
+              run: msbuild MyProject.sln /p:Configuration=Release /t:Build,Test
+prevention:
+  - "Avoid depending on specific Visual Studio components that are not part of the core VS 2022/2026 workloads — install them explicitly in your workflow if needed."
+  - "Subscribe to actions/runner-images announcements to receive advance notice of `windows-latest` migrations."
+  - "Test your Windows workflows against `windows-2025-vs2026` before the `windows-latest` migration completes."
+  - "Use MSBuild's `-T v143` toolset flag to target the VS 2022 compiler toolchain from within VS 2026 if full migration is not yet feasible."
+  - "Search your workflows for CMake generator strings like 'Visual Studio 17 2022' and update them proactively."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/14017"
+    label: "GitHub Announcement: windows-latest migrates to Visual Studio 2026"
+  - url: "https://github.com/actions/runner-images/issues/14016"
+    label: "GitHub Announcement: Windows Server 2025 with VS 2026 now GA"
+  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners"
+    label: "About GitHub-hosted runners"
+source:
+  article: "https://htek.dev/articles/github-actions-debugging-guide"
+  section: "Windows runner Visual Studio migrations"

package/errors/silent-failures/hashfiles-empty-string-cache-collision.yml

@@ -0,0 +1,96 @@
+id: silent-failures-009
+title: "hashFiles() Returns Empty String When No Files Match — Silent Cache Key Collision"
+category: silent-failures
+severity: silent-failure
+tags:
+  - cache
+  - hashFiles
+  - cache-key
+  - collision
+  - glob
+  - silent-failure
+patterns:
+  - regex: "key: [A-Za-z0-9_-]+-$"
+    flags: "m"
+  - regex: "Cache restored from key: [A-Za-z0-9_-]+(?!-[0-9a-f]{64})"
+    flags: "i"
+error_messages:
+  - "Cache restored from key: Linux-node-"
+  - "Cache restored from key: Linux-pip-"
+  - "No error shown — workflow succeeds but wrong cache is restored"
+root_cause: |
+  The `hashFiles()` expression function returns an empty string (not an error)
+  when the supplied glob pattern matches no files in the workspace. This silently
+  truncates the cache key, turning a key like:
+
+    ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+
+  into:
+
+    Linux-node-
+
+  when no package-lock.json exists. This short, predictable key collides across
+  branches and runs, causing stale or wrong cache content to be restored without
+  any warning. The workflow log shows the cache as restored successfully.
+
+  Documented in actions/runner issue #894. Commonly triggered by:
+  - Lockfile not yet committed (new project setup)
+  - Wrong glob path (e.g., `**/package-lock.json` but lockfile is at root)
+  - Wrong working directory at cache step execution time
+  - Matrix jobs where not all matrix values have a matching lockfile
+fix: |
+  Add a fallback value to the hashFiles() expression using the `||` operator so
+  the key is always deterministic even when no files match:
+
+    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') || 'no-lockfile' }}
+
+  Also verify that the glob actually matches the file by running
+  `find . -name "package-lock.json"` in a debug step before the cache step.
+
+  For matrix workflows, include the matrix value in the key to prevent
+  cross-matrix collisions even when hash is empty:
+
+    key: ${{ runner.os }}-node-${{ matrix.node-version }}-${{ hashFiles('**/package-lock.json') || 'no-lockfile' }}
+fix_code:
+  - language: yaml
+    label: "WRONG — hashFiles with no fallback (silently short key on miss)"
+    code: |
+      - uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+          # ❌ If no package-lock.json found, key becomes "Linux-node-"
+          # All runs share the same truncated key → wrong cache restored silently
+  - language: yaml
+    label: "RIGHT — hashFiles with explicit fallback"
+    code: |
+      - uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') || 'no-lockfile' }}
+          # ✅ If no lockfile, key becomes "Linux-node-no-lockfile" — deterministic and unique
+          restore-keys: |
+            ${{ runner.os }}-node-
+  - language: yaml
+    label: "DEBUG — verify glob matches before caching"
+    code: |
+      - name: Debug — check lockfile exists
+        run: find . -name "package-lock.json" | head -5
+        # If empty output: fix the glob or ensure lockfile is committed
+
+      - uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') || 'no-lockfile' }}
+prevention:
+  - "Always provide a `|| 'fallback-value'` after any hashFiles() call to prevent empty-string cache key truncation."
+  - "Test your hashFiles() glob locally: run `find . -name 'your-lockfile'` from the repo root to confirm it matches."
+  - "Include stable discriminators (runner.os, matrix values, Node version) in cache keys to reduce collision risk."
+  - "Review restored cache key in workflow logs — a key ending in just a short prefix without a 64-char hash is a sign of an empty hashFiles()."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/evaluate-expressions-in-workflows-and-actions#hashfiles"
+    label: "hashFiles() function documentation"
+  - url: "https://github.com/actions/runner/issues/894"
+    label: "actions/runner #894 — hashFiles returns empty string instead of hash"
+  - url: "https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows"
+    label: "Caching dependencies to speed up workflows"

package/errors/triggers/environment-protection-rules-silent-block.yml

@@ -0,0 +1,105 @@
+id: triggers-006
+title: "Job Blocked Silently by Environment Protection Rules — No Clear Log Message"
+category: triggers
+severity: warning
+tags:
+  - environment
+  - protection-rules
+  - deployment
+  - approval
+  - branch-restriction
+  - silent-wait
+patterns:
+  - regex: "Waiting for.*environment.*approval"
+    flags: "i"
+  - regex: "Branch '.*' is not allowed to deploy to .* due to environment protection rules"
+    flags: "i"
+  - regex: "Expected.*Waiting for status to be reported"
+    flags: "i"
+error_messages:
+  - "Branch 'feature/my-branch' is not allowed to deploy to production due to environment protection rules."
+  - "Waiting for approval — This workflow run requires approval from the environment's configured reviewers."
+  - "Expected — Waiting for status to be reported"
+root_cause: |
+  GitHub Environments can have protection rules that gate job execution:
+  - **Required reviewers**: A human must approve the deployment before the job runs.
+  - **Branch/tag restrictions**: Only specific branches or tags are allowed to
+    deploy to the environment (e.g., only `main` can deploy to `production`).
+  - **Required status checks**: External status checks must pass first.
+  - **Wait timers**: A mandatory delay before the job can proceed.
+
+  When a job targets an environment with unsatisfied protection rules, it enters
+  a waiting state in the GitHub UI. The **workflow log may not show a clear
+  failure message** — the job simply appears as pending or "Expected — Waiting
+  for status to be reported." This is a common source of confusion for teams
+  that enable environment protection rules for the first time, especially in
+  forks or feature-branch workflows where the branch is not in the allowed list.
+
+  Documented in GitHub Community discussions #39054 and #26698.
+fix: |
+  1. **Check environment settings**: Repository Settings → Environments → select
+     the environment → review protection rules (required reviewers, deployment
+     branches, required checks, wait timers).
+
+  2. **For branch restriction failures**: Add the branch that the workflow runs
+     on to the environment's "Deployment branches and tags" list, or change the
+     policy to "No restriction" for non-production environments.
+
+  3. **For pending approval**: A configured reviewer must approve the deployment
+     in the GitHub UI (Actions tab → select the run → click "Review deployments").
+
+  4. **For automated CI**: Use a separate environment with no protection rules
+     for automated test deployments, and reserve protected environments for
+     production deployments that require human approval.
+
+  5. **For fork PRs**: Environments with protection rules can silently block
+     fork PRs since the fork branch is not in the allowed branch list — use a
+     separate no-protection environment for fork PR validation jobs.
+fix_code:
+  - language: yaml
+    label: "Use separate environments for CI vs production"
+    code: |
+      jobs:
+        deploy-staging:
+          runs-on: ubuntu-latest
+          environment: staging    # ✅ no protection rules — runs immediately
+          steps:
+            - run: ./deploy.sh staging
+
+        deploy-production:
+          needs: deploy-staging
+          runs-on: ubuntu-latest
+          environment: production  # 🔒 has required reviewers — waits for approval
+          if: github.ref == 'refs/heads/main'  # ✅ only main is in allowed branch list
+          steps:
+            - run: ./deploy.sh production
+  - language: yaml
+    label: "Check branch restriction: ensure workflow branch is in allowed list"
+    code: |
+      # In GitHub UI: Settings → Environments → production → Deployment branches
+      # Add "main" or change policy to match your workflow's ref.
+      #
+      # In workflow: use github.ref_name to verify before targeting environment
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          # Only run on main — matches production environment's branch restriction
+          if: github.ref == 'refs/heads/main'
+          environment: production
+          steps:
+            - run: ./deploy.sh
+prevention:
+  - "Document environment protection rules in your repository's CONTRIBUTING.md so all developers know which branches can deploy where."
+  - "Test protection rules in a staging environment before applying them to production — the silent-wait behavior is surprising on first encounter."
+  - "For automated CI workflows that run on feature branches, use environments without branch restrictions or required reviewers."
+  - "After enabling environment protection rules, verify the workflow can actually trigger by running a test deployment from an allowed branch."
+  - "Monitor for stuck jobs in the Actions tab — a job sitting in 'waiting' or 'Expected' state usually means an environment protection rule is blocking it."
+docs:
+  - url: "https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment"
+    label: "Using environments for deployment — protection rules"
+  - url: "https://github.com/orgs/community/discussions/39054"
+    label: "GitHub Community #39054 — Branch not allowed to deploy due to environment protection rules"
+  - url: "https://github.com/orgs/community/discussions/26698"
+    label: "GitHub Community #26698 — Job stuck in Expected / Waiting for status to be reported"
+  - url: "https://stackoverflow.com/questions/72109150/github-action-avoid-approval-on-same-environment-rule-within-same-workflow"
+    label: "Stack Overflow — Avoiding approval in same environment within same workflow"

package/errors/yaml-syntax/env-context-unavailable-job-level.yml

@@ -0,0 +1,109 @@
+id: yaml-syntax-014
+title: "env Context Not Available at Job-Level if or Reusable Workflow Positions"
+category: yaml-syntax
+severity: error
+tags:
+  - env
+  - context
+  - job-if
+  - reusable-workflow
+  - expression
+  - context-availability
+patterns:
+  - regex: "Unrecognized named-value: 'env'"
+    flags: "i"
+  - regex: "The workflow is not valid.*Unrecognized named-value: 'env'"
+    flags: "i"
+  - regex: "Located at position \\d+ within expression.*env\\."
+    flags: "i"
+error_messages:
+  - "The workflow is not valid. .github/workflows/<workflow>.yml (Line: X, Col: Y): Unrecognized named-value: 'env'. Located at position Z within expression: <expression>"
+  - "Unrecognized named-value: 'env'. Located at position 1 within expression"
+root_cause: |
+  GitHub Actions evaluates job-level expressions (jobs.<job_id>.if, certain
+  jobs.<job_id>.with: inputs for reusable workflows) before any steps run and
+  before step-level env values are available. Because the `env` context is
+  only populated at step execution time, using `env.MY_VAR` inside a job-level
+  `if:` condition or inside a reusable workflow's `jobs:` block triggers a
+  validation error at parse time rather than a runtime failure.
+
+  This affects:
+  - `jobs.<job_id>.if: ${{ env.MY_VAR == 'foo' }}`
+  - `jobs.<job_id>.with:` fields referencing `env.*` in a reusable workflow call
+  - Any top-level workflow expression that attempts to read `env` context
+
+  Documented in actions/runner issues #1189, #1661, and #2372.
+fix: |
+  Replace env context references in job-level positions with contexts that are
+  available at job evaluation time:
+  - Use `vars.*` (repository/environment variables) for static configuration values
+  - Use `github.*` context for event-driven values
+  - Use `inputs.*` for values passed into reusable workflows
+  - Use job outputs (`needs.<job_id>.outputs.<name>`) to pass dynamic values
+    computed in earlier steps to downstream job `if:` conditions
+
+  If the value is truly dynamic and set in a previous step, emit it as a step
+  output → job output → needs output chain so downstream jobs can reference it.
+fix_code:
+  - language: yaml
+    label: "WRONG — env context in job-level if (fails validation)"
+    code: |
+      jobs:
+        deploy:
+          if: ${{ env.DEPLOY_ENV == 'production' }}  # ❌ env not available here
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Deploying"
+  - language: yaml
+    label: "RIGHT — use vars context or job outputs instead"
+    code: |
+      # Option 1: use vars (repository/environment variables) for static config
+      jobs:
+        deploy:
+          if: ${{ vars.DEPLOY_ENV == 'production' }}  # ✅ vars available at job level
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Deploying"
+
+      # Option 2: compute in a preceding job, emit as output
+      jobs:
+        compute-env:
+          runs-on: ubuntu-latest
+          outputs:
+            deploy_env: ${{ steps.set-env.outputs.deploy_env }}
+          steps:
+            - id: set-env
+              run: echo "deploy_env=production" >> $GITHUB_OUTPUT
+
+        deploy:
+          needs: compute-env
+          if: ${{ needs.compute-env.outputs.deploy_env == 'production' }}
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Deploying"
+  - language: yaml
+    label: "RIGHT — reusable workflow: pass value via inputs not env"
+    code: |
+      # Caller workflow
+      jobs:
+        call-deploy:
+          uses: ./.github/workflows/deploy.yml
+          with:
+            environment: production  # ✅ pass via inputs, not env
+          secrets: inherit
+prevention:
+  - "Consult the GitHub docs context availability table before writing expressions — not all contexts are available at every YAML key position."
+  - "For job-level if conditions, use `vars.*`, `github.*`, or `needs.<job>.outputs.*` — never `env.*`."
+  - "For reusable workflow inputs, pass values explicitly through `with:` inputs rather than relying on caller env context."
+  - "Use `vars` (repository/environment variables) as a replacement for env-based feature flags that need to be available at job evaluation time."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#context-availability"
+    label: "Context availability — which contexts are available at each YAML key"
+  - url: "https://github.com/actions/runner/issues/1189"
+    label: "actions/runner #1189 — Unrecognized named-value: 'env' for job conditional"
+  - url: "https://github.com/actions/runner/issues/1661"
+    label: "actions/runner #1661 — env unrecognised in job-level if when calling reusable workflow"
+  - url: "https://github.com/actions/runner/issues/2372"
+    label: "actions/runner #2372 — Unrecognized named-value: 'env' in reusable workflow jobs"
+  - url: "https://stackoverflow.com/questions/76471787/why-is-env-context-not-available-in-github-action-job-level-if-statement"
+    label: "Stack Overflow — Why is env context not available in job level if statement?"

package/package.json

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