@htekdev/actions-debugger 1.0.13 → 1.0.15

package/errors/silent-failures/app-store-ios26-sdk-required.yml

@@ -0,0 +1,113 @@
+id: silent-failures-017
+title: "iOS App Store Upload Fails Silently — macOS-latest Uses Xcode 16.4 but Apple Requires iOS 26 SDK"
+category: silent-failures
+severity: silent-failure
+tags:
+  - macos
+  - xcode
+  - ios
+  - app-store
+  - sdk
+  - silent-failure
+  - apple
+patterns:
+  - regex: "built with the iOS (?:18|17|16)\\.\\d SDK"
+    flags: "i"
+  - regex: "must be built with the iOS 26 SDK or later.*App Store"
+    flags: "i"
+  - regex: "Invalid Toolchain.*iOS.*SDK.*required"
+    flags: "i"
+  - regex: "ITMS-90725|ITMS-90206"
+    flags: "i"
+error_messages:
+  - "This app was built with the iOS 18.5 SDK. All iOS and iPadOS apps must be built with the iOS 26 SDK or later in order to be uploaded to App Store Connect."
+  - "ERROR ITMS-90725: SDK Version Issue - This app was built with the iOS 18.5 SDK"
+  - "Invalid Toolchain. New apps and app updates must be built with the public iOS 26 SDK or later"
+root_cause: |
+  Apple requires that all new iOS/iPadOS App Store submissions be built with the
+  iOS 26 SDK or later (enforced starting mid-2026). However, `macos-latest` currently
+  points to macOS 15 (until the macOS 26 migration completes in July 2026), and
+  macOS 15 runner images ship with Xcode 16.4 as the default — which includes the
+  iOS 18.5 SDK, NOT the iOS 26 SDK.
+
+  The failure is a classic silent-failure pattern:
+  - The build step SUCCEEDS with zero errors or warnings.
+  - The archive step SUCCEEDS.
+  - The upload/export to App Store Connect FAILS with the SDK version error.
+  - Because the failure occurs at the distribution stage (not compilation), it
+    can be misdiagnosed as a signing, provisioning, or network issue.
+
+  Workflows that use `uses: maxim-lobanov/setup-xcode` with an explicit 16.x version,
+  or that rely on `macos-latest` defaults without explicit Xcode pinning, will
+  silently produce an .ipa or .xcarchive that cannot be submitted to App Store Connect.
+
+  After the `macos-latest` migration to macOS 26 completes (July 15, 2026), the default
+  Xcode will be 26.4.1+, which includes the iOS 26 SDK and resolves this issue.
+  Until then, explicit Xcode pinning is required.
+
+  Source: actions/runner-images#14165
+fix: |
+  **Immediate fix**: Pin Xcode to 26.x explicitly using `maxim-lobanov/setup-xcode`
+  before any build or archive steps. Use `macos-26` as the runner to ensure Xcode 26
+  is available.
+
+  **For teams not ready to migrate to Xcode 26**: Use `macos-26` and pin to Xcode 26.4.1
+  or later — this is required by Apple regardless of code changes.
+
+  **Verify the SDK in use** by adding `xcodebuild -showsdks` before the build step.
+fix_code:
+  - language: yaml
+    label: "Pin to macOS 26 + Xcode 26 for App Store submissions"
+    code: |
+      jobs:
+        release:
+          runs-on: macos-26   # Explicit: don't rely on macos-latest during transition
+          steps:
+            - uses: actions/checkout@v4
+
+            # Explicitly select Xcode 26 (includes iOS 26 SDK required by App Store)
+            - uses: maxim-lobanov/setup-xcode@v1
+              with:
+                xcode-version: '26.4'   # or '26.5' once generally available
+
+            - name: Verify SDK
+              run: xcodebuild -showsdks | grep -i iphoneos
+
+            - name: Archive
+              run: |
+                xcodebuild archive \
+                  -scheme MyApp \
+                  -archivePath $RUNNER_TEMP/MyApp.xcarchive \
+                  -destination generic/platform=iOS
+
+            - name: Export for App Store
+              run: |
+                xcodebuild -exportArchive \
+                  -archivePath $RUNNER_TEMP/MyApp.xcarchive \
+                  -exportOptionsPlist ExportOptions.plist \
+                  -exportPath $RUNNER_TEMP/MyApp.ipa
+  - language: yaml
+    label: "Check installed Xcode versions and default SDK (diagnosis)"
+    code: |
+      - name: Diagnose Xcode and SDK versions
+        run: |
+          echo "=== Default Xcode ==="
+          xcode-select -p
+          xcodebuild -version
+          echo "=== Available SDKs ==="
+          xcodebuild -showsdks | grep -i iphone
+prevention:
+  - "Never rely on `macos-latest` default Xcode for App Store release builds — always pin the Xcode version explicitly."
+  - "Use `xcodebuild -showsdks` as an early workflow step to emit the active iOS SDK version to logs."
+  - "Run a smoke test of the App Store export (not just the build) in CI to catch SDK requirement errors before manual submission."
+  - "Subscribe to Apple Developer news for SDK requirement enforcement dates and plan runner image migrations in advance."
+  - "Pin `runs-on: macos-26` explicitly rather than `macos-latest` for release workflows during the macOS version transition period."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/14165"
+    label: "runner-images#14165 — macOS-latest Xcode 16.4 breaks App Store submissions"
+  - url: "https://github.com/actions/runner-images/issues/14167"
+    label: "runner-images#14167 — macos-latest will use macos-26 in June 2026"
+  - url: "https://github.com/maxim-lobanov/setup-xcode"
+    label: "maxim-lobanov/setup-xcode — Pin Xcode version in workflows"
+  - url: "https://developer.apple.com/news/releases/"
+    label: "Apple Developer News — SDK requirement announcements"

package/errors/silent-failures/event-commits-empty-on-workflow-dispatch.yml

@@ -0,0 +1,110 @@
+id: silent-failures-018
+title: "github.event.commits and github.event.head_commit Are Null/Empty on Non-Push Triggers"
+category: silent-failures
+severity: silent-failure
+tags:
+  - github-context
+  - workflow-dispatch
+  - schedule
+  - commits
+  - null-access
+  - push-event
+  - expression
+patterns:
+  - regex: "github\\.event\\.commits\\[0\\]"
+    flags: "i"
+  - regex: "github\\.event\\.head_commit\\.(message|id|author)"
+    flags: "i"
+  - regex: "github\\.event\\.commits is not iterable|Cannot read.*commits"
+    flags: "i"
+error_messages:
+  - "Error: Cannot read properties of undefined (reading 'message')"
+  - "Error: github.event.commits[0] is undefined"
+root_cause: |
+  The `github.event.commits` array and `github.event.head_commit` object are ONLY populated
+  for `push` webhook events. They are absent (null / empty array) for all other trigger types:
+
+  - `workflow_dispatch` — manual UI or API trigger, no commit context
+  - `schedule` — cron-triggered run, no specific push associated
+  - `pull_request` / `pull_request_target` — uses github.event.pull_request instead
+  - `workflow_call` — reusable workflow invocation, no commit array
+  - `repository_dispatch` — uses github.event.client_payload, no commits key
+  - `release` — uses github.event.release, no commits array
+
+  When a workflow is triggered on both `push` and `workflow_dispatch` (a common pattern),
+  expressions like:
+    ${{ github.event.commits[0].message }}
+    ${{ github.event.head_commit.id }}
+
+  silently evaluate to empty string ('') on non-push triggers rather than raising an error.
+  GitHub Actions treats missing context properties as empty string, so the step runs but
+  with blank or wrong data — the workflow shows green while producing incorrect output.
+
+  This is a silent failure because there is no error in the logs when the empty string is
+  used in a step (e.g., an echo, a tag, a release title). The problem only becomes visible
+  when the downstream artifact or message is inspected.
+fix: |
+  Use git directly to extract commit information — it works reliably across all trigger types
+  (as long as fetch-depth is not 1 / uses default full clone or depth >= 2):
+
+    git log --format=%s -1      # subject line
+    git log --format=%H -1      # full SHA
+    git log --format=%ae -1     # author email
+
+  Alternatively, guard commit-context access with an event_name check, or use the
+  github.sha context (which IS available on all triggers) when a commit SHA is needed.
+fix_code:
+  - language: yaml
+    label: "Portable commit message extraction via git (works on all triggers)"
+    code: |
+      jobs:
+        release:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                fetch-depth: 2  # depth >= 2 required for git log on non-push
+
+            - name: Get commit message (safe for push, workflow_dispatch, schedule)
+              id: meta
+              run: |
+                echo "sha=${{ github.sha }}" >> $GITHUB_OUTPUT
+                echo "message=$(git log --format=%s -1 ${{ github.sha }})" >> $GITHUB_OUTPUT
+                echo "author=$(git log --format=%ae -1 ${{ github.sha }})" >> $GITHUB_OUTPUT
+
+            - name: Use commit metadata
+              run: |
+                echo "SHA: ${{ steps.meta.outputs.sha }}"
+                echo "Message: ${{ steps.meta.outputs.message }}"
+  - language: yaml
+    label: "Guard push-only context with event_name check"
+    code: |
+      - name: Get commit message (push only)
+        if: github.event_name == 'push' && github.event.commits[0] != null
+        run: |
+          echo "COMMIT_MSG=${{ github.event.commits[0].message }}" >> $GITHUB_ENV
+
+      - name: Fallback for non-push triggers
+        if: github.event_name != 'push'
+        run: |
+          echo "COMMIT_MSG=$(git log --format=%s -1)" >> $GITHUB_ENV
+  - language: yaml
+    label: "Debug: dump full event payload to understand what is available"
+    code: |
+      - name: Debug — dump event context
+        run: echo '${{ toJSON(github.event) }}'
+prevention:
+  - "Never access github.event.commits or github.event.head_commit without first checking github.event_name == 'push'."
+  - "Use `git log --format=%s -1 ${{ github.sha }}` for commit message extraction — it works on all trigger types."
+  - "Note that github.sha IS available on all triggers and points to the relevant commit; use it as a portable substitute for github.event.head_commit.id."
+  - "Add a debug step early in development to dump `${{ toJSON(github.event) }}` so you can see exactly what context is available for each trigger type."
+  - "Test workflows by triggering them manually via workflow_dispatch to catch push-only context assumptions before they hit production."
+docs:
+  - url: "https://docs.github.com/en/webhooks/webhook-events-and-payloads#push"
+    label: "GitHub docs — push event payload (includes commits array)"
+  - url: "https://docs.github.com/en/webhooks/webhook-events-and-payloads#workflow_dispatch"
+    label: "GitHub docs — workflow_dispatch event payload (no commits array)"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/accessing-contextual-information-about-workflow-runs#github-context"
+    label: "GitHub docs — github context reference"
+  - url: "https://github.com/orgs/community/discussions/27058"
+    label: "Community discussion — github.event.commits undefined on workflow_dispatch"

package/errors/silent-failures/fetch-tags-depth-one-silent-no-op.yml

@@ -0,0 +1,77 @@
+id: silent-failures-022
+title: "fetch-tags: true Silently Fetches No Tags When fetch-depth Is 1"
+category: silent-failures
+severity: silent-failure
+tags:
+  - checkout
+  - fetch-tags
+  - shallow-clone
+  - fetch-depth
+  - git-tags
+  - versioning
+patterns:
+  - regex: "No tags found|no tags found"
+    flags: "i"
+  - regex: "fatal: No names found, cannot describe anything"
+    flags: "i"
+  - regex: "CHANGELOG.*No tag found"
+    flags: "i"
+error_messages:
+  - "fatal: No names found, cannot describe anything"
+  - "No tags found. Try unshallowing the repository"
+  - "CHANGELOG ERROR: No tag found on HEAD"
+  - "Error: No tags matching '*' found, exiting"
+root_cause: |
+  The `fetch-tags: true` option in `actions/checkout` was introduced in v3.6.0 to restore tag
+  fetching after `--no-tags` was made the default for shallow clones. However, when `fetch-depth`
+  remains at its default value of `1` (shallow clone), the tag fetch silently produces no results.
+
+  With a shallow clone, git only downloads a single commit. Tags are only present if they point
+  directly to that one commit — i.e., the workflow was triggered by a tag push. In all other
+  cases, `fetch-tags: true` appears to succeed (no error, no warning) but `git tag -l` returns
+  empty results.
+
+  This silently breaks tools that depend on git tags for versioning: semantic-release,
+  commitizen, standard-version, cargo-smart-release, setuptools-scm, and any script using
+  `git describe --tags`. Builds succeed but produce wrong version numbers (often 0.0.0 or
+  commit-hash-only versions).
+fix: |
+  Pair `fetch-tags: true` with `fetch-depth: 0` to fetch the full history including all tags.
+  On very large repositories, use `filter: tree:0` for a blobless partial clone that still
+  includes complete tag history. As a targeted workaround, add a second step to fetch only
+  tags after a shallow checkout.
+fix_code:
+  - language: yaml
+    label: "Recommended: full history with all tags"
+    code: |
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0     # full history required for tags
+          fetch-tags: true   # fetch all tags
+  - language: yaml
+    label: "Large repos: blobless filter (faster, still includes tags)"
+    code: |
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          filter: tree:0     # blobless clone — avoids downloading file blobs
+          fetch-tags: true
+  - language: yaml
+    label: "Workaround: shallow checkout + separate tag fetch step"
+    code: |
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+      - name: Fetch all tags
+        run: git fetch --prune --unshallow --tags
+prevention:
+  - "Always pair `fetch-tags: true` with `fetch-depth: 0` unless the workflow is only triggered by tag pushes"
+  - "Add `git tag -l` as a debug step in release workflows to verify tags are present after checkout"
+  - "If using semantic-release or similar, test your version script locally with a shallow clone to catch this early"
+docs:
+  - url: "https://github.com/actions/checkout/issues/1471"
+    label: "actions/checkout#1471 — fetch-tags: true doesn't actually fetch any tags (126 reactions)"
+  - url: "https://github.com/actions/checkout/issues/1467"
+    label: "actions/checkout#1467 — related: no-tags default behavior"
+  - url: "https://github.com/actions/checkout#usage"
+    label: "actions/checkout — fetch-tags and fetch-depth inputs documentation"

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"