@htekdev/actions-debugger 1.0.71 → 1.0.73

package/errors/runner-environment/arm64-runner-binary-exec-format-error.yml

@@ -0,0 +1,100 @@
+id: runner-environment-133
+title: 'ARM64 runners: downloaded x86_64 binary fails with "Exec format error" — wrong architecture'
+category: runner-environment
+severity: error
+tags:
+  - arm64
+  - aarch64
+  - binary
+  - exec-format-error
+  - ubuntu-arm
+  - architecture
+patterns:
+  - regex: 'cannot execute binary file: Exec format error'
+    flags: 'i'
+  - regex: 'Exec format error'
+    flags: 'i'
+  - regex: 'exec.*format error'
+    flags: 'i'
+error_messages:
+  - './my-tool: cannot execute binary file: Exec format error'
+  - '/usr/local/bin/kubectl: cannot execute binary file: Exec format error'
+  - 'bash: ./tool: cannot execute binary file: Exec format error'
+root_cause: |
+  GitHub-hosted ubuntu-24.04-arm and ubuntu-22.04-arm runners use ARM64 (aarch64) CPUs.
+  The RUNNER_ARCH environment variable returns ARM64 on these runners, not X64.
+
+  Workflows that download pre-built binaries using hardcoded architecture suffixes like
+  linux-amd64, linux-x86_64, or linux-x64 download x86_64 binaries that cannot execute on
+  ARM64 hardware. The Linux kernel rejects the binary with "Exec format error" (ENOEXEC)
+  because the ELF architecture header in the binary does not match the host CPU.
+
+  Common patterns that break:
+  - Hardcoded URL: https://example.com/tool-linux-amd64.tar.gz
+  - Shell variable set once: ARCH="amd64" without checking RUNNER_ARCH
+  - Workflow matrix that includes ubuntu-24.04-arm without updating download URLs
+  - Third-party scripts that assume x86_64 without ARM64 support
+
+  This is a silent-ish failure — the binary downloads successfully (HTTP 200), extracts
+  without error, but fails only when executed.
+fix: |
+  Use the RUNNER_ARCH environment variable or uname -m to detect architecture and select
+  the correct binary:
+
+  - RUNNER_ARCH is X64 on x86_64 runners, ARM64 on ARM64 runners
+  - uname -m returns x86_64 on x86_64, aarch64 on ARM64
+
+  Normalize to the convention used by the tool's release naming (amd64/arm64 or x86_64/aarch64).
+  Where possible, prefer using setup-* actions that handle multi-architecture automatically.
+fix_code:
+  - language: yaml
+    label: 'Detect architecture and download correct binary'
+    code: |
+      jobs:
+        install-tool:
+          runs-on: ${{ matrix.runner }}
+          strategy:
+            matrix:
+              runner: [ubuntu-24.04, ubuntu-24.04-arm]
+          steps:
+            - name: Detect architecture and download tool
+              run: |
+                ARCH=$(uname -m)
+                case "$ARCH" in
+                  x86_64)  DL_ARCH="amd64" ;;
+                  aarch64) DL_ARCH="arm64" ;;
+                  *) echo "Unsupported arch: $ARCH"; exit 1 ;;
+                esac
+                curl -sSL "https://example.com/tool-linux-${DL_ARCH}.tar.gz" | tar xz
+                sudo mv tool /usr/local/bin/
+
+  - language: yaml
+    label: 'Use RUNNER_ARCH environment variable (GitHub-native)'
+    code: |
+      jobs:
+        install-tool:
+          runs-on: ubuntu-24.04-arm
+          steps:
+            - name: Install tool using RUNNER_ARCH
+              run: |
+                # RUNNER_ARCH is X64 or ARM64 (uppercase)
+                if [ "$RUNNER_ARCH" = "ARM64" ]; then
+                  DL_ARCH="arm64"
+                else
+                  DL_ARCH="amd64"
+                fi
+                curl -sSL "https://releases.example.com/tool-linux-${DL_ARCH}" -o /usr/local/bin/tool
+                chmod +x /usr/local/bin/tool
+prevention:
+  - 'Never hardcode linux-amd64 or linux-x86_64 in binary download URLs — always parameterize by architecture'
+  - 'Prefer setup-* GitHub Actions (setup-node, setup-go, setup-java) over manual binary downloads — they handle ARM64 automatically'
+  - 'Add ubuntu-24.04-arm to your test matrix to catch architecture issues before they affect users'
+  - 'Check tool release pages for ARM64 availability before migrating to ARM64 runners — not all tools provide arm64 builds'
+  - 'Use RUNNER_ARCH (GitHub variable) or uname -m (portable) to detect architecture in shell scripts'
+docs:
+  - 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-hosted runners — supported runner types including ARM64'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables#default-environment-variables'
+    label: 'Default environment variables — RUNNER_ARCH values'
+  - url: 'https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2404-ARM64-Readme.md'
+    label: 'ubuntu-24.04-arm runner software report'

package/errors/runner-environment/ubuntu-24-no-swap-oom-exit-137.yml

@@ -0,0 +1,124 @@
+id: runner-environment-135
+title: 'ubuntu-24.04: no swap memory — memory-intensive builds killed with exit code 137 (OOM)'
+category: runner-environment
+severity: error
+tags:
+  - oom
+  - memory
+  - swap
+  - ubuntu-24
+  - exit-137
+  - killed
+patterns:
+  - regex: 'Error 137'
+    flags: 'i'
+  - regex: 'exit code 137'
+    flags: 'i'
+  - regex: '^Killed\s*$'
+    flags: 'm'
+  - regex: 'out of memory|OOM|oom.killer'
+    flags: 'i'
+error_messages:
+  - 'make: *** [Makefile:42: build] Error 137'
+  - 'Killed'
+  - 'Process exited with code 137'
+  - 'error Command failed with exit code 137'
+  - 'npm ERR! code 137'
+root_cause: |
+  GitHub-hosted ubuntu-24.04 runners provide approximately 29GB RAM but have no swap space.
+  Ubuntu 22.04 runners provided about 6GB of swap as overflow capacity. When a job exhausts
+  physical RAM, the Linux OOM killer terminates the offending process with SIGKILL (signal 9),
+  producing exit code 137 (128 + 9).
+
+  The killed process may be:
+  - Node.js during webpack/esbuild/rollup bundle generation for large frontend projects
+  - Gradle during Android AAB/APK build or large multi-module Java projects
+  - Electron Forge/Builder packaging step
+  - C/C++ linker (ld) linking large binaries with many object files
+  - Cargo (Rust) compiling with high parallelism or many dependencies
+
+  The failure is often hard to diagnose because:
+  - No explicit "Out of Memory" message appears in the workflow log
+  - The step log simply shows "Killed" and exit code 137
+  - The runner does not report memory usage in the workflow summary
+
+  If the same workflow runs on ubuntu-22.04 without issues, missing swap is the likely cause.
+fix: |
+  Option A — Add a swap file manually before the memory-intensive step. This adds ~30 seconds
+  to job setup but provides 8GB of overflow capacity:
+
+  Option B — Reduce peak memory usage:
+  - Node.js: pass --max-old-space-size=N (MB) to node or set NODE_OPTIONS env var
+  - Gradle: reduce org.gradle.jvmargs heap in gradle.properties
+  - Cargo: set CARGO_BUILD_JOBS=2 to reduce parallel compilation
+  - webpack: use --parallel false or reduce splitChunks settings
+
+  Option C — Use a larger GitHub-hosted runner with more RAM (requires paid plan):
+  ubuntu-24.04 with 64GB RAM is available as a larger runner.
+fix_code:
+  - language: yaml
+    label: 'Add 8GB swap file before memory-intensive build step'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-24.04
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Add swap space
+              run: |
+                sudo fallocate -l 8G /swapfile
+                sudo chmod 600 /swapfile
+                sudo mkswap /swapfile
+                sudo swapon /swapfile
+                swapon --show
+                free -h
+
+            - name: Build (memory-intensive)
+              run: npm run build
+
+  - language: yaml
+    label: 'Reduce Node.js memory usage with --max-old-space-size'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-24.04
+          env:
+            NODE_OPTIONS: '--max-old-space-size=6144'
+          steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-node@v4
+              with:
+                node-version: '20'
+            - run: npm ci
+            - run: npm run build
+
+  - language: yaml
+    label: 'Reduce Gradle heap for Android/Java builds'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-24.04
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Set Gradle memory limits
+              run: |
+                mkdir -p ~/.gradle
+                echo 'org.gradle.jvmargs=-Xmx4g -XX:MaxMetaspaceSize=512m' >> ~/.gradle/gradle.properties
+
+            - name: Build APK
+              run: ./gradlew assembleRelease
+prevention:
+  - 'Test builds on ubuntu-24.04 explicitly — do not assume ubuntu-22.04 memory behavior transfers'
+  - 'Add a swap file as a build step when migrating large builds to ubuntu-24.04'
+  - 'Set NODE_OPTIONS=--max-old-space-size as a job-level env var for Node.js heavy workflows'
+  - 'Monitor build memory usage locally: /usr/bin/time -v npm run build shows peak RSS'
+  - 'Exit code 137 with no explicit error is the canonical indicator of OOM kill — add this as a diagnostic check'
+docs:
+  - 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-hosted runner hardware specs — RAM and storage per runner type'
+  - url: 'https://github.com/actions/runner-images/issues'
+    label: 'runner-images issues — search "OOM" or "exit 137" for community reports'
+  - url: 'https://nodejs.org/api/cli.html#--max-old-space-sizesize-in-megabytes'
+    label: 'Node.js CLI docs — --max-old-space-size option'

package/errors/runner-environment/ubuntu-24-openjdk11-no-installation-candidate.yml

@@ -0,0 +1,99 @@
+id: runner-environment-134
+title: 'ubuntu-24.04: openjdk-11-jdk has no installation candidate — Java 11 removed from Ubuntu 24 repos'
+category: runner-environment
+severity: error
+tags:
+  - java
+  - openjdk
+  - ubuntu-24
+  - apt
+  - java-11
+  - noble
+patterns:
+  - regex: 'Package .openjdk-11.*has no installation candidate'
+    flags: 'i'
+  - regex: 'openjdk-11-jdk.*no installation candidate'
+    flags: 'i'
+  - regex: 'E: Package .openjdk-11'
+    flags: 'i'
+error_messages:
+  - 'E: Package ''openjdk-11-jdk'' has no installation candidate'
+  - 'E: Package ''openjdk-11-jre'' has no installation candidate'
+  - 'E: Unable to locate package openjdk-11-jdk'
+root_cause: |
+  Ubuntu 24.04 LTS (Noble Numbat) dropped OpenJDK 11 from its official package repositories.
+  The minimum available Java version via apt on Ubuntu 24.04 is OpenJDK 17 (openjdk-17-jdk)
+  along with OpenJDK 21 (openjdk-21-jdk). OpenJDK 11 packages that existed in Ubuntu 22.04
+  (Jammy) are not present in Ubuntu 24.04 (Noble) main or universe repos.
+
+  Workflows that install Java via apt-get will fail:
+    sudo apt-get install -y openjdk-11-jdk  # Fails on ubuntu-24.04
+    sudo apt-get install -y openjdk-11-jre  # Fails on ubuntu-24.04
+
+  This affects workflows that:
+  - Directly install OpenJDK via apt without using actions/setup-java
+  - Use Docker images based on ubuntu:24.04 inside workflow steps
+  - Run scripts that call apt-get install openjdk-11* expecting Ubuntu 22 behavior
+
+  Note: Java 11 is still supported under long-term support plans but must be obtained from
+  third-party sources (Adoptium/Temurin, Amazon Corretto, Azul Zulu) rather than Ubuntu repos.
+fix: |
+  Use actions/setup-java to install any Java version including 11. The action downloads from
+  a distribution vendor (Temurin, Corretto, Zulu, etc.) rather than Ubuntu packages, making
+  it distribution-independent and supporting Java 11 on ubuntu-24.04.
+
+  Never use apt-get to install Java on GitHub-hosted runners — always use actions/setup-java
+  which handles version discovery, caching, JAVA_HOME configuration, and multi-platform support.
+fix_code:
+  - language: yaml
+    label: 'Use actions/setup-java to install Java 11 (works on ubuntu-24.04)'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-24.04
+          steps:
+            - uses: actions/checkout@v4
+
+            - uses: actions/setup-java@v4
+              with:
+                java-version: '11'
+                distribution: 'temurin'
+                cache: 'maven'
+
+            - name: Build with Maven
+              run: mvn -B package --file pom.xml
+
+  - language: yaml
+    label: 'Multi-version Java matrix — test across Java 11, 17, 21'
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-24.04
+          strategy:
+            matrix:
+              java-version: ['11', '17', '21']
+          steps:
+            - uses: actions/checkout@v4
+
+            - uses: actions/setup-java@v4
+              with:
+                java-version: ${{ matrix.java-version }}
+                distribution: 'temurin'
+
+            - name: Run tests
+              run: mvn test
+prevention:
+  - 'Always use actions/setup-java to install Java on GitHub-hosted runners — never rely on apt-get for Java'
+  - 'Pin the Java distribution explicitly (temurin, corretto, zulu) to avoid resolution differences across Ubuntu versions'
+  - 'Test workflows on ubuntu-24.04 explicitly when migrating from ubuntu-22.04 or ubuntu-20.04'
+  - 'Check Ubuntu package availability with https://packages.ubuntu.com before relying on apt for any tool installation'
+  - 'Validate Java availability in your workflow with: java -version && javac -version as an early smoke check'
+docs:
+  - url: 'https://github.com/actions/setup-java'
+    label: 'actions/setup-java — install Java on any GitHub-hosted runner'
+  - url: 'https://packages.ubuntu.com/noble/'
+    label: 'Ubuntu 24.04 (Noble) package search — verify available package versions'
+  - url: 'https://adoptium.net/temurin/releases/?version=11'
+    label: 'Eclipse Temurin — Java 11 LTS builds for all platforms'
+  - url: 'https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2404-Readme.md'
+    label: 'ubuntu-24.04 runner software report — pre-installed Java versions'

package/errors/runner-environment/windows-2025-dotnet6-sdk-removed.yml

@@ -0,0 +1,96 @@
+id: runner-environment-132
+title: 'windows-2025 runner: .NET 6 SDK removed — NETSDK1045 when targeting net6.0'
+category: runner-environment
+severity: error
+tags:
+  - dotnet
+  - windows-2025
+  - net6
+  - sdk
+  - netsdk1045
+  - eol
+patterns:
+  - regex: 'NETSDK1045.*\.NET 6\.0'
+    flags: 'i'
+  - regex: 'does not support targeting.*\.NET 6'
+    flags: 'i'
+  - regex: 'error NETSDK1045'
+    flags: 'i'
+error_messages:
+  - 'error NETSDK1045: The current .NET SDK does not support targeting .NET 6.0.'
+  - 'error NETSDK1045: The current .NET SDK does not support targeting .NET 6.0. Either target .NET 8.0 or higher, or use a .NET SDK that supports .NET 6.0.'
+root_cause: |
+  .NET 6 reached end-of-life on November 12, 2024. The windows-2025 runner image does not
+  include the .NET 6 SDK or runtime. Pre-installed .NET SDKs on windows-2025 are .NET 8
+  and .NET 9 only.
+
+  Workflows using dotnet build, dotnet test, or dotnet publish that target net6.0 TFM fail
+  with NETSDK1045 because no installed SDK can build or run .NET 6 targets. This affects:
+  - Projects with <TargetFramework>net6.0</TargetFramework> in their .csproj
+  - Multi-target projects including net6.0 in <TargetFrameworks>
+  - Workflows that run dotnet run with a net6.0 project
+
+  The windows-2022 runner still includes .NET 6 for legacy compatibility, so workflows using
+  runs-on: windows-2022 are unaffected. The breakage appears when migrating to windows-2025
+  or when windows-latest switches to windows-2025.
+fix: |
+  Option A (recommended): Upgrade the project's TargetFramework to net8.0 or net9.0. .NET 8
+  is the current LTS release and is pre-installed on windows-2025.
+
+  Option B (legacy support): Use actions/setup-dotnet to explicitly install the .NET 6 SDK.
+  Note: .NET 6 is EOL and receives no security patches — this option is not recommended for
+  production workloads.
+
+  Option C (short-term): Pin to windows-2022 runner temporarily while upgrading.
+fix_code:
+  - language: yaml
+    label: 'Option A — upgrade target framework to .NET 8 LTS (recommended)'
+    code: |
+      # In your .csproj, update:
+      # <TargetFramework>net8.0</TargetFramework>
+      # Then in your workflow:
+      jobs:
+        build:
+          runs-on: windows-2025
+          steps:
+            - uses: actions/checkout@v4
+
+            - uses: actions/setup-dotnet@v4
+              with:
+                dotnet-version: '8.0.x'
+
+            - name: Build
+              run: dotnet build --configuration Release
+
+  - language: yaml
+    label: 'Option B — explicitly install .NET 6 SDK (EOL, not recommended for production)'
+    code: |
+      jobs:
+        build:
+          runs-on: windows-2025
+          steps:
+            - uses: actions/checkout@v4
+
+            - uses: actions/setup-dotnet@v4
+              with:
+                dotnet-version: |
+                  6.0.x
+                  8.0.x
+
+            - name: Build
+              run: dotnet build --framework net6.0
+prevention:
+  - 'Audit all TargetFramework and TargetFrameworks values before migrating to windows-2025'
+  - 'Monitor the .NET release lifecycle at https://dotnet.microsoft.com/platform/support/policy for upcoming EOL dates'
+  - 'Use Dependabot or Renovate to track .NET SDK versions referenced in global.json or setup-dotnet steps'
+  - 'Check the windows-2025 runner software report (runner-images/Windows2025-Readme.md) before migration to see pre-installed SDKs'
+  - 'Set up a CI matrix that tests both windows-2022 and windows-2025 during migration periods'
+docs:
+  - url: 'https://github.com/actions/runner-images/blob/main/images/windows/Windows2025-Readme.md'
+    label: 'windows-2025 runner software report — pre-installed SDK versions'
+  - url: 'https://dotnet.microsoft.com/platform/support/policy/dotnet-core'
+    label: '.NET release lifecycle and EOL schedule'
+  - url: 'https://github.com/actions/setup-dotnet'
+    label: 'actions/setup-dotnet — install specific .NET SDK versions'
+  - url: 'https://github.com/actions/runner-images/discussions'
+    label: 'GitHub runner-images discussions — windows-2025 migration issues'

package/errors/silent-failures/github-ref-name-pr-merge-ref-not-branch.yml

@@ -0,0 +1,102 @@
+id: silent-failures-070
+title: 'github.ref_name returns N/merge on pull_request events, not the head branch name'
+category: silent-failures
+severity: silent-failure
+tags:
+  - github-ref-name
+  - github-head-ref
+  - pull-request
+  - merge-ref
+  - branch-name
+  - context
+patterns:
+  - regex: 'github\.ref_name'
+    flags: 'i'
+  - regex: '\d+/merge'
+    flags: ''
+error_messages:
+  - "branch name is '15/merge' instead of 'feature/my-branch'"
+  - "invalid branch: 45/merge"
+  - "ref_name evaluates to 23/merge on pull_request trigger"
+root_cause: |
+  On pull_request events, GitHub creates a synthetic merge commit ref at refs/pull/N/merge
+  representing the result of merging the head branch into the base branch. This is the ref
+  that the runner checks out by default.
+
+  github.ref resolves to 'refs/pull/N/merge' and github.ref_name resolves to 'N/merge'
+  (e.g., '15/merge') — not the human-readable head branch name.
+
+  Developers who use github.ref_name expecting the PR head branch name receive the synthetic
+  merge ref slug instead, which breaks:
+  - Branch-based deployment logic
+  - Conditional workflow steps that check the branch name
+  - Tag/release workflows incorrectly applied to PR builds
+  - Docker image tags derived from the branch name
+
+  To get the actual PR head branch name on pull_request events, use github.head_ref.
+  To get the base branch name, use github.base_ref.
+
+  Note: On push events, github.ref_name correctly returns the branch name (e.g., 'main').
+  The discrepancy only affects pull_request (and pull_request_target) events.
+fix: |
+  Use github.head_ref instead of github.ref_name when you need the PR head branch name.
+
+  For robust multi-event workflows, use a conditional expression:
+  - On pull_request: github.head_ref contains the branch name
+  - On push: github.ref_name contains the branch name
+
+  Or use a ternary-style expression to normalize:
+  ${{ github.event_name == 'pull_request' && github.head_ref || github.ref_name }}
+fix_code:
+  - language: yaml
+    label: 'Use github.head_ref for PR branch name, github.ref_name for push'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Get branch name
+              run: |
+                if [ "${{ github.event_name }}" = "pull_request" ]; then
+                  BRANCH="${{ github.head_ref }}"
+                else
+                  BRANCH="${{ github.ref_name }}"
+                fi
+                echo "Branch: $BRANCH"
+                echo "BRANCH=$BRANCH" >> $GITHUB_ENV
+
+  - language: yaml
+    label: 'Normalize branch name in Docker image tag (works for push and PR)'
+    code: |
+      on:
+        push:
+          branches: [main, develop]
+        pull_request:
+
+      jobs:
+        docker:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Set branch slug
+              id: branch
+              run: |
+                # Use head_ref for PRs, ref_name for push events
+                BRANCH="${{ github.event_name == 'pull_request' && github.head_ref || github.ref_name }}"
+                # Slugify: replace / with - for Docker tag compatibility
+                SLUG=$(echo "$BRANCH" | tr '/' '-' | tr '[:upper:]' '[:lower:]')
+                echo "slug=$SLUG" >> $GITHUB_OUTPUT
+
+            - name: Build Docker image
+              run: docker build -t myapp:${{ steps.branch.outputs.slug }} .
+prevention:
+  - 'On pull_request events, always use github.head_ref for the PR head branch and github.base_ref for the target base branch'
+  - 'github.ref_name is only reliable as a branch name on push events — never use it unconditionally'
+  - 'When writing multi-event workflows (push + pull_request), add an event-conditional expression to normalize the branch name'
+  - 'Test workflows triggered by both push and pull_request events to catch context differences early'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#github-context'
+    label: 'GitHub context — github.ref_name, github.head_ref, github.base_ref'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#pull_request'
+    label: 'pull_request event context and merge ref behavior'
+  - url: 'https://github.com/orgs/community/discussions/25722'
+    label: 'GitHub Community: github.ref_name returns N/merge on pull_request'

package/errors/silent-failures/reusable-workflow-caller-env-not-forwarded.yml

@@ -0,0 +1,93 @@
+id: silent-failures-069
+title: 'workflow_call: caller env vars not forwarded to reusable workflow — silently unavailable'
+category: silent-failures
+severity: silent-failure
+tags:
+  - reusable-workflow
+  - workflow_call
+  - env-context
+  - caller-env
+  - inputs
+  - environment-variables
+patterns:
+  - regex: 'env\.\w+ is not defined'
+    flags: 'i'
+  - regex: '\$\{\{\s*env\.\w+\s*\}\}\s*$'
+    flags: 'im'
+error_messages:
+  - "env.API_URL is not defined"
+  - "The template is not valid. .github/workflows/deploy.yml: env.BASE_URL is not defined"
+root_cause: |
+  GitHub Actions reusable workflows (on.workflow_call) run in a completely isolated environment.
+  The caller workflow's env: context — whether defined at the top-level workflow scope or at the
+  calling job scope — is NOT automatically forwarded to the called reusable workflow.
+
+  Only two mechanisms exist for passing data into a reusable workflow:
+  - inputs: (on.workflow_call.inputs) for plain values
+  - secrets: (on.workflow_call.secrets) for sensitive values
+
+  A common mistake is defining env: vars at the caller workflow level and assuming they will be
+  visible inside the reusable workflow. They are not. The called workflow has its own empty env:
+  context (unless vars.* or env: is set within the reusable workflow itself).
+
+  Example that breaks silently:
+  - Caller sets: env: { API_URL: 'https://api.example.com' }
+  - Caller calls: uses: ./.github/workflows/deploy.yml
+  - Inside deploy.yml: run: curl ${{ env.API_URL }}  # evaluates to empty string, no error
+fix: |
+  Pass values explicitly via the inputs: mechanism on the reusable workflow call.
+  Define the input on on.workflow_call.inputs and reference it as inputs.<name> inside the
+  called workflow.
+
+  If many env vars need forwarding, consider using a JSON-encoded input and fromJSON() inside
+  the called workflow, or use repository variables (vars.*) which are available in all workflows.
+fix_code:
+  - language: yaml
+    label: 'Pass caller env var as explicit input to reusable workflow'
+    code: |
+      # Caller workflow
+      jobs:
+        deploy:
+          uses: ./.github/workflows/deploy.yml
+          with:
+            api_url: ${{ vars.API_URL }}   # or hardcoded value
+          secrets: inherit
+
+      # Reusable workflow: .github/workflows/deploy.yml
+      on:
+        workflow_call:
+          inputs:
+            api_url:
+              required: true
+              type: string
+
+      jobs:
+        run:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Deploy
+              run: curl ${{ inputs.api_url }}
+
+  - language: yaml
+    label: 'Use repository variables (vars.*) accessible in all workflows'
+    code: |
+      # Set API_URL as a repository variable in Settings → Secrets and variables → Actions → Variables
+      # Then reference it in the reusable workflow directly:
+      jobs:
+        run:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Deploy
+              run: curl ${{ vars.API_URL }}
+prevention:
+  - 'Never rely on env: vars defined in a caller workflow being available inside a reusable workflow — they are not forwarded'
+  - 'Declare all cross-workflow values as on.workflow_call.inputs or on.workflow_call.secrets'
+  - 'Use repository/org-level variables (vars.*) for configuration that many workflows need without explicit passing'
+  - 'Run actionlint on caller and callee separately — it will flag undefined env references in reusable workflows'
+docs:
+  - url: 'https://docs.github.com/en/actions/sharing-automations/reusing-workflows#passing-inputs-and-secrets-to-a-reusable-workflow'
+    label: 'Passing inputs and secrets to a reusable workflow'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables#using-the-vars-context-to-access-configuration-variable-values'
+    label: 'Using repository variables with the vars context'
+  - url: 'https://github.com/orgs/community/discussions/26671'
+    label: 'GitHub Community: env vars not accessible in reusable workflows'

package/errors/triggers/issue-comment-pr-review-thread-not-triggered.yml

@@ -0,0 +1,105 @@
+id: triggers-050
+title: 'on.issue_comment does not fire for PR review thread comments — requires pull_request_review_comment'
+category: triggers
+severity: silent-failure
+tags:
+  - issue_comment
+  - pull_request_review_comment
+  - pr-review
+  - comment-event
+  - trigger
+  - chatops
+patterns:
+  - regex: 'on:\s*\n\s+issue_comment'
+    flags: 'im'
+  - regex: 'github\.event_name\s*==\s*[''"]issue_comment[''"]'
+    flags: 'i'
+error_messages:
+  - "workflow never triggered when commenting on a PR review thread"
+  - "issue_comment workflow fires on issue comments but not PR inline review comments"
+root_cause: |
+  GitHub Actions has two distinct comment event types that developers frequently confuse:
+
+  1. issue_comment — fires when a comment is posted on:
+     - The main conversation thread of an issue
+     - The main conversation thread of a pull request (PR-as-issue comments)
+     It does NOT fire for inline PR code review comments or review summary comments.
+
+  2. pull_request_review_comment — fires when a comment is posted on:
+     - A specific line of code in a PR diff (inline review comment)
+     It does NOT fire for comments on the main PR conversation thread.
+
+  3. pull_request_review — fires when:
+     - A complete PR review is submitted (including review body, approval, or request-changes)
+
+  Chatops bots and automation that listen to issue_comment expecting to catch all PR comment
+  activity will silently miss all PR code review thread comments. There is no error — the
+  workflow simply never fires for that comment type.
+
+  Similarly, on.pull_request_review_comment will miss all main thread comments on the same PR.
+fix: |
+  Choose the correct trigger based on what type of comment you want to react to:
+
+  - For commands in PR main conversation (/deploy, /approve, etc.): use issue_comment
+  - For reactions to inline code review comments: use pull_request_review_comment
+  - For reactions to full review submissions (approve, request changes): use pull_request_review
+  - For all PR comment activity: use both issue_comment AND pull_request_review_comment
+
+  Note: on.issue_comment has access to github.event.issue.number for the PR number,
+  while on.pull_request_review_comment has access to github.event.pull_request.number.
+fix_code:
+  - language: yaml
+    label: 'Listen to all PR comment types (main thread + review thread)'
+    code: |
+      on:
+        issue_comment:
+          types: [created]
+        pull_request_review_comment:
+          types: [created]
+        pull_request_review:
+          types: [submitted]
+
+      jobs:
+        handle-comment:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Handle comment
+              run: |
+                if [ "${{ github.event_name }}" = "issue_comment" ]; then
+                  echo "Main thread comment: ${{ github.event.comment.body }}"
+                  echo "PR number: ${{ github.event.issue.number }}"
+                elif [ "${{ github.event_name }}" = "pull_request_review_comment" ]; then
+                  echo "Review thread comment: ${{ github.event.comment.body }}"
+                  echo "PR number: ${{ github.event.pull_request.number }}"
+                fi
+
+  - language: yaml
+    label: 'Chatops bot — listen for slash commands on main PR thread only'
+    code: |
+      on:
+        issue_comment:
+          types: [created]
+
+      jobs:
+        chatops:
+          # Only run for PR comments (issue_comment also fires on plain issues)
+          if: github.event.issue.pull_request != null
+          runs-on: ubuntu-latest
+          steps:
+            - name: Check for slash command
+              run: |
+                echo "Comment body: ${{ github.event.comment.body }}"
+prevention:
+  - 'Distinguish issue_comment (main PR thread) from pull_request_review_comment (inline code review thread) — they never overlap'
+  - 'If building a PR chatops bot, filter to PR-only comments by checking github.event.issue.pull_request != null'
+  - 'Use pull_request_review for reactions to full review submissions (approve/reject), not pull_request_review_comment'
+  - 'Test your trigger by posting comments in BOTH places (main conversation and code review thread) to verify expected behavior'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#issue_comment'
+    label: 'GitHub Docs — issue_comment event'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#pull_request_review_comment'
+    label: 'GitHub Docs — pull_request_review_comment event'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#pull_request_review'
+    label: 'GitHub Docs — pull_request_review event'
+  - url: 'https://github.com/orgs/community/discussions/21929'
+    label: 'GitHub Community: issue_comment vs pull_request_review_comment confusion'

package/errors/yaml-syntax/branches-and-branches-ignore-combined-same-event.yml

@@ -0,0 +1,99 @@
+id: yaml-syntax-047
+title: '"You can''t use both ''branches'' and ''branches-ignore''" — combined on same event trigger'
+category: yaml-syntax
+severity: error
+tags:
+  - branches
+  - branches-ignore
+  - trigger-filter
+  - validation-error
+  - actionlint
+  - on-push
+patterns:
+  - regex: 'You can''t use both ''branches'' and ''branches-ignore'''
+    flags: 'i'
+  - regex: "You can't use both 'branches' and 'branches-ignore'"
+    flags: 'i'
+  - regex: 'branches.*branches-ignore|branches-ignore.*branches'
+    flags: 'is'
+error_messages:
+  - "You can't use both 'branches' and 'branches-ignore' for the same event."
+  - "Invalid workflow file: .github/workflows/ci.yml: You can't use both 'branches' and 'branches-ignore' for the same event."
+root_cause: |
+  GitHub Actions validates that branches and branches-ignore are mutually exclusive filters
+  on the same trigger event. Using both simultaneously causes a workflow parse error because
+  the semantics are contradictory — branches is an allowlist while branches-ignore is a
+  denylist, and combining them on the same trigger is undefined behavior.
+
+  This restriction applies to all events that support branch filtering, including:
+  - on.push
+  - on.pull_request
+  - on.pull_request_target
+
+  The same restriction applies to paths vs paths-ignore and tags vs tags-ignore.
+
+  Common mistake patterns:
+  - Developer adds branches-ignore: [main] to prevent duplicate runs, forgetting branches is set
+  - Developer copies a snippet with branches and adds branches-ignore without removing the original
+  - Workflow generated from a template that includes both filters from different sections
+
+  Note: branches and paths can coexist on the same trigger (both act as allowlists that AND together).
+  It is only branches + branches-ignore (or paths + paths-ignore) that conflict.
+fix: |
+  Choose one approach and remove the other:
+
+  Option A — Use branches (allowlist): explicitly list which branches should trigger the workflow.
+  Option B — Use branches-ignore (denylist): list which branches should NOT trigger the workflow.
+
+  To achieve "run on all branches except main and release/*", use branches-ignore.
+  To achieve "only run on main and feature/*", use branches.
+
+  For complex patterns (e.g., "feature/* except feature/skip"), use branches with negation
+  via the ! prefix:
+    branches:
+      - 'feature/**'
+      - '!feature/skip-*'
+fix_code:
+  - language: yaml
+    label: 'Broken — branches and branches-ignore on same event (causes validation error)'
+    code: |
+      # BROKEN — do not use both on the same event
+      on:
+        push:
+          branches:
+            - main
+            - 'feature/**'
+          branches-ignore:      # ERROR: cannot combine with branches
+            - 'feature/wip-*'
+
+  - language: yaml
+    label: 'Fixed — use branches with ! negation patterns'
+    code: |
+      on:
+        push:
+          branches:
+            - main
+            - 'feature/**'
+            - '!feature/wip-*'   # negate specific sub-pattern
+
+  - language: yaml
+    label: 'Fixed — use branches-ignore (denylist) alone'
+    code: |
+      on:
+        push:
+          branches-ignore:
+            - 'feature/wip-*'
+            - 'dependabot/**'
+prevention:
+  - 'Never combine branches and branches-ignore on the same trigger event — pick one approach'
+  - 'Use branches (allowlist) when only a few branches should trigger; use branches-ignore (denylist) when most branches should trigger'
+  - 'To exclude specific patterns from an allowlist, use ! negation prefix inside the branches list'
+  - 'Run actionlint in CI to catch this validation error before pushing (actionlint reports it immediately)'
+  - 'The same mutual-exclusion rule applies to paths/paths-ignore and tags/tags-ignore'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/triggering-a-workflow#using-filters'
+    label: 'Using filters — branches, branches-ignore, and negation patterns'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#onpushbranchestagsbranches-ignoretags-ignore'
+    label: 'Workflow syntax — on.push branches and branches-ignore'
+  - url: 'https://rhysd.github.io/actionlint/'
+    label: 'actionlint — static checker that catches this error instantly'

package/package.json

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