@htekdev/actions-debugger 1.0.101 → 1.0.103

package/errors/caching-artifacts/cache-key-missing-runner-arch-x64-arm64-bleed.yml

@@ -0,0 +1,101 @@
+id: caching-artifacts-058
+title: 'actions/cache key using runner.os bleeds between x64 and ARM64 Linux runners — wrong architecture binaries restored'
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - cache-key
+  - runner-arch
+  - arm64
+  - x64
+  - architecture
+  - cross-arch
+patterns:
+  - regex: 'exec format error'
+    flags: 'i'
+  - regex: 'cannot execute binary file.*Exec format error'
+    flags: 'i'
+  - regex: 'ELF.*wrong ELF class'
+    flags: 'i'
+error_messages:
+  - "bash: /path/to/binary: cannot execute binary file: Exec format error"
+  - "error while loading shared libraries: wrong ELF class: ELFCLASS32"
+  - "qemu: uncaught target signal 11 (Segmentation fault)"
+root_cause: |
+  runner.os returns "Linux" for both ubuntu-24.04 (x86_64) and ubuntu-24.04-arm
+  (arm64/aarch64) runners. A cache key built with only ${{ runner.os }} will match
+  caches created on EITHER architecture, silently restoring the wrong binaries.
+
+  Example: a workflow compiles a Rust binary or installs native npm packages
+  (esbuild, rollup, sharp) on an x86_64 runner, then the same cache key is used on
+  an ARM64 runner. The cached x86_64 ELF binary is restored and immediately fails
+  with "Exec format error" — or worse, a segfault with no obvious cause.
+
+  This affects:
+  - Compiled binaries cached in the build layer
+  - Native npm modules (esbuild, @swc/core, sharp, canvas)
+  - Python packages with C extensions (.so files)
+  - Go, Rust, C++ build artifacts
+  - Any runner.os-keyed cache shared across an architecture matrix
+
+  The silent aspect: the cache HITS (green cache-hit output), no error is reported
+  until the cached binary is actually executed, often many steps later.
+fix: |
+  Add runner.arch to any cache key that stores architecture-dependent content.
+  runner.arch returns "X64" or "ARM64" on Linux runners, disambiguating them.
+
+  Change:
+    key: ${{ runner.os }}-build-${{ hashFiles('**/Cargo.lock') }}
+
+  To:
+    key: ${{ runner.os }}-${{ runner.arch }}-build-${{ hashFiles('**/Cargo.lock') }}
+
+  This applies to all cache keys for compiled artifacts, native modules, or
+  any platform-specific binary output. Pure source-code or platform-agnostic
+  caches (e.g., Go module downloads, pip source distributions) do not need runner.arch.
+fix_code:
+  - language: yaml
+    label: 'WRONG — runner.os only, bleeds between x64 and ARM64'
+    code: |
+      - uses: actions/cache@v4
+        with:
+          path: target/release
+          # BAD: runner.os = "Linux" for both x64 and ARM64
+          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
+  - language: yaml
+    label: 'FIX — include runner.arch in cache key'
+    code: |
+      - uses: actions/cache@v4
+        with:
+          path: target/release
+          # GOOD: runner.arch = "X64" or "ARM64", prevents cross-arch cache hits
+          key: ${{ runner.os }}-${{ runner.arch }}-cargo-${{ hashFiles('**/Cargo.lock') }}
+  - language: yaml
+    label: 'Full matrix example with architecture-aware cache keys'
+    code: |
+      jobs:
+        build:
+          strategy:
+            matrix:
+              runner: [ubuntu-24.04, ubuntu-24.04-arm]
+          runs-on: ${{ matrix.runner }}
+          steps:
+            - uses: actions/checkout@v4
+            - uses: actions/cache@v4
+              with:
+                path: |
+                  ~/.cargo/registry
+                  target/
+                key: ${{ runner.os }}-${{ runner.arch }}-cargo-${{ hashFiles('**/Cargo.lock') }}
+            - run: cargo build --release
+prevention:
+  - 'Always include runner.arch in cache keys when the cached content contains compiled or architecture-specific binaries'
+  - 'Audit existing cache keys whenever adding ARM64 runners to a workflow that already runs on x86_64'
+  - 'Use a restore-key that does NOT include arch only as a fallback, not as a primary key'
+  - 'Test fresh (clear cache) runs on each architecture to verify binaries execute correctly'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/contexts#runner-context'
+    label: 'GitHub Actions runner context — runner.os and runner.arch'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows'
+    label: 'Caching dependencies to speed up workflows'
+  - url: 'https://github.com/actions/cache'
+    label: 'actions/cache — cache key examples and best practices'

package/errors/known-unsolved/matrix-job-limit-256-silent-truncation.yml

@@ -0,0 +1,116 @@
+id: known-unsolved-056
+title: 'GitHub Actions matrix is silently capped at 256 jobs — excess jobs are dropped with no warning'
+category: known-unsolved
+severity: limitation
+tags:
+  - matrix
+  - job-limit
+  - 256
+  - large-matrix
+  - silent-truncation
+patterns:
+  - regex: 'matrix.*256|256.*matrix.*job'
+    flags: 'i'
+  - regex: 'some jobs.*not.*generated.*matrix'
+    flags: 'i'
+error_messages:
+  - "The matrix contains more jobs than the 256 job limit"
+root_cause: |
+  GitHub Actions enforces a hard limit of 256 jobs per matrix expansion. When a
+  matrix generates more than 256 combinations, GitHub silently drops all jobs beyond
+  the first 256 — no error is raised, no warning appears in the workflow run UI,
+  and no notification is sent to the repository owner.
+
+  The truncation is silent and deterministic: GitHub processes matrix entries in
+  the order they are defined and stops at 256. If your matrix has 300 combinations,
+  jobs 257–300 simply do not run, but the workflow completes successfully.
+
+  Common scenarios that hit this limit:
+  - Large monorepo test suites that fan out one job per package/service (50+ packages
+    × multiple OS/version combinations)
+  - Parameterized test sharding where both shard-count and OS are in the matrix
+  - Dynamic matrices built from directory listings or API calls
+  - Security scanning jobs that matrix over many dependency versions
+
+  GitHub Actions documentation mentions the 256 limit but does not surface it as
+  an error at runtime, making it easy to miss for months.
+
+  Note: Enterprise plans have the same 256-job limit per matrix. There is no paid
+  tier that raises this cap.
+fix: |
+  There is no way to raise the 256-job limit. Workarounds:
+
+  1. Restructure the matrix to combine dimensions:
+     Instead of os × version × shard (3×4×30=360), use a pre-computed list of
+     only the combinations you actually need (often far fewer than the full product).
+
+  2. Shard within a single job instead of across jobs:
+     Use a single "test" job that runs a subset of tests in each runner process,
+     controlled by TOTAL_SHARDS / SHARD_INDEX environment variables, without
+     a separate matrix job per shard.
+
+  3. Split into multiple workflows:
+     Use workflow_call to invoke sub-workflows, each handling a subset of jobs.
+     Each workflow has its own 256-job budget.
+
+  4. Use a dynamic include-only matrix:
+     Build the matrix list externally (e.g., a script) and output it as JSON,
+     then ensure the JSON has at most 256 entries. Add a CI check that fails if
+     the list exceeds 255 (leaving headroom for include additions).
+fix_code:
+  - language: yaml
+    label: 'Pre-compute matrix list to stay under 256 (dynamic matrix pattern)'
+    code: |
+      jobs:
+        setup:
+          runs-on: ubuntu-latest
+          outputs:
+            matrix: ${{ steps.build-matrix.outputs.matrix }}
+          steps:
+            - uses: actions/checkout@v4
+            - id: build-matrix
+              run: |
+                # Build matrix, enforce limit
+                MATRIX=$(find packages -name package.json -maxdepth 2 | \
+                  head -256 | jq -R -s -c 'split("\n") | map(select(. != ""))')
+                echo "matrix={\"pkg\":$MATRIX}" >> "$GITHUB_OUTPUT"
+
+        test:
+          needs: setup
+          strategy:
+            matrix: ${{ fromJSON(needs.setup.outputs.matrix) }}
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Testing ${{ matrix.pkg }}"
+  - language: yaml
+    label: 'Split large matrix across two workflows via workflow_call'
+    code: |
+      # .github/workflows/test-batch-a.yml
+      on:
+        workflow_call:
+      jobs:
+        test:
+          strategy:
+            matrix:
+              pkg: [svc-a, svc-b, svc-c]  # First 128 services
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Testing ${{ matrix.pkg }}"
+
+      # .github/workflows/ci.yml
+      on: [push]
+      jobs:
+        batch-a:
+          uses: ./.github/workflows/test-batch-a.yml
+        batch-b:
+          uses: ./.github/workflows/test-batch-b.yml
+prevention:
+  - 'Monitor your matrix job count as the codebase grows — add a pre-flight check that fails CI if the computed matrix exceeds 255'
+  - 'Prefer horizontal test sharding within a single job over per-package matrix expansion for large monorepos'
+  - 'Document the matrix budget in your CONTRIBUTING.md so contributors understand the constraint'
+  - 'Use include: sparingly — each include entry adds to the 256-job budget'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/running-variations-of-jobs-in-a-workflow#about-matrix-strategies'
+    label: 'GitHub Actions — About matrix strategies (256-job limit documented)'
+  - url: 'https://docs.github.com/en/actions/administering-github-actions/usage-limits-billing-and-administration#usage-limits'
+    label: 'GitHub Actions usage limits — job matrix limits'

package/errors/runner-environment/homebrew-auto-update-macos-ci-slow.yml

@@ -0,0 +1,84 @@
+id: runner-environment-172
+title: 'Homebrew 4.x triggers auto-update on every brew install, adding 1-3 minutes to macOS CI'
+category: runner-environment
+severity: warning
+tags:
+  - macos
+  - homebrew
+  - brew
+  - slow-ci
+  - performance
+  - HOMEBREW_NO_AUTO_UPDATE
+patterns:
+  - regex: '==> Auto-updated Homebrew!|Updating Homebrew\.\.\.|Auto-update took'
+    flags: 'i'
+  - regex: 'Fetching https://formulae\.brew\.sh/api/(formula|cask)\.jws\.json'
+    flags: 'i'
+error_messages:
+  - "==> Auto-updated Homebrew!"
+  - "Updating Homebrew..."
+  - "Fetching https://formulae.brew.sh/api/formula.jws.json"
+  - "This operation has taken more than 5 minutes"
+root_cause: |
+  Homebrew 4.0 (released February 2023) replaced its previous approach of cloning the
+  homebrew-core and homebrew-cask Git repositories with downloading pre-computed JSON API
+  responses from formulae.brew.sh. While this reduced the on-disk size of the Homebrew
+  installation, Homebrew retained its auto-update behavior: by default, any brew install,
+  brew upgrade, or brew reinstall command triggers an auto-update check if the local
+  formula cache is older than HOMEBREW_AUTO_UPDATE_SECS (default: 300 seconds = 5 minutes).
+
+  On GitHub-hosted macOS runners, every fresh runner starts with a Homebrew installation
+  that has not been updated recently, so the first brew install in any job always triggers
+  a full API fetch from formulae.brew.sh. This fetch downloads large JSON manifests for
+  formula and cask databases and typically adds 1-3 minutes to the job. For workflows with
+  multiple parallel matrix jobs or multiple brew install calls, this overhead compounds.
+
+  Homebrew 4.x also added HOMEBREW_AUTO_UPDATE_SECS and related env vars to control this
+  behavior, but the default settings cause every fresh runner to update on first use.
+fix: |
+  Set HOMEBREW_NO_AUTO_UPDATE=1 as a workflow environment variable to disable automatic
+  updates entirely. The macOS runner image ships a recent-enough Homebrew installation for
+  most use cases. If you need the absolute latest formula versions for a specific tool,
+  run a single explicit brew update at the start of the job.
+
+  Also set HOMEBREW_NO_INSTALL_CLEANUP=1 to prevent cleanup passes that extend install time.
+fix_code:
+  - language: yaml
+    label: 'Disable Homebrew auto-update at workflow level (recommended)'
+    code: |
+      env:
+        HOMEBREW_NO_AUTO_UPDATE: '1'
+        HOMEBREW_NO_INSTALL_CLEANUP: '1'
+
+      jobs:
+        build:
+          runs-on: macos-latest
+          steps:
+            - name: Install build dependencies
+              run: brew install ninja cmake
+  - language: yaml
+    label: 'Run one explicit update then suppress auto-update per job'
+    code: |
+      jobs:
+        build:
+          runs-on: macos-latest
+          env:
+            HOMEBREW_NO_AUTO_UPDATE: '1'
+            HOMEBREW_NO_INSTALL_CLEANUP: '1'
+          steps:
+            - name: Update Homebrew (once, explicit)
+              run: brew update
+            - name: Install tools
+              run: brew install ninja cmake
+prevention:
+  - 'Set HOMEBREW_NO_AUTO_UPDATE=1 and HOMEBREW_NO_INSTALL_CLEANUP=1 as top-level workflow env vars'
+  - 'Use actions/setup-* official actions instead of brew install when available (setup-python, setup-node, etc.)'
+  - 'Cache brew downloads using actions/cache with a key derived from a Brewfile or explicit package list'
+  - 'Set HOMEBREW_AUTO_UPDATE_SECS=86400 to limit auto-updates to at most once per day if you need periodic updates'
+docs:
+  - url: 'https://docs.brew.sh/Manpage#environment'
+    label: 'Homebrew environment variables — HOMEBREW_NO_AUTO_UPDATE'
+  - url: 'https://brew.sh/2023/02/16/homebrew-4.0.0/'
+    label: 'Homebrew 4.0.0 release notes — JSON API migration'
+  - url: 'https://github.com/actions/runner-images/blob/main/images/macos/macos-15-Readme.md'
+    label: 'macOS 15 runner image — preinstalled Homebrew version'

package/errors/runner-environment/python312-ast-str-num-removed-ubuntu24.yml

@@ -0,0 +1,74 @@
+id: runner-environment-171
+title: 'Python 3.12 removes deprecated ast.Str, ast.Num, ast.NameConstant on ubuntu-24.04 — older linters crash'
+category: runner-environment
+severity: error
+tags:
+  - ubuntu-24.04
+  - python
+  - python-3.12
+  - ast
+  - linting
+  - pylint
+  - bandit
+patterns:
+  - regex: 'AttributeError: module ''ast'' has no attribute ''(Str|Num|NameConstant|Bytes)'''
+    flags: 'i'
+  - regex: 'ImportError.*pylint|cannot import name.*astroid|AttributeError.*ast\.(Str|Num)'
+    flags: 'i'
+error_messages:
+  - "AttributeError: module 'ast' has no attribute 'Str'"
+  - "AttributeError: module 'ast' has no attribute 'Num'"
+  - "AttributeError: module 'ast' has no attribute 'NameConstant'"
+  - "AttributeError: module 'ast' has no attribute 'Bytes'"
+root_cause: |
+  Ubuntu 24.04 ships Python 3.12 as the default system Python (/usr/bin/python3).
+  Python 3.12 permanently removed several deprecated AST node types that were soft-deprecated
+  since Python 3.8 and slated for removal in 3.12: ast.Str, ast.Num, ast.NameConstant,
+  ast.Bytes, and the legacy constant-value wrapper nodes.
+
+  Many popular static analysis tools directly referenced these internal AST nodes for
+  backward compatibility with Python 2 and early Python 3 code. Affected tools include:
+  - pylint < 3.0 (uses astroid which references ast.Str/ast.Num for constant folding)
+  - astroid < 3.0 (core dependency of pylint; crash on import with Python 3.12)
+  - bandit < 1.8.0 (security linter; uses ast.Str for string literal detection)
+  - flake8-bugbear < 23.x (some plugin versions reference ast.Num directly)
+  - pyflakes < 3.0 (uses ast.Str for format string analysis)
+
+  Workflows that install these linters without pinning minimum versions fail immediately
+  when the runner migrates from ubuntu-22.04 (Python 3.10) to ubuntu-24.04 (Python 3.12).
+  The error surfaces as an AttributeError during tool import, before any code is analyzed.
+fix: |
+  Upgrade the affected analysis tools to Python 3.12-compatible versions:
+  - pylint: upgrade to 3.0+ (requires astroid >= 3.0 simultaneously)
+  - bandit: upgrade to 1.8.0+
+  - flake8: upgrade to 7.0+ with compatible plugin versions
+
+  If an immediate upgrade is not feasible, pin the runner to ubuntu-22.04 (Python 3.10)
+  temporarily while the upgrade is planned. Ubuntu 22.04 runner support continues until
+  at least April 2027.
+fix_code:
+  - language: yaml
+    label: 'Upgrade linting tools to Python 3.12-compatible versions'
+    code: |
+      - name: Install Python linters (3.12 compatible)
+        run: pip install 'pylint>=3.0' 'astroid>=3.0' 'bandit>=1.8.0' 'flake8>=7.0'
+  - language: yaml
+    label: 'Temporary workaround — pin to ubuntu-22.04 (Python 3.10)'
+    code: |
+      jobs:
+        lint:
+          runs-on: ubuntu-22.04  # Python 3.10 — avoids ast.Str removal in 3.12
+prevention:
+  - 'Pin minimum versions for linting tools in requirements-dev.txt or pyproject.toml'
+  - 'Use actions/setup-python to control the Python version explicitly rather than relying on system Python'
+  - 'Test your CI toolchain against Python 3.12 before migrating to ubuntu-24.04'
+  - 'Review the Python 3.12 changelog for all removed deprecated features before upgrading'
+docs:
+  - url: 'https://docs.python.org/3.12/whatsnew/3.12.html#removed'
+    label: 'Python 3.12 Removed Features'
+  - url: 'https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2404-Readme.md'
+    label: 'Ubuntu 24.04 runner image software listing'
+  - url: 'https://pylint.readthedocs.io/en/stable/whatsnew/3.0/summary.html'
+    label: 'Pylint 3.0 migration and Python 3.12 compatibility notes'
+  - url: 'https://github.com/PyCQA/bandit/releases/tag/1.8.0'
+    label: 'bandit 1.8.0 release notes — Python 3.12 AST compatibility'

package/errors/runner-environment/setup-go-eol-version-not-in-tool-cache.yml

@@ -0,0 +1,78 @@
+id: runner-environment-173
+title: 'actions/setup-go with EOL Go versions (1.21, 1.22) not in runner tool cache — slow downloads or failures'
+category: runner-environment
+severity: warning
+tags:
+  - setup-go
+  - go
+  - golang
+  - eol
+  - tool-cache
+  - go-version
+patterns:
+  - regex: 'go version [\d.]+ is not in the tool-cache.*Falling back to download|go\d+\.\d+\.?\d*.*not found.*tool.cache'
+    flags: 'i'
+  - regex: 'Downloading go[\d.]+.*from https://dl\.google\.com/go'
+    flags: 'i'
+  - regex: 'Failed to download Go from|Unable to find Go version.*in cache'
+    flags: 'i'
+error_messages:
+  - "go version 1.21.x is not in the tool-cache. Falling back to downloading from https://dl.google.com/go"
+  - "go version 1.22.x is not in the tool-cache. Falling back to downloading from https://dl.google.com/go"
+  - "Failed to download Go from https://dl.google.com/go"
+  - "Unable to find Go version 1.21 in cache"
+root_cause: |
+  GitHub removes end-of-life Go versions from the runner image tool cache after their
+  official support window closes. Go follows a two-release support policy: only the two
+  most recent major releases receive security updates. Once a version is EOL, it is no
+  longer pre-installed on new runner images.
+
+  Affected versions as of 2025-2026:
+  - Go 1.21 — EOL February 6, 2024 (removed from runner tool cache ~Q2 2024)
+  - Go 1.22 — EOL August 6, 2025 (removed from runner tool cache ~Q4 2025)
+
+  When actions/setup-go requests a version not in the tool cache, it falls back to
+  downloading the Go toolchain from dl.google.com/go. This fallback:
+  1. Adds 30-90 seconds of download time per job (depending on network speed)
+  2. Fails entirely in self-hosted runners without internet access or strict outbound
+     firewall rules blocking dl.google.com
+  3. May fail intermittently if the Google CDN experiences transient issues
+
+  Workflows with many parallel matrix jobs (e.g., matrix of Go versions or OS targets)
+  multiply this overhead: 20 parallel jobs each downloading Go = 20 concurrent CDN requests.
+fix: |
+  Upgrade to a currently-supported Go version. As of 2025-2026, the two supported releases
+  are Go 1.23 and Go 1.24. Both are pre-cached in the runner tool cache and resolve
+  instantly without any network download.
+
+  Use the go-version-file input to read the version from go.mod, ensuring your CI always
+  matches your project's declared Go version.
+fix_code:
+  - language: yaml
+    label: 'Pin to a supported Go version (no tool-cache miss)'
+    code: |
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.24'   # or '1.23' — both are in the runner tool cache
+          cache: true
+  - language: yaml
+    label: 'Use go-version-file to read version from go.mod'
+    code: |
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: 'go.mod'  # reads `go 1.24` directive from go.mod
+          cache: true
+prevention:
+  - 'Keep go-version in your workflows aligned with the go directive in go.mod'
+  - 'Upgrade Go versions proactively before EOL — the Go team announces EOL dates 6 months in advance'
+  - 'Use go-version-file: go.mod so your CI automatically follows your module declaration'
+  - 'Monitor https://go.dev/doc/devel/release for maintenance status of Go releases'
+docs:
+  - url: 'https://go.dev/doc/devel/release'
+    label: 'Go release history and maintenance policy'
+  - url: 'https://github.com/actions/setup-go'
+    label: 'actions/setup-go — go-version and go-version-file inputs'
+  - url: 'https://github.com/actions/runner-images'
+    label: 'GitHub runner images — preinstalled tool versions'

package/errors/silent-failures/github-event-before-zeros-new-branch.yml

@@ -0,0 +1,99 @@
+id: silent-failures-092
+title: 'github.event.before is all zeros on first push to a new branch — git diff fails with unknown revision'
+category: silent-failures
+severity: silent-failure
+tags:
+  - push-event
+  - before-sha
+  - new-branch
+  - git-diff
+  - changed-files
+patterns:
+  - regex: 'fatal: ambiguous argument.*0{40}'
+    flags: 'i'
+  - regex: 'unknown revision.*0{10,}.*working tree'
+    flags: 'i'
+  - regex: 'fatal: bad object 0{40}'
+    flags: 'i'
+error_messages:
+  - "fatal: ambiguous argument '0000000000000000000000000000000000000000': unknown revision or path not in the working tree"
+  - "fatal: bad object 0000000000000000000000000000000000000000"
+root_cause: |
+  When a branch is pushed to GitHub for the first time, there is no previous state.
+  GitHub sets github.event.before to the all-zeros SHA (40 zeros) as a sentinel
+  meaning "this is a brand-new branch with no prior history."
+
+  Any workflow step that uses this SHA in git commands fails because 40 zeros is not
+  a valid Git object reference. Common patterns that break:
+    git diff ${{ github.event.before }} ${{ github.sha }} --name-only
+    git log ${{ github.event.before }}..${{ github.sha }}
+
+  This silently breaks:
+  - Changed-file detection scripts that decide which jobs to run
+  - Automated changelog generators that compare before→after SHAs
+  - CI selective-run logic based on modified paths
+  - Commit-message linters that inspect newly added commits only
+
+  The failure is non-obvious because the workflow may succeed on subsequent pushes
+  to the same branch (where before is a real SHA), leading developers to believe
+  the issue was transient or environmental.
+fix: |
+  Guard against the all-zeros SHA before performing git operations:
+
+  Option 1 — Skip the step/job on new-branch pushes with an if: condition:
+    if: github.event.before != '0000000000000000000000000000000000000000'
+
+  Option 2 — Fall back to the initial commit when before is zeros:
+    BEFORE="${{ github.event.before }}"
+    if [ "$BEFORE" = "0000000000000000000000000000000000000000" ]; then
+      BEFORE=$(git rev-list --max-parents=0 HEAD)
+    fi
+    git diff "$BEFORE" "${{ github.sha }}" --name-only
+
+  Option 3 — Use tj-actions/changed-files which handles this case automatically.
+fix_code:
+  - language: yaml
+    label: 'Guard with if: to skip diff on new-branch first push'
+    code: |
+      jobs:
+        diff-check:
+          runs-on: ubuntu-latest
+          # Skip when there is no before commit (first push to new branch)
+          if: github.event.before != '0000000000000000000000000000000000000000'
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                fetch-depth: 0
+            - name: Get changed files
+              run: git diff ${{ github.event.before }} ${{ github.sha }} --name-only
+  - language: yaml
+    label: 'Shell fallback — use initial commit when before SHA is zeros'
+    code: |
+      - name: Get changed files (handles new branch)
+        run: |
+          BEFORE="${{ github.event.before }}"
+          if [ "$BEFORE" = "0000000000000000000000000000000000000000" ]; then
+            # New branch — fall back to root commit
+            BEFORE=$(git rev-list --max-parents=0 HEAD)
+          fi
+          git diff "$BEFORE" "${{ github.sha }}" --name-only
+  - language: yaml
+    label: 'Use tj-actions/changed-files (handles new-branch automatically)'
+    code: |
+      - uses: tj-actions/changed-files@v44
+        id: changed
+        with:
+          since_last_remote_commit: true
+      - run: echo "${{ steps.changed.outputs.all_changed_files }}"
+prevention:
+  - 'Always check github.event.before against the 40-zero sentinel before using it in git commands'
+  - 'Use maintained actions such as tj-actions/changed-files that already handle new-branch edge cases'
+  - 'Add fetch-depth: 0 to actions/checkout so full git history is available for diff operations'
+  - 'Test workflows on a branch that has never had CI run before to catch first-push failures early'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#push'
+    label: 'GitHub Actions — push event payload (before/after SHA fields)'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/contexts#github-context'
+    label: 'GitHub context reference — github.event.before'
+  - url: 'https://github.com/tj-actions/changed-files'
+    label: 'tj-actions/changed-files — handles new-branch and force-push edge cases'

package/errors/silent-failures/pull-request-target-checks-out-base-not-head.yml

@@ -0,0 +1,97 @@
+id: silent-failures-093
+title: 'pull_request_target workflow checks out base branch by default — PR head changes are not tested'
+category: silent-failures
+severity: silent-failure
+tags:
+  - pull-request-target
+  - checkout
+  - base-branch
+  - head-ref
+  - fork-pr
+patterns:
+  - regex: 'pull_request_target.*actions/checkout'
+    flags: 'i'
+  - regex: 'HEAD is now at.*base.*not.*head'
+    flags: 'i'
+error_messages:
+  - "Actions attempted to checkout a merge commit for a pull request but the merge commit was unavailable"
+root_cause: |
+  When a workflow is triggered by pull_request_target, the GITHUB_SHA and the default
+  checkout ref point to the BASE branch of the PR — not the PR head commit.
+
+  This is intentional security behavior: pull_request_target runs in the context of
+  the base repository (with full secrets access), so GitHub deliberately avoids
+  running untrusted code from fork PRs by defaulting to the safe base branch state.
+
+  The result is a silent failure: CI appears to run and pass, but it is actually
+  testing the base branch code, not the contributor's changes. No error is emitted.
+
+  Developers commonly hit this when:
+  - Migrating from pull_request to pull_request_target for Dependabot secrets access
+  - Setting up labeler/auto-assign bots that also want to run tests
+  - Building required-status checks that use pull_request_target for fork support
+
+  Even with actions/checkout@v4, the default ref for pull_request_target is
+  github.sha which resolves to the base branch HEAD — not the merge commit.
+fix: |
+  Explicitly check out the PR head ref when you need to test the contributor's code:
+
+    - uses: actions/checkout@v4
+      with:
+        ref: ${{ github.event.pull_request.head.sha }}
+
+  WARNING: This executes untrusted code from fork contributors in an environment
+  with full repository secrets. Only do this after careful security review:
+  - Gate on github.event.pull_request.head.repo.fork to distinguish fork vs internal
+  - Never expose secrets to steps that run contributor code
+  - Consider using a separate workflow_run trigger instead for fork PRs that need secrets
+
+  For safe automation (labelers, assignment bots), use pull_request_target but do NOT
+  check out the head ref — these actions only need the event payload, not the code.
+fix_code:
+  - language: yaml
+    label: 'Check out PR head for internal PRs only (safe pattern)'
+    code: |
+      on:
+        pull_request_target:
+          types: [opened, synchronize]
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          # Only run contributor code for PRs from the same repo, not forks
+          if: github.event.pull_request.head.repo.full_name == github.repository
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                ref: ${{ github.event.pull_request.head.sha }}
+            - run: npm test
+  - language: yaml
+    label: 'Safe bot usage — do NOT check out head (labeler example)'
+    code: |
+      on:
+        pull_request_target:
+          types: [opened]
+
+      jobs:
+        label:
+          runs-on: ubuntu-latest
+          permissions:
+            pull-requests: write
+          steps:
+            # No checkout needed — labeler only reads the event payload
+            - uses: actions/labeler@v5
+              with:
+                repo-token: ${{ secrets.GITHUB_TOKEN }}
+prevention:
+  - 'Always explicitly set ref: when using actions/checkout with pull_request_target triggers'
+  - 'Never check out the PR head commit in a pull_request_target workflow that has access to secrets unless you have verified the source repo'
+  - 'Prefer pull_request for standard CI — use pull_request_target only when secrets access is required from fork workflows'
+  - 'Read the GitHub security hardening guide before using pull_request_target with any code execution steps'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#pull_request_target'
+    label: 'GitHub Actions — pull_request_target event (security context and checkout behavior)'
+  - url: 'https://securitylab.github.com/research/github-actions-preventing-pwn-requests/'
+    label: 'GitHub Security Lab — Preventing pwn requests with pull_request_target'
+  - url: 'https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions#understanding-the-risk-of-script-injections'
+    label: 'GitHub Actions security hardening guide'

package/errors/yaml-syntax/env-context-unavailable-defaults-run-working-directory.yml

@@ -0,0 +1,113 @@
+id: yaml-syntax-065
+title: 'env context unavailable in defaults.run.working-directory — "Unrecognized named-value: env"'
+category: yaml-syntax
+severity: error
+tags:
+  - env
+  - context
+  - defaults
+  - working-directory
+  - expression
+  - context-availability
+patterns:
+  - regex: 'Unrecognized named-value: ''env''.*defaults|defaults.*working.directory.*env'
+    flags: 'i'
+  - regex: 'The workflow is not valid.*defaults\.run\.working-directory.*env\.'
+    flags: 'i'
+  - regex: 'Unrecognized named-value: ''env''.*position.*working.directory'
+    flags: 'i'
+error_messages:
+  - "The workflow is not valid. .github/workflows/<workflow>.yml (Line: X, Col: Y): Unrecognized named-value: 'env'. Located at position 1 within expression: env.WORKING_DIR"
+  - "Unrecognized named-value: 'env'"
+root_cause: |
+  The `env` context is only available during step execution — not at job evaluation time.
+  `defaults.run.working-directory` is a job-level field evaluated before any steps run,
+  so GitHub Actions rejects references to `env.*` inside it with "Unrecognized named-value: 'env'".
+
+  This is the same fundamental limitation that affects other job-level fields (if:,
+  runs-on, timeout-minutes, continue-on-error) but is less documented for defaults.run.
+
+  Common patterns that fail:
+  - Setting a shared working directory from a workflow-level env variable:
+      env:
+        APP_DIR: './packages/app'
+      jobs:
+        build:
+          defaults:
+            run:
+              working-directory: ${{ env.APP_DIR }}  # FAILS — env not available here
+
+  - Reading an env var set in another job:
+      jobs:
+        setup:
+          ...
+        build:
+          defaults:
+            run:
+              working-directory: ${{ env.BUILD_DIR }}  # FAILS — env from another job not visible
+
+  The limitation applies to all expressions in defaults.run.working-directory and
+  defaults.run.shell at both the workflow level and the job level.
+fix: |
+  Replace env context references in defaults.run.working-directory with contexts that are
+  available at job evaluation time:
+
+  1. Use vars.* (repository or environment variables configured in Settings) for static paths
+  2. Use inputs.* if inside a reusable workflow called with workflow_call
+  3. Set working-directory on each individual step instead of at defaults level
+  4. Use an outputs chain from a prior job if the path is computed dynamically
+fix_code:
+  - language: yaml
+    label: 'WRONG — env context in defaults.run.working-directory (fails)'
+    code: |
+      env:
+        APP_DIR: './packages/app'
+
+      jobs:
+        build:
+          defaults:
+            run:
+              working-directory: ${{ env.APP_DIR }}  # Error: Unrecognized named-value 'env'
+  - language: yaml
+    label: 'FIX option 1 — use vars context (repository variable)'
+    code: |
+      # Configure APP_DIR in Settings > Secrets and variables > Variables
+      jobs:
+        build:
+          defaults:
+            run:
+              working-directory: ${{ vars.APP_DIR }}  # repository variable — available at job level
+  - language: yaml
+    label: 'FIX option 2 — set working-directory on each step directly'
+    code: |
+      jobs:
+        build:
+          env:
+            APP_DIR: './packages/app'
+          steps:
+            - name: Build
+              run: npm run build
+              working-directory: ${{ env.APP_DIR }}  # env IS available at step level
+            - name: Test
+              run: npm test
+              working-directory: ${{ env.APP_DIR }}
+  - language: yaml
+    label: 'FIX option 3 — hardcode the path in defaults.run'
+    code: |
+      jobs:
+        build:
+          defaults:
+            run:
+              working-directory: ./packages/app  # literal path, no context expression needed
+prevention:
+  - 'Only use vars.*, github.*, inputs.*, or needs.*.outputs.* in job-level expressions — env.* is never available at job level'
+  - 'For shared working directories, prefer literal paths in defaults.run.working-directory over expressions'
+  - 'If the path must be dynamic, use step-level working-directory instead of defaults.run'
+  - 'Use actionlint to validate workflows locally — it catches env context misuse in job-level fields'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/setting-default-values-for-jobs'
+    label: 'GitHub Actions — Setting default values for jobs (defaults.run)'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/contexts#context-availability'
+    label: 'GitHub Actions context availability by workflow key'
+  - url: 'https://github.com/rhysd/actionlint'
+    label: 'actionlint — static checker that validates context availability'

package/package.json

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