@htekdev/actions-debugger 1.0.102 → 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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@htekdev/actions-debugger",
-  "version": "1.0.102",
+  "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",