@htekdev/actions-debugger 1.0.102 → 1.0.104

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/caching-artifacts/upload-artifact-v4-hidden-files-excluded-by-default.yml

@@ -0,0 +1,82 @@
+id: caching-artifacts-059
+title: 'actions/upload-artifact@v4 excludes hidden files by default — dotfiles silently missing from artifacts'
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - upload-artifact
+  - v4
+  - hidden-files
+  - dotfiles
+  - include-hidden-files
+  - silent-omission
+patterns:
+  - regex: 'uses:\s*actions/upload-artifact@v4'
+    flags: 'i'
+  - regex: 'include-hidden-files:\s*false'
+    flags: 'i'
+error_messages:
+  - 'No files were found with the provided path'
+  - 'Uploading 0 files'
+  - 'Found no files matching'
+root_cause: |
+  actions/upload-artifact@v4 introduced the include-hidden-files input, which defaults
+  to false. Any file or directory whose name begins with a dot (.) is silently excluded
+  from the artifact upload. The action completes with a success status and reports the
+  number of files uploaded — only inspecting that count reveals that dotfiles were
+  skipped.
+
+  Common files and directories affected:
+    .env, .env.production, .env.local     — environment configuration
+    .npmrc, .nvmrc, .node-version          — Node.js toolchain config
+    .htaccess                              — Apache web server config
+    .browserslistrc, .babelrc              — build tool configuration
+    .next/, .nuxt/, .svelte-kit/           — framework build output directories
+    .vitepress/, .docusaurus/              — documentation build output
+
+  Workflows migrated from v3 to v4 silently break: the artifact is created and
+  downloaded without any error, but dependent steps fail when the expected dotfiles
+  are absent. Framework deployments (Next.js, Nuxt, SvelteKit) that upload their build
+  output are most frequently affected since their output directories are hidden.
+fix: |
+  Set include-hidden-files: true on the upload step whenever dotfiles or dot-directories
+  must be preserved in the artifact:
+
+    - uses: actions/upload-artifact@v4
+      with:
+        name: build-output
+        path: ./dist
+        include-hidden-files: true
+
+  Alternatively, explicitly list only the required hidden files in the path input to
+  avoid uploading the entire directory with hidden file inclusion.
+fix_code:
+  - language: yaml
+    label: 'Add include-hidden-files: true to preserve dotfiles and dot-directories'
+    code: |
+      - name: Upload build artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: build-output
+          path: ./.next          # Next.js build output is a hidden directory
+          include-hidden-files: true   # required — excluded by default in v4
+  - language: yaml
+    label: 'Alternative: explicitly list hidden files instead of directory glob'
+    code: |
+      - name: Upload build artifacts including dotfiles
+        uses: actions/upload-artifact@v4
+        with:
+          name: build-output
+          path: |
+            ./dist
+            ./.env.production
+            ./.nvmrc
+            ./.npmrc
+prevention:
+  - 'Set include-hidden-files: true when uploading directories known to contain dotfiles or dot-directories (.next/, .nuxt/, .svelte-kit/, etc.)'
+  - 'After migrating from upload-artifact@v3 to @v4, inspect the artifact file count in the run log — a drop indicates hidden files were excluded'
+  - 'Add a post-upload verification step: download the artifact in a subsequent job and assert the expected dotfiles exist'
+docs:
+  - url: 'https://github.com/actions/upload-artifact/blob/main/README.md'
+    label: 'actions/upload-artifact README: include-hidden-files input'
+  - url: 'https://github.com/actions/upload-artifact/blob/main/docs/migration-v3-to-v4.md'
+    label: 'Migration guide: upload-artifact v3 to v4'

package/errors/concurrency-timing/github-run-id-concurrency-group-disables-cancel-in-progress.yml

@@ -0,0 +1,90 @@
+id: concurrency-timing-048
+title: 'github.run_id in concurrency group key disables cancel-in-progress — every run is unique, unlimited parallelism'
+category: concurrency-timing
+severity: silent-failure
+tags:
+  - concurrency
+  - cancel-in-progress
+  - github-run-id
+  - unique-key
+  - parallelism
+  - anti-pattern
+patterns:
+  - regex: 'group:.*\$\{\{\s*github\.run_id\s*\}\}'
+    flags: 'i'
+  - regex: 'group:.*github\.run_id'
+    flags: 'i'
+error_messages:
+  - 'Old workflow runs are not being cancelled despite cancel-in-progress: true'
+  - 'Multiple concurrent runs executing simultaneously'
+root_cause: |
+  github.run_id is always unique per workflow run — it is the numeric identifier
+  assigned at run creation time. When used in the concurrency group key, every run
+  evaluates to a different group name. No two runs ever share the same group, so
+  cancel-in-progress: true has nothing to cancel. All runs proceed simultaneously.
+
+  This anti-pattern typically originates from developers who experienced unwanted
+  concurrency cancellations and "fixed" the problem by adding a unique value to the
+  group key. The immediate cancellation symptom disappears but a more serious problem
+  is introduced: on high-velocity branches, dozens of in-progress CI runs pile up
+  simultaneously, exhausting the available runner pool and increasing costs.
+
+  Related: github.sha in the group key has the same effect (concurrency-timing-030),
+  but github.run_id is more severe. github.sha can repeat when a commit is re-run;
+  github.run_id is unconditionally unique per run and per re-run attempt, so
+  cancel-in-progress is permanently disabled with no exceptions.
+fix: |
+  Remove github.run_id from the concurrency group key. Use github.ref (for branch-scoped
+  deduplication) or github.head_ref (for PR-scoped deduplication). If the original
+  goal was to prevent manual dispatch runs from being cancelled, scope the unique key
+  to workflow_dispatch events only using a conditional expression:
+
+    group: >-
+      ${{ github.workflow }}-
+      ${{ github.event_name == 'workflow_dispatch' && github.run_id || github.ref }}
+fix_code:
+  - language: yaml
+    label: 'Wrong: github.run_id makes every run unique — cancel-in-progress is dead code'
+    code: |
+      # WRONG: every run gets its own unique group — cancel-in-progress never fires
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.ref }}-${{ github.run_id }}
+        cancel-in-progress: true  # never cancels anything
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+  - language: yaml
+    label: 'Correct: branch-scoped group key enables cancel-in-progress'
+    code: |
+      # CORRECT: all pushes to same branch share one group
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.ref }}
+        cancel-in-progress: true
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+  - language: yaml
+    label: 'Advanced: isolate manual dispatch runs while deduplicating automated runs'
+    code: |
+      # Manual dispatch runs are never cancelled; push/PR runs cancel old runs on same branch
+      concurrency:
+        group: >-
+          ${{ github.workflow }}-
+          ${{ github.event_name == 'workflow_dispatch' && github.run_id || github.ref }}
+        cancel-in-progress: true
+prevention:
+  - 'Never add github.run_id to a concurrency group key when the goal is to cancel old runs — it defeats cancel-in-progress entirely'
+  - 'Verify cancel-in-progress by triggering two rapid pushes and confirming the first run is cancelled in the Actions UI'
+  - 'If cancellation of specific trigger types is unwanted, use event_name-conditional keys instead of unique values'
+  - 'Monitor runner utilization — unbounded parallel runs will exhaust available runners and increase billing'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-concurrency'
+    label: 'GitHub Docs: Using concurrency'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/contexts#github-context'
+    label: 'GitHub Docs: github context — run_id'

package/errors/concurrency-timing/pull-request-target-base-ref-concurrency-serializes-all-prs.yml

@@ -0,0 +1,78 @@
+id: concurrency-timing-046
+title: 'pull_request_target github.ref resolves to base branch — all PRs targeting same branch share one concurrency slot'
+category: concurrency-timing
+severity: silent-failure
+tags:
+  - concurrency
+  - pull_request_target
+  - github-ref
+  - base-branch
+  - serialization
+patterns:
+  - regex: 'on:\s*\n\s+pull_request_target:'
+    flags: 'ms'
+  - regex: 'group:.*github\.ref'
+    flags: 'i'
+error_messages:
+  - 'This run was automatically queued'
+  - 'Waiting for a pending job to complete'
+root_cause: |
+  On pull_request events, github.ref is the head branch ref (e.g., refs/heads/my-feature).
+  On pull_request_target events, however, github.ref is the BASE branch ref (e.g.,
+  refs/heads/main) — the branch the PR targets. This is a security design choice that
+  prevents untrusted fork code from influencing the event ref.
+
+  When a concurrency group key uses github.ref in a pull_request_target workflow, all
+  open PRs targeting the same base branch (main, develop, etc.) evaluate to the identical
+  group key. Only one PR's CI can run at a time; all others queue behind it. On repos
+  with many open PRs, this effectively serializes all PR workflows into a single lane
+  with potentially multi-hour wait times.
+
+  The correct per-PR identifier in pull_request_target workflows is
+  github.event.pull_request.number — unique per PR regardless of base branch.
+fix: |
+  Replace github.ref with github.event.pull_request.number in concurrency group keys
+  for pull_request_target workflows. PR numbers are unique per repository and stable
+  across new commits to the same PR:
+
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
+      cancel-in-progress: true
+fix_code:
+  - language: yaml
+    label: 'Wrong: github.ref = base branch on pull_request_target — all PRs share one slot'
+    code: |
+      # WRONG: github.ref = refs/heads/main for ALL PRs targeting main
+      on:
+        pull_request_target:
+
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.ref }}  # same for every PR!
+        cancel-in-progress: true
+  - language: yaml
+    label: 'Correct: use github.event.pull_request.number for per-PR isolation'
+    code: |
+      # CORRECT: PR number is unique per PR, stable across pushes to same PR
+      on:
+        pull_request_target:
+
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
+        cancel-in-progress: true
+
+      jobs:
+        lint:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                ref: ${{ github.event.pull_request.head.sha }}
+prevention:
+  - 'In pull_request_target workflows, never use github.ref as the sole differentiator in concurrency groups — it is the base branch ref'
+  - 'Use github.event.pull_request.number to scope concurrency to individual PRs'
+  - 'Audit concurrency groups when migrating workflows from pull_request to pull_request_target'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#pull_request_target'
+    label: 'GitHub Docs: pull_request_target event'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-concurrency'
+    label: 'GitHub Docs: Using concurrency'

package/errors/concurrency-timing/workflow-dispatch-schedule-shared-concurrency-kills-scheduled-run.yml

@@ -0,0 +1,87 @@
+id: concurrency-timing-047
+title: 'workflow_dispatch and schedule sharing a concurrency group — manual dispatch silently cancels queued scheduled run'
+category: concurrency-timing
+severity: silent-failure
+tags:
+  - concurrency
+  - workflow_dispatch
+  - schedule
+  - cancel-in-progress
+  - scheduled-job
+patterns:
+  - regex: 'schedule:.*\n.*workflow_dispatch:|workflow_dispatch:.*\n.*schedule:'
+    flags: 'ms'
+  - regex: 'group:\s*.*github\.workflow'
+    flags: 'i'
+error_messages:
+  - 'This run was automatically cancelled'
+  - 'Canceling since a higher priority waiting run was found'
+root_cause: |
+  When a workflow is triggered by both schedule and workflow_dispatch and uses a shared
+  concurrency group key that does not include github.event_name (e.g.,
+  group: ${{ github.workflow }}-${{ github.ref }}), all runs — regardless of trigger
+  type — map to the same concurrency slot.
+
+  When cancel-in-progress: true is set, any manual workflow_dispatch run immediately
+  cancels the scheduled run that may be actively executing. A developer who triggers
+  a manual run can silently kill a scheduled maintenance job, nightly report, or backup
+  workflow with no warning or notification.
+
+  When cancel-in-progress: false, GitHub only keeps one pending run per concurrency
+  slot. A queued scheduled run is silently displaced when the dispatch run arrives.
+  The scheduled run is discarded with no error, no notification, and no log entry.
+
+  This affects maintenance workflows, report generators, data sync jobs, and backup
+  workflows where workflow_dispatch is added for "emergency manual runs" after the
+  initial scheduled implementation.
+fix: |
+  Include github.event_name in the concurrency group key to give each trigger type
+  its own independent concurrency slot:
+
+    group: ${{ github.workflow }}-${{ github.event_name }}-${{ github.ref }}
+
+  This ensures that manual dispatch runs and scheduled runs never compete for the
+  same slot and cannot cancel each other.
+fix_code:
+  - language: yaml
+    label: 'Wrong: schedule and workflow_dispatch share the same concurrency slot'
+    code: |
+      on:
+        schedule:
+          - cron: '0 3 * * *'   # nightly at 03:00 UTC
+        workflow_dispatch:
+
+      # WRONG: both trigger types evaluate to the same group key
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.ref }}
+        cancel-in-progress: true  # dispatch run kills the in-progress scheduled run
+  - language: yaml
+    label: 'Correct: include github.event_name to isolate trigger types'
+    code: |
+      on:
+        schedule:
+          - cron: '0 3 * * *'
+        workflow_dispatch:
+
+      # CORRECT: schedule and workflow_dispatch get separate concurrency slots
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.event_name }}-${{ github.ref }}
+        cancel-in-progress: true
+
+      jobs:
+        nightly:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: ./nightly-tasks.sh
+prevention:
+  - 'Always include ${{ github.event_name }} in the concurrency group for workflows with multiple trigger event types'
+  - 'After adding workflow_dispatch to an existing scheduled workflow, verify scheduled runs are not silently displaced'
+  - 'Monitor the Actions tab run history — consecutive scheduled run gaps may indicate silent cancellations'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-concurrency'
+    label: 'GitHub Docs: Using concurrency'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#schedule'
+    label: 'GitHub Docs: schedule event'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_dispatch'
+    label: 'GitHub Docs: workflow_dispatch event'

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.104",
   "description": "65+ real GitHub Actions errors, queryable by agents. CLI + MCP server + Copilot skills + error database.",
   "type": "module",
   "main": "./dist/index.js",