@htekdev/actions-debugger 1.0.13 → 1.0.15

package/errors/silent-failures/job-output-masked-as-secret-empty.yml

@@ -0,0 +1,147 @@
+id: silent-failures-020
+title: "Job Output Silently Emptied by Secret Masking — Downstream Steps See Empty String"
+category: silent-failures
+severity: silent-failure
+tags:
+  - job-outputs
+  - secrets
+  - masking
+  - empty-output
+  - runner
+  - cryptic
+patterns:
+  - regex: "Value.*masked.*job output"
+    flags: "i"
+  - regex: "\\[MASKED\\].*output"
+    flags: "i"
+  - regex: "Warning.*masked.*not be set as.*output"
+    flags: "i"
+error_messages:
+  - "(no error shown — downstream job receives empty string instead of expected value)"
+  - "Warning: Value is masked and will not be set as an output"
+root_cause: |
+  The GitHub Actions runner applies secret masking to **job outputs**. If a job output
+  value contains a substring that matches a registered secret (or any value added via
+  `add-mask`), the runner replaces the output value with `***` (the masked placeholder)
+  before passing it to dependent jobs.
+
+  When this happens, the downstream job reads the output as an **empty string** (or the
+  literal `***` which evaluates as empty in most conditional checks), producing a silent
+  failure with no error in the logs — the upload/set step exits 0, but the value is gone.
+
+  **Triggers:**
+  - Outputting a value that happens to contain a secret substring (e.g., a build artifact
+    path that includes a secret-derived token)
+  - Using `echo "::add-mask::$VALUE"` and then emitting `$VALUE` as a job output
+  - Dynamic values (UUIDs, tokens, generated keys) that partially overlap masked values
+
+  **Why it's silent:**
+  - The `set-output` / `$GITHUB_OUTPUT` step exits with code 0
+  - The parent job shows "success"
+  - No "masked" warning appears in the UI by default
+  - The dependent job simply receives `""` and often silently skips dependent work
+
+  Sources: actions/runner#1498, GitHub Community discussions/37942
+fix: |
+  **Option 1 (recommended): Encode output before setting, decode before using**
+
+  Base64-encode the value before writing it to `$GITHUB_OUTPUT`. Decode it in the
+  consuming job. Base64 strings do not match secret substrings.
+
+  **Option 2: Avoid passing secret-derived values as job outputs**
+
+  Restructure the workflow so secrets are consumed directly in the job that has access
+  to them rather than forwarded through outputs.
+
+  **Option 3: Check for masking with a debug step**
+
+  Add a step that prints the raw output value to confirm it is not masked before
+  downstream jobs consume it.
+
+  **Option 4: Use artifact upload instead of job outputs for large/sensitive values**
+
+  Upload the value as a workflow artifact (with restricted retention) and download it
+  in dependent jobs — artifacts bypass the masking pipeline.
+fix_code:
+  - language: yaml
+    label: "Broken — output value matches secret pattern, silently emptied"
+    code: |
+      # ❌ BROKEN: If 'generated-token' overlaps with a masked secret, output is empty
+      jobs:
+        generate:
+          runs-on: ubuntu-latest
+          outputs:
+            token: ${{ steps.gen.outputs.token }}
+          steps:
+            - id: gen
+              run: echo "token=$SOME_DERIVED_VALUE" >> $GITHUB_OUTPUT
+
+        consume:
+          needs: generate
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Token is ${{ needs.generate.outputs.token }}"
+              # Prints: "Token is " — silently empty, no error
+  - language: yaml
+    label: "Fixed — base64-encode output to avoid masking collision"
+    code: |
+      # ✅ FIXED: Encode before output, decode before use
+      jobs:
+        generate:
+          runs-on: ubuntu-latest
+          outputs:
+            token_b64: ${{ steps.gen.outputs.token_b64 }}
+          steps:
+            - id: gen
+              run: |
+                DERIVED_VALUE="$(generate-my-token)"
+                # Encode so masking patterns don't match
+                echo "token_b64=$(echo -n "$DERIVED_VALUE" | base64)" >> $GITHUB_OUTPUT
+
+        consume:
+          needs: generate
+          runs-on: ubuntu-latest
+          steps:
+            - run: |
+                # Decode in the consumer job
+                TOKEN=$(echo "${{ needs.generate.outputs.token_b64 }}" | base64 -d)
+                echo "Token: $TOKEN"
+  - language: yaml
+    label: "Fixed — pass value via artifact instead of job output"
+    code: |
+      # ✅ ALTERNATIVE: Use artifact upload to avoid masking pipeline entirely
+      jobs:
+        generate:
+          runs-on: ubuntu-latest
+          steps:
+            - id: gen
+              run: generate-my-token > token.txt
+            - uses: actions/upload-artifact@v4
+              with:
+                name: generated-token
+                path: token.txt
+                retention-days: 1
+
+        consume:
+          needs: generate
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/download-artifact@v4
+              with:
+                name: generated-token
+            - run: TOKEN=$(cat token.txt) && echo "Token: $TOKEN"
+prevention:
+  - "Never pass values through job outputs that contain or partially overlap with known secret values — use artifacts or re-derive them in consuming jobs."
+  - "If a job output starts arriving empty with no error, add a debug step to print `${{ steps.ID.outputs.KEY }}` immediately after the output is set — if it shows `***`, masking is the culprit."
+  - "Avoid `add-mask` on values you later need to pass as job outputs — once masked, the value cannot be safely forwarded."
+  - "Use base64 encoding as a general defensive practice for any dynamic/computed value passed through `$GITHUB_OUTPUT` across jobs."
+  - "Monitor GitHub runner release notes — the masking heuristics have changed across runner versions and may affect previously working workflows."
+docs:
+  - url: "https://github.com/actions/runner/issues/1498"
+    label: "actions/runner#1498 — Job output emptied by secret masking"
+  - url: "https://github.com/orgs/community/discussions/37942"
+    label: "GitHub Community #37942 — Combining job outputs with masking leads to empty output"
+  - url: "https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions#redacting-secrets-in-logs"
+    label: "GitHub Docs: Redacting secrets in logs"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/passing-information-between-jobs"
+    label: "GitHub Docs: Passing information between jobs"

package/errors/silent-failures/upload-artifact-permissions-stripped.yml

@@ -0,0 +1,98 @@
+id: silent-failures-023
+title: "upload-artifact Silently Strips Unix File Permissions (chmod +x Lost)"
+category: silent-failures
+severity: silent-failure
+tags:
+  - upload-artifact
+  - download-artifact
+  - file-permissions
+  - chmod
+  - executable
+  - linux
+  - macos
+patterns:
+  - regex: "Permission denied"
+    flags: "i"
+  - regex: "EACCES: permission denied"
+    flags: "i"
+  - regex: "cannot execute.*Permission denied"
+    flags: "i"
+error_messages:
+  - "/bin/sh: ./script.sh: Permission denied"
+  - "Error: EACCES: permission denied, access '/path/to/binary'"
+  - "bash: ./build/my-binary: Permission denied"
+  - "Process completed with exit code 126"
+root_cause: |
+  The `actions/upload-artifact` action zips files using a Node.js-based zip implementation
+  that does not preserve Unix file permission mode bits. When the artifact is downloaded in
+  a subsequent job with `actions/download-artifact`, all files are extracted with default
+  permissions (typically 0644), silently losing any executable bits or other custom permissions
+  that were set in the producing job.
+
+  This affects any workflow that:
+  - Builds a binary in one job and runs it in a downstream job
+  - Produces shell scripts with +x and executes them after download
+  - Compiles Python wheels with C extensions requiring executable shared libraries
+  - Uses tools that detect file mode bits (e.g., `test -x ./binary`)
+
+  The upload and download both complete with no warnings. The failure only surfaces when the
+  downloaded file is executed in the downstream job. This is a known open issue since 2020
+  affecting both `upload-artifact@v3` and `v4`.
+fix: |
+  Wrap files in a tar archive before uploading. Since the tar utility preserves Unix permission
+  mode bits, permissions survive the upload/download cycle. Alternatively, re-apply permissions
+  explicitly with `chmod` in the downstream job after downloading.
+fix_code:
+  - language: yaml
+    label: "Preserve permissions with tar (recommended)"
+    code: |
+      # --- Job A: Build and upload ---
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Build binary
+              run: |
+                make my-binary
+                chmod +x my-binary
+
+            - name: Package with tar to preserve permissions
+              run: tar -czf artifacts.tar.gz my-binary
+
+            - uses: actions/upload-artifact@v4
+              with:
+                name: my-artifacts
+                path: artifacts.tar.gz
+
+      # --- Job B: Download and run ---
+        deploy:
+          needs: build
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/download-artifact@v4
+              with:
+                name: my-artifacts
+
+            - name: Extract and run (permissions restored)
+              run: |
+                tar -xzf artifacts.tar.gz
+                ./my-binary
+  - language: yaml
+    label: "Re-apply chmod after download"
+    code: |
+      - uses: actions/download-artifact@v4
+        with:
+          name: my-artifacts
+
+      - name: Restore executable permissions
+        run: chmod +x my-binary ./scripts/*.sh
+prevention:
+  - "Never rely on upload-artifact to preserve Unix file permissions — always tar or re-chmod"
+  - "If your downstream job runs a downloaded binary, add `chmod +x` before executing it as a safety habit"
+  - "Use `ls -la` after download as a debug step to verify permissions are what you expect"
+  - "For permission-sensitive artifacts, `actions/cache` can be used as an alternative — it preserves permissions"
+docs:
+  - url: "https://github.com/actions/upload-artifact/issues/38"
+    label: "actions/upload-artifact#38 — upload-artifact does not retain artifact permissions (169 reactions)"
+  - url: "https://github.com/actions/download-artifact/issues/14"
+    label: "actions/download-artifact#14 — download-artifact loses permissions on download (54 reactions)"

package/errors/triggers/pull-request-branches-filter-matches-base-not-head.yml

@@ -0,0 +1,140 @@
+id: triggers-013
+title: "pull_request branches Filter Matches Base (Target) Branch, Not Head (Source) Branch"
+category: triggers
+severity: silent-failure
+tags:
+  - pull-request
+  - branches-filter
+  - base-branch
+  - head-branch
+  - trigger
+  - silent-failure
+patterns:
+  - regex: "branches.*pull_request.*head_ref"
+    flags: "i"
+  - regex: "on.*pull_request.*branches"
+    flags: "i"
+error_messages:
+  - "Workflow not triggered for pull request from feature branch"
+  - "Workflow triggered unexpectedly for pull request to main"
+root_cause: |
+  The `branches:` filter under `on.pull_request` matches the **target (base) branch**
+  of the pull request — i.e., the branch being merged INTO — NOT the source (head)
+  branch the PR was created from.
+
+  This is the opposite of what many developers expect. Common mistakes:
+
+  1. **"Run CI only for PRs from feature branches"** — You write:
+     ```yaml
+     on:
+       pull_request:
+         branches: ['feature/**']
+     ```
+     This does NOT trigger for PRs *from* feature branches. It triggers for PRs
+     *targeting* branches matching `feature/**`. Most feature branches are opened
+     targeting `main` or `develop`, so this filter silently prevents CI from running.
+
+  2. **"Run CI only when targeting main"** — You write the correct filter but test
+     with a PR from `main` to a release branch and are surprised it fires.
+
+  3. **branches-ignore on pull_request** — Same inversion: `branches-ignore` ignores
+     based on the TARGET branch, not the source branch.
+
+  There is no built-in filter for the source (head) branch of a pull request at
+  the trigger level. The `on.pull_request.branches` filter only controls the
+  target/base branch.
+
+  Sources: GitHub Community #26795, Stack Overflow #70101203
+fix: |
+  **To filter by the TARGET (base) branch** (where the PR merges to):
+  Use `on.pull_request.branches:` — this is the intended behavior.
+
+  **To filter by the SOURCE (head) branch** (where the PR was created from):
+  You cannot do this at the `on:` trigger level. Instead, add an `if:` condition on
+  the job or step using `github.head_ref`:
+
+    `if: startsWith(github.head_ref, 'feature/')`
+
+  **To trigger only on PRs targeting main:**
+  ```yaml
+  on:
+    pull_request:
+      branches: [main]
+  ```
+  This is correct — branches: [main] means "PRs whose base is main".
+fix_code:
+  - language: yaml
+    label: "Broken — developer intends to filter by head/source branch but branches: filters base"
+    code: |
+      # ❌ BROKEN: developer wants CI only for PRs from 'feature/**' branches
+      # but branches: matches TARGET branch, not SOURCE branch
+      # This workflow will NOT trigger for "feature/my-feat → main" PRs
+      # (because 'main' doesn't match 'feature/**')
+      on:
+        pull_request:
+          branches:
+            - 'feature/**'    # This matches the BASE branch, not the head branch!
+  - language: yaml
+    label: "Fixed — use if: condition on github.head_ref to filter by source branch"
+    code: |
+      # ✅ FIXED: trigger on all PRs, then conditionally run based on head_ref
+      on:
+        pull_request:
+
+      jobs:
+        ci:
+          # Only run for PRs from feature branches (filtering by HEAD/source branch)
+          if: startsWith(github.head_ref, 'feature/')
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm test
+  - language: yaml
+    label: "Correct — branches: to filter by TARGET branch (the intended use case)"
+    code: |
+      # ✅ CORRECT: run CI only for PRs targeting main or release branches
+      # (branches: matches the BASE/target branch — the branch being merged INTO)
+      on:
+        pull_request:
+          branches:
+            - main
+            - 'release/**'
+
+      jobs:
+        ci:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm test
+  - language: yaml
+    label: "Both filters — target main AND from a feature branch"
+    code: |
+      # ✅ Combine trigger-level base filter with job-level head_ref condition
+      on:
+        pull_request:
+          branches:
+            - main          # Only for PRs targeting main
+
+      jobs:
+        ci:
+          # Further restrict to feature/* source branches only
+          if: startsWith(github.head_ref, 'feature/')
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm test
+prevention:
+  - "Remember: `on.pull_request.branches` matches the BASE (target) branch — the branch being merged into."
+  - "To filter by the source branch, use `if: startsWith(github.head_ref, 'your-prefix/')` at the job level."
+  - "Test your trigger config by opening a test PR and checking the Actions tab — verify the workflow does/doesn't trigger as expected."
+  - "`github.base_ref` = target branch name. `github.head_ref` = source branch name. Know the difference."
+  - "Use `branches-ignore:` to exclude PRs targeting specific branches (e.g., skip CI for PRs targeting a `docs` branch)."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#pull_request"
+    label: "pull_request event — branches filter behavior"
+  - url: "https://github.com/orgs/community/discussions/26795"
+    label: "GitHub Community #26795 — branches filter matches base not head"
+  - url: "https://stackoverflow.com/questions/70101203/github-actions-workflow-syntax-not-working-as-expected"
+    label: "Stack Overflow #70101203 — pull_request branches filter confusion"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/using-filters#using-filters-to-target-specific-branches-for-pull-request-events"
+    label: "Using filters to target specific branches for pull request events"

package/errors/triggers/push-event-fires-on-branch-delete.yml

@@ -0,0 +1,129 @@
+id: triggers-015
+title: "on: push Fires When a Branch Is Deleted — Unguarded Workflows Fail"
+category: triggers
+severity: error
+tags:
+  - push
+  - branch-delete
+  - github.event.deleted
+  - ref-not-found
+  - workflow-trigger
+  - branch-cleanup
+patterns:
+  - regex: "on:\\s*push"
+    flags: "im"
+  - regex: "github\\.event\\.deleted"
+    flags: "i"
+  - regex: "fatal.*not.*a.*git repository|fatal.*couldn't find remote ref"
+    flags: "i"
+error_messages:
+  - "fatal: couldn't find remote ref refs/heads/my-feature-branch"
+  - "Error: The process '/usr/bin/git' failed with exit code 128"
+  - "fatal: not a git repository (or any of the parent directories): .git"
+  - "remote: Repository not found"
+root_cause: |
+  GitHub's `push` webhook fires on ALL ref write operations, including branch and tag
+  deletions. When a branch is deleted, a push event is emitted with:
+    - `github.event.deleted == true`
+    - `github.event.created == false`
+    - `github.ref` set to the deleted branch ref (e.g., `refs/heads/feature-xyz`)
+    - `github.event.after` set to `0000000000000000000000000000000000000000` (40 zeros)
+    - `github.sha` reverts to the default branch SHA
+
+  Workflows triggered by `on: push` that do not guard against deletion events can:
+  - Fail when `actions/checkout` tries to check out a branch that no longer exists
+  - Trigger deployment pipelines, test suites, or notification workflows unexpectedly
+  - Produce misleading failures that look like unrelated CI breakage
+
+  This is especially problematic in workflows that:
+  - Checkout a specific branch ref from `github.ref`
+  - Run clean-up scripts expecting the branch to exist
+  - Use `git describe` or `git log` on the tip of the deleted branch
+
+  GitHub documentation notes: "When you delete a branch, the SHA in the workflow run
+  (and its associated refs) reverts to the default branch of the repository."
+  Source: GitHub Docs — Events that trigger workflows (push event payload)
+  Source: GitHub Docs — Webhook events and payloads (`deleted` field on push payload)
+fix: |
+  Add an `if:` guard to any job or workflow step that should not run on branch deletions.
+  The `github.event.deleted` context field is `true` when the push event is a deletion.
+
+  For most push-triggered workflows, the intent is to react to new commits — guard with:
+    `if: github.event.deleted != true`
+
+  For tag deletion events, also check `github.event.ref_type` if you use the `delete`
+  event, or use `if: github.event.deleted != true && !startsWith(github.ref, 'refs/tags/')`.
+
+  Alternatively, use the `on: delete` event for branch/tag cleanup workflows instead of
+  listening for deletions via the push event.
+fix_code:
+  - language: yaml
+    label: "Guard push jobs from running on branch deletion"
+    code: |
+      on:
+        push:
+          branches:
+            - 'feature/**'
+            - 'fix/**'
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          # ✅ Skip the job entirely when the push is a branch deletion
+          if: github.event.deleted != true
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm ci && npm test
+
+  - language: yaml
+    label: "Per-step guard if you need some steps to run on deletion"
+    code: |
+      jobs:
+        process:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Checkout (skip on delete)
+              if: github.event.deleted != true
+              uses: actions/checkout@v4
+
+            - name: Run tests (skip on delete)
+              if: github.event.deleted != true
+              run: npm test
+
+            - name: Log branch deleted
+              if: github.event.deleted == true
+              run: echo "Branch ${{ github.ref_name }} was deleted"
+
+  - language: yaml
+    label: "Use on: delete event for cleanup workflows instead"
+    code: |
+      # Prefer the dedicated 'delete' event for branch/tag cleanup
+      on:
+        delete:
+          # Optionally filter to branches only (not tags)
+
+      jobs:
+        cleanup:
+          runs-on: ubuntu-latest
+          # github.event.ref is the deleted branch/tag name
+          # github.event.ref_type is 'branch' or 'tag'
+          if: github.event.ref_type == 'branch'
+          steps:
+            - name: Clean up preview environment
+              run: |
+                echo "Cleaning up for deleted branch: ${{ github.event.ref }}"
+                ./scripts/teardown-preview.sh "${{ github.event.ref }}"
+
+prevention:
+  - "Add `if: github.event.deleted != true` to all jobs in `on: push` workflows."
+  - "Use the `on: delete` event for branch/tag teardown workflows instead of catching deletions via push."
+  - "Check `github.event.after == '0000000000000000000000000000000000000000'` as an alternative deletion guard."
+  - "Avoid checking out `${{ github.ref }}` directly; use `actions/checkout` defaults which handle this gracefully."
+  - "Add branch filters under `on: push: branches:` to limit which branches trigger the workflow."
+docs:
+  - url: "https://docs.github.com/en/webhooks/webhook-events-and-payloads#push"
+    label: "GitHub Docs: push webhook event payload (deleted field)"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#push"
+    label: "GitHub Docs: push event trigger"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#delete"
+    label: "GitHub Docs: delete event trigger"

package/errors/triggers/push-first-commit-before-sha-zeros.yml

@@ -0,0 +1,160 @@
+id: triggers-014
+title: "github.event.before Is All Zeros on First Push to a New Branch — git diff Fails"
+category: triggers
+severity: error
+tags:
+  - push
+  - first-push
+  - git-diff
+  - before-sha
+  - new-branch
+  - branch-creation
+patterns:
+  - regex: "fatal.*bad revision.*0000000000000000000000000000000000000000"
+    flags: "i"
+  - regex: "fatal.*ambiguous argument '0{40}'"
+    flags: "i"
+  - regex: "unknown revision or path not in the working tree.*0{10}"
+    flags: "i"
+  - regex: "0{40}\\.\\.\\.\\$\\{\\{.*github\\.event\\.before"
+    flags: "i"
+error_messages:
+  - "fatal: bad revision '0000000000000000000000000000000000000000...HEAD'"
+  - "fatal: ambiguous argument '0000000000000000000000000000000000000000': unknown revision or path not in the working tree"
+  - "error: object file .git/objects/00/00000000000000000000000000000000000000 is empty"
+root_cause: |
+  When a **new branch is pushed for the first time**, `github.event.before` is set to
+  `0000000000000000000000000000000000000000` (40 zeros), representing the null/empty SHA.
+  This indicates there was no previous commit on this branch — it is a branch creation event.
+
+  Workflows that use `github.event.before` to compute a diff range (e.g., to find changed
+  files) fail when run on a first push because `git diff` or `git log` cannot resolve the
+  null SHA:
+
+  ```yaml
+  run: git diff ${{ github.event.before }}...HEAD
+  # On first push: git diff 0000000000000000000000000000000000000000...HEAD → FATAL ERROR
+  ```
+
+  **When this occurs:**
+  - First push to a new branch (branch creation)
+  - `push` events that create a new branch (`github.event.created == true`)
+  - Forced pushes that reference a non-existent before-SHA (rare)
+
+  **Why it's painful:**
+  - Workflows work fine for subsequent pushes (where `before` is a real commit)
+  - The error only appears on the first push, often during branch creation in a PR workflow
+  - The error message references the git object store internals, not the workflow context
+  - Developers check out the diff command syntax without realizing the SHA is invalid
+fix: |
+  **Option 1 (recommended): Guard against the null SHA before running git diff**
+
+  Check if `github.event.before` is the null SHA and fall back to diffing against the
+  merge base or the initial commit.
+
+  **Option 2: Use the `dorny/paths-filter` action**
+
+  The `dorny/paths-filter` action handles first-push, force-push, and all edge cases
+  in branch diff computation automatically.
+
+  **Option 3: Use `github.event.created` to skip diff-based logic on branch creation**
+
+  Add an `if: github.event.created != true` guard to diff-dependent steps so they only
+  run on non-creation push events.
+fix_code:
+  - language: yaml
+    label: "Broken — git diff with github.event.before fails on first push"
+    code: |
+      # ❌ BROKEN: Fails when branch is pushed for the first time
+      on: push
+
+      jobs:
+        lint-changed:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                fetch-depth: 0
+            - name: Lint only changed files
+              run: |
+                CHANGED=$(git diff --name-only ${{ github.event.before }}...HEAD)
+                # FATAL on first push: 0000000000000000000000000000000000000000 is not a commit
+  - language: yaml
+    label: "Fixed — guard against null SHA before git diff"
+    code: |
+      # ✅ FIXED: Check for null SHA and fall back to first commit
+      on: push
+
+      jobs:
+        lint-changed:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                fetch-depth: 0
+            - name: Lint only changed files
+              run: |
+                BEFORE="${{ github.event.before }}"
+                NULL_SHA="0000000000000000000000000000000000000000"
+
+                if [ "$BEFORE" = "$NULL_SHA" ]; then
+                  # First push to new branch — diff against the initial commit or all files
+                  echo "First push to branch, diffing all files"
+                  CHANGED=$(git diff --name-only $(git rev-list --max-parents=0 HEAD)...HEAD)
+                else
+                  CHANGED=$(git diff --name-only "$BEFORE"...HEAD)
+                fi
+                echo "$CHANGED"
+  - language: yaml
+    label: "Fixed — skip diff steps on branch creation using github.event.created"
+    code: |
+      # ✅ FIXED: Skip diff-based steps entirely on first push (branch creation)
+      on: push
+
+      jobs:
+        lint-changed:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                fetch-depth: 0
+            - name: Lint only changed files
+              # Skip on branch creation (before SHA is null)
+              if: github.event.created != true
+              run: |
+                git diff --name-only ${{ github.event.before }}...HEAD | xargs eslint
+  - language: yaml
+    label: "Fixed — use dorny/paths-filter which handles null SHA automatically"
+    code: |
+      # ✅ RECOMMENDED: dorny/paths-filter handles first-push and force-push edge cases
+      on: push
+
+      jobs:
+        lint-changed:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - uses: dorny/paths-filter@v3
+              id: changes
+              with:
+                filters: |
+                  src:
+                    - 'src/**'
+                  tests:
+                    - 'tests/**'
+            - name: Lint src changes
+              if: steps.changes.outputs.src == 'true'
+              run: npm run lint
+prevention:
+  - "Never use `git diff ${{ github.event.before }}` without guarding against the null SHA (`0000000000000000000000000000000000000000`) — this is guaranteed to fail on first push."
+  - "Prefer `dorny/paths-filter` for changed-file detection — it handles all SHA edge cases (first push, force push, merge commits) internally."
+  - "If you must use raw git diff, always add: `if [ \"$BEFORE\" = \"$NULL_SHA\" ]; then echo 'first push'; exit 0; fi`."
+  - "Test your diff workflows by creating a fresh test branch — don't only test on subsequent pushes where `before` is always valid."
+  - "Use `github.event.created == true` in `if:` conditions to identify branch creation events and handle them separately."
+docs:
+  - url: "https://docs.github.com/en/webhooks/webhook-events-and-payloads#push"
+    label: "GitHub Docs: push webhook event payload — before field"
+  - url: "https://github.com/dorny/paths-filter"
+    label: "dorny/paths-filter — changed file detection with edge case handling"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#push"
+    label: "GitHub Docs: Events that trigger workflows — push"