@htekdev/actions-debugger 1.0.14 → 1.0.15

package/errors/silent-failures/github-sha-pr-merge-commit-not-head.yml

@@ -0,0 +1,150 @@
+id: silent-failures-021
+title: "GITHUB_SHA on pull_request Is the Synthetic Merge Commit — Not the PR Head Commit"
+category: silent-failures
+severity: silent-failure
+tags:
+  - pull_request
+  - github-sha
+  - GITHUB_SHA
+  - merge-commit
+  - head-sha
+  - docker-tag
+  - commit-lookup
+  - git-show
+patterns:
+  - regex: "github\\.sha"
+    flags: "i"
+  - regex: "GITHUB_SHA"
+    flags: ""
+  - regex: "git show \\$\\{\\{\\s*github\\.sha\\s*\\}\\}"
+    flags: "i"
+  - regex: "commit.*not found|unknown revision or path not in the working tree"
+    flags: "i"
+error_messages:
+  - "fatal: ambiguous argument 'abc1234ef56': unknown revision or path not in the working tree"
+  - "Error: An object named 'abc1234' is not in the repository"
+  - "error: pathspec 'abc1234ef56' did not match any file(s) known to git"
+  - "commit not found: abc1234ef5678"
+root_cause: |
+  When a workflow is triggered by the `pull_request` (or `pull_request_target`) event,
+  `github.sha` and `GITHUB_SHA` do NOT contain the SHA of the PR author's latest commit.
+  Instead, they contain the SHA of a **synthetic merge commit** — a prospective merge of
+  the PR head branch into the target branch, created by GitHub on the fly as
+  `refs/pull/<number>/merge`.
+
+  This merge commit:
+  - Exists only as a special GitHub ref, not as a real commit in the repo's history
+  - Is NOT returned by `git log` on the PR branch
+  - Cannot be resolved by `git show <sha>` after a shallow fetch-depth:1 checkout
+  - Has a different SHA than the PR author's actual commit
+
+  This silently breaks common patterns:
+  - Docker image tagging: `docker build -t myimage:${{ github.sha }}` then looking up
+    that SHA in CI/CD systems finds nothing in the actual branch history
+  - Commit status APIs: posting status to `github.sha` may fail or post to an
+    unexpected ref
+  - Manual `git log --pretty=format:'%H' | grep ${{ github.sha }}` returns nothing
+  - `git show ${{ github.sha }}` after shallow clone fails with "unknown revision"
+
+  The correct variable to get the PR author's head commit SHA is:
+    `github.event.pull_request.head.sha`
+
+  For `workflow_run` events, use:
+    `github.event.workflow_run.head_sha`
+
+  This behavior is documented in the GitHub environment variables reference but not
+  prominently called out, leading to widespread confusion.
+  Source: github/docs#15302 — "GITHUB_SHA on PRs refers to the merge commit"
+  Source: github/docs#17767 — "github.sha description is misleading for pull_request"
+  Source: github/docs#30093 — equivalent of github.sha for other events
+fix: |
+  Replace `github.sha` with `github.event.pull_request.head.sha` whenever you need
+  the actual PR author's commit SHA in a `pull_request`-triggered workflow.
+
+  For `workflow_run`, use `github.event.workflow_run.head_sha`.
+  For `push` events, `github.sha` is correct (it IS the pushed commit's SHA).
+
+  If your workflow must be compatible with multiple event types, add a step to compute
+  the correct SHA once and expose it via `GITHUB_OUTPUT`:
+    ```
+    COMMIT_SHA=${{ github.event.pull_request.head.sha || github.sha }}
+    ```
+  Note: The `||` expression operator works in GitHub Actions expressions —
+  `github.event.pull_request.head.sha` is empty for non-PR events, so `github.sha`
+  becomes the fallback.
+fix_code:
+  - language: yaml
+    label: "Fix: use github.event.pull_request.head.sha for PR head commit"
+    code: |
+      on: pull_request
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            # ❌ WRONG: github.sha is the merge commit SHA, not the PR head commit
+            - name: Tag Docker image (wrong SHA)
+              run: docker build -t myimage:${{ github.sha }} .
+
+            # ✅ CORRECT: use the PR head commit SHA
+            - name: Tag Docker image (correct SHA)
+              run: docker build -t myimage:${{ github.event.pull_request.head.sha }} .
+
+  - language: yaml
+    label: "Cross-event SHA: works for both push and pull_request"
+    code: |
+      on:
+        push:
+        pull_request:
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Resolve correct commit SHA
+              id: sha
+              run: |
+                # For pull_request: use head.sha; for push: fall back to github.sha
+                COMMIT_SHA="${{ github.event.pull_request.head.sha || github.sha }}"
+                echo "commit_sha=$COMMIT_SHA" >> "$GITHUB_OUTPUT"
+
+            - name: Use resolved SHA
+              run: docker build -t myimage:${{ steps.sha.outputs.commit_sha }} .
+
+  - language: yaml
+    label: "workflow_run: use head_sha from the triggering workflow"
+    code: |
+      on:
+        workflow_run:
+          workflows: [CI]
+          types: [completed]
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            # ❌ WRONG: github.sha on workflow_run is the default branch SHA
+            - run: echo "Wrong SHA: ${{ github.sha }}"
+
+            # ✅ CORRECT: head_sha is the SHA of the commit that triggered the upstream workflow
+            - run: echo "Correct SHA: ${{ github.event.workflow_run.head_sha }}"
+
+prevention:
+  - "Never use `github.sha` directly in `pull_request` workflows — always use `github.event.pull_request.head.sha`."
+  - "Add a comment in your workflow YAML calling out which SHA variable to use for which event."
+  - "For Docker tagging and commit status APIs in PR workflows, always derive the SHA from the event payload."
+  - "Add a debug step printing both `github.sha` and `github.event.pull_request.head.sha` when troubleshooting."
+  - "For `workflow_run` events, use `github.event.workflow_run.head_sha` not `github.sha`."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#github-context"
+    label: "GitHub Docs: github context — github.sha"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#pull_request"
+    label: "GitHub Docs: pull_request event (GITHUB_SHA value)"
+  - url: "https://github.com/github/docs/issues/15302"
+    label: "github/docs#15302: GITHUB_SHA on PRs refers to the merge commit"
+  - url: "https://github.com/github/docs/issues/17767"
+    label: "github/docs#17767: github.sha description is misleading for pull_request"

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"