@htekdev/actions-debugger 1.0.14 → 1.0.16

package/errors/silent-failures/github-env-multiline-value-truncated.yml

@@ -0,0 +1,127 @@
+id: silent-failures-019
+title: "GITHUB_ENV Multiline Values Silently Truncate Without Heredoc Delimiter Format"
+category: silent-failures
+severity: silent-failure
+tags:
+  - GITHUB_ENV
+  - environment-variable
+  - multiline
+  - heredoc
+  - truncation
+  - env-file
+patterns:
+  - regex: "GITHUB_ENV.*multiline|multiline.*GITHUB_ENV"
+    flags: "i"
+  - regex: "Invalid format '.*\\n'"
+    flags: "i"
+  - regex: "Error: Failed to parse environment file"
+    flags: "i"
+error_messages:
+  - "Error: Failed to parse environment file"
+  - "Invalid format 'MY_VAR=line1\nline2'"
+  - "Warning: Environment file exporting failed"
+root_cause: |
+  When setting an environment variable with `$GITHUB_ENV` that contains **newline
+  characters**, naïvely echoing the value produces an invalid environment file entry
+  that is silently truncated or causes a parse error.
+
+  The environment file format used by GitHub Actions expects single-line `KEY=VALUE`
+  entries. If a value contains a literal newline, the runner cannot parse it and
+  typically:
+  - Silently truncates the value at the first newline (the variable gets only the
+    first line)
+  - In strict runner versions: fails with "Error: Failed to parse environment file"
+
+  **Common incorrect pattern:**
+  ```yaml
+  run: echo "MY_CERT=${{ secrets.CERT }}" >> $GITHUB_ENV
+  # If CERT contains newlines, the env file entry is broken
+  ```
+
+  **Why it's a silent failure:**
+  - The step succeeds with exit code 0
+  - No obvious error message appears in the logs
+  - Downstream steps see a truncated, incomplete variable value
+  - Certificate/JSON/SSH key values are commonly multi-line and hit this silently
+
+  This is separate from the `$GITHUB_OUTPUT` multiline issue (which uses the same
+  heredoc syntax fix) — the root cause and pattern are identical but the environment
+  file (`GITHUB_ENV`) is a distinct file from the output file (`GITHUB_OUTPUT`).
+
+  Sources: GitHub Community #160171, GitHub Docs workflow commands
+fix: |
+  Use the **heredoc delimiter format** for multiline values in `$GITHUB_ENV`:
+
+  ```
+  KEY<<DELIMITER
+  value-line-1
+  value-line-2
+  DELIMITER
+  ```
+
+  The delimiter can be any string that does not appear in the value. `EOF` is the
+  conventional choice. The delimiter must appear on its own line both as the opening
+  marker and the closing marker.
+
+  This same pattern applies to `$GITHUB_OUTPUT` for multiline step outputs.
+fix_code:
+  - language: yaml
+    label: "Broken — newline in value breaks the env file silently"
+    code: |
+      # ❌ BROKEN: Secret or cert value with newlines truncates silently
+      - name: Set multiline env var
+        run: echo "MY_CERT=${{ secrets.TLS_CERT }}" >> $GITHUB_ENV
+        # Result: MY_CERT contains only the first line of the certificate
+  - language: yaml
+    label: "Fixed — heredoc delimiter format for multiline GITHUB_ENV values"
+    code: |
+      # ✅ FIXED: Use heredoc delimiter syntax
+      - name: Set multiline env var
+        run: |
+          echo "MY_CERT<<EOF" >> $GITHUB_ENV
+          echo "${{ secrets.TLS_CERT }}" >> $GITHUB_ENV
+          echo "EOF" >> $GITHUB_ENV
+  - language: yaml
+    label: "Fixed — multiline JSON body in GITHUB_ENV"
+    code: |
+      # ✅ FIXED: Multi-line JSON stored as env var using heredoc format
+      - name: Set JSON config variable
+        run: |
+          echo "APP_CONFIG<<EOF" >> $GITHUB_ENV
+          cat config/settings.json >> $GITHUB_ENV
+          echo "EOF" >> $GITHUB_ENV
+  - language: yaml
+    label: "Fixed — same pattern applies to GITHUB_OUTPUT for multiline outputs"
+    code: |
+      # ✅ SAME PATTERN for step outputs (GITHUB_OUTPUT)
+      - name: Set multiline output
+        id: generate
+        run: |
+          echo "report<<EOF" >> $GITHUB_OUTPUT
+          cat test-results.txt >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
+  - language: yaml
+    label: "Fixed — PowerShell equivalent for Windows runners"
+    code: |
+      # ✅ FIXED (Windows/PowerShell): Use Out-File -Append with heredoc-style writes
+      - name: Set multiline env var on Windows
+        shell: pwsh
+        run: |
+          @"
+          MY_CERT<<EOF
+          ${{ secrets.TLS_CERT }}
+          EOF
+          "@ | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
+prevention:
+  - "Always use the `KEY<<DELIMITER ... DELIMITER` heredoc format for any env var value that may contain newlines (certs, JWTs, JSON, SSH keys)."
+  - "Never use a single `echo KEY=VALUE >> $GITHUB_ENV` for values sourced from secrets or file contents — they are likely to contain newlines."
+  - "The same heredoc pattern applies to `$GITHUB_OUTPUT` — treat them identically for multiline values."
+  - "Validate that downstream steps receive the full value: `run: echo \"MY_CERT=$MY_CERT\"` — a truncated cert will be obviously short."
+  - "Use `echo 'key<<EOF' >> $GITHUB_ENV` (single quotes around key<<EOF) to avoid accidental shell expansion of the delimiter line."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#multiline-strings"
+    label: "GitHub Docs: Workflow commands — Multiline strings in environment files"
+  - url: "https://github.com/orgs/community/discussions/160171"
+    label: "GitHub Community #160171 — GITHUB_ENV multiline values"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#setting-an-environment-variable"
+    label: "GitHub Docs: Setting an environment variable (GITHUB_ENV format)"

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"