@htekdev/actions-debugger 1.0.36 → 1.0.38

package/errors/runner-environment/macos-latest-macos-15-xcode16-sdk-mismatch.yml

@@ -0,0 +1,84 @@
+id: runner-environment-095
+title: macos-latest Points to macOS 15 — Xcode 16 Default Breaks Hardcoded SDK References
+category: runner-environment
+severity: error
+tags:
+  - macos-latest
+  - macos-15
+  - xcode-16
+  - runner-migration
+  - apple-silicon
+patterns:
+  - regex: 'SDK ''macosx14\.\d+'' cannot be located'
+    flags: i
+  - regex: 'SDKROOT.*macosx14'
+    flags: i
+  - regex: 'built for macOS 14.*linking for macOS 15'
+    flags: i
+  - regex: 'xcodebuild: error:.*SDK ''macosx14'
+    flags: i
+error_messages:
+  - "error: SDK 'macosx14.5' cannot be located"
+  - "xcodebuild: error: The requested SDK 'macosx14.5' cannot be found."
+  - "ld: warning: ignoring file ...: built for macOS 14, but linking for macOS 15"
+root_cause: |
+  GitHub updated macos-latest to point to macOS 15 (Sequoia) on Apple Silicon
+  (M1) runners in January 2025 (GitHub Changelog 2025-01-16). The macOS 15 runner
+  image ships with Xcode 16 as the default toolchain.
+
+  Workflows and Xcode project files that hardcode `SDKROOT=macosx14.5` or
+  `MACOSX_DEPLOYMENT_TARGET=14` fail because the macOS 14 SDK is not bundled
+  with Xcode 16 by default. Common failure modes:
+
+  - Hardcoded SDK version strings in .xcconfig files
+  - Xcode project targets specifying a minimum macOS deployment target of 14.x
+    that resolve against the now-absent SDK
+  - Homebrew formulae and pre-installed tool versions changed on macOS 15,
+    breaking workflows that assumed specific tool paths or versions
+  - The pre-installed Ruby version changed, breaking Fastlane and CocoaPods
+    workflows that did not pin a Ruby version
+fix: |
+  Option 1: Pin the runner to `macos-14` explicitly to continue using Xcode 15
+  and the macOS 14 SDK until you are ready to migrate.
+
+  Option 2: Use the `maxim-lobanov/setup-xcode` action to pin a specific Xcode
+  version on macos-latest, keeping the runner current while controlling toolchain.
+
+  Option 3: Update Xcode project settings to remove hardcoded SDK version strings.
+  Use `$(SDKROOT)` relative targets and set `MACOSX_DEPLOYMENT_TARGET` to a value
+  supported by Xcode 16.
+
+  For Ruby-dependent workflows (Fastlane, CocoaPods), use `ruby/setup-ruby` with
+  an explicit version rather than relying on the system Ruby.
+fix_code:
+  - language: yaml
+    label: Pin explicit macOS version to avoid macos-latest drift
+    code: |
+      jobs:
+        build:
+          runs-on: macos-14  # explicit; Xcode 15 + macOS 14 SDK
+
+  - language: yaml
+    label: Pin Xcode version on macos-latest
+    code: |
+      - uses: maxim-lobanov/setup-xcode@v1
+        with:
+          xcode-version: '15.4'
+
+  - language: yaml
+    label: Use ruby/setup-ruby for Fastlane and CocoaPods workflows
+    code: |
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+          bundler-cache: true
+prevention:
+  - "Pin explicit runner OS versions (macos-14, macos-15) instead of macos-latest for stable CI builds"
+  - "Never hardcode SDK version strings (macosx14.x) in Xcode project .xcconfig files — use $(SDKROOT)"
+  - "Use ruby/setup-ruby, actions/setup-python, and similar version-pinning actions for all language runtimes"
+  - "Subscribe to GitHub Changelog and runner-images repository releases for macOS image update notices"
+docs:
+  - url: https://github.blog/changelog/2025-01-16-github-actions-macos-15-is-now-the-latest-macos-runner-image/
+    label: "GitHub Changelog: macOS 15 becomes macos-latest (Jan 2025)"
+  - url: https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners
+    label: "GitHub-hosted runner images documentation"

package/errors/runner-environment/multi-platform-docker-build-missing-qemu.yml

@@ -0,0 +1,84 @@
+id: runner-environment-092
+title: "Multi-platform Docker Build Fails — Missing QEMU Setup for Cross-Architecture"
+category: runner-environment
+severity: error
+tags:
+  - docker
+  - multi-platform
+  - qemu
+  - buildx
+  - arm64
+  - cross-arch
+patterns:
+  - regex: 'failed to solve: no match for platform in manifest'
+    flags: "i"
+  - regex: 'no match for platform in manifest: linux/(arm64|arm/v[67]|riscv64|ppc64le|s390x)'
+    flags: "i"
+  - regex: 'exec format error'
+    flags: "i"
+error_messages:
+  - "ERROR: failed to solve: no match for platform in manifest: linux/arm64"
+  - "failed to solve: no match for platform in manifest: linux/arm64"
+  - "exec format error"
+  - "cannot execute binary file: Exec format error"
+root_cause: |
+  GitHub-hosted runners (ubuntu-*, macos-*, windows-*) are single-architecture machines.
+  When docker/build-push-action is configured with platforms: linux/amd64,linux/arm64 (or
+  any other non-native architecture), Docker BuildKit needs QEMU user-mode emulation to
+  execute non-native binaries during the build. Without docker/setup-qemu-action registered
+  first, BuildKit cannot emulate the target architecture and immediately fails with "no match
+  for platform in manifest" or exec format errors when a RUN instruction in the Dockerfile
+  executes a binary compiled for the wrong architecture.
+
+  This is a common mistake when adding multi-arch support to an existing single-arch workflow.
+  The amd64 platform succeeds while arm64 fails, producing confusing partial-success output.
+  Self-hosted ARM64 runners (e.g. macos-14/15, ubuntu ARM) can build their native arch without
+  QEMU but still need it for other non-native targets.
+fix: |
+  Add docker/setup-qemu-action before docker/setup-buildx-action in your workflow steps.
+  QEMU must be installed before buildx initializes so BuildKit discovers the emulators at
+  setup time. Order matters — QEMU before buildx, buildx before build-push-action.
+fix_code:
+  - language: yaml
+    label: "WRONG — buildx without QEMU (arm64 fails)"
+    code: |
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          platforms: linux/amd64,linux/arm64  # arm64 fails without QEMU
+          push: true
+          tags: myimage:latest
+  - language: yaml
+    label: "RIGHT — QEMU registered before buildx"
+    code: |
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: myimage:latest
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+prevention:
+  - "Always add docker/setup-qemu-action before docker/setup-buildx-action when targeting non-native platforms."
+  - "Verify QEMU platform list covers your targets: linux/arm64, linux/arm/v7, linux/arm/v6, linux/riscv64, linux/ppc64le, linux/s390x."
+  - "Use a platform matrix to build and test each architecture independently for faster CI feedback loops."
+  - "Check runner architecture with 'uname -m' in a run step when debugging platform mismatches."
+docs:
+  - url: "https://github.com/docker/setup-qemu-action"
+    label: "docker/setup-qemu-action — GitHub Action"
+  - url: "https://docs.docker.com/build/building/multi-platform/"
+    label: "Docker — Multi-platform builds"
+  - url: "https://github.com/docker/build-push-action/blob/master/docs/advanced/multi-platform.md"
+    label: "docker/build-push-action — Multi-platform builds guide"
+  - url: "https://stackoverflow.com/questions/69984898/github-action-multi-arch-docker-build-failed-to-solve-no-match-for-platform-in"
+    label: "Stack Overflow — Multi-arch Docker build: no match for platform in manifest (400+ votes)"

package/errors/runner-environment/node16-actions-runtime-deprecated-disabled.yml

@@ -0,0 +1,87 @@
+id: runner-environment-094
+title: Node.js 16 Actions Runtime Deprecated and Disabled — Actions Using node16 Fail
+category: runner-environment
+severity: error
+tags:
+  - node16
+  - node20
+  - action-runtime
+  - deprecation
+  - runs-using
+patterns:
+  - regex: 'Node\.js 16 actions are deprecated'
+    flags: i
+  - regex: 'Please update the following actions to use Node\.js 20'
+    flags: i
+  - regex: 'uses a deprecated version of `actions/node`'
+    flags: i
+error_messages:
+  - "Node.js 16 actions are deprecated. Please update the following actions to use Node.js 20: actions/checkout@v3"
+  - "Warning: Node.js 16 is End-of-Life. Upgrade to Node.js 20 or later."
+  - "Error: This request has been automatically failed because it uses a deprecated version of `actions/node`"
+root_cause: |
+  Node.js 16 reached end-of-life on September 11, 2023. GitHub announced on
+  September 22, 2023 (GitHub Changelog) that it would deprecate the Node.js 16
+  runtime for GitHub Actions, with a hard enforcement cutoff on September 22, 2024.
+
+  Actions authored with `runs.using: node16` in their action.yml emit deprecation
+  warnings from late 2023 onward. From September 2024, these actions produce hard
+  errors and may not execute. Third-party actions pinned to older major versions
+  that internally use node16 are affected, including actions/checkout@v3,
+  actions/setup-node@v3, actions/cache@v3, and many community actions. Composite
+  actions that transitively call a node16-based action also fail.
+fix: |
+  Update all action references in your workflows to major versions that use the
+  node20 (or node22) runtime. Common upgrades needed:
+  - actions/checkout@v3      → @v4
+  - actions/setup-node@v3    → @v4
+  - actions/cache@v3         → @v4
+  - actions/upload-artifact@v3 → @v4
+  - actions/download-artifact@v3 → @v4
+
+  For custom actions you own, update `runs.using` in action.yml from
+  `node16` to `node20`.
+
+  Use Dependabot or Renovate with the `github-actions` package ecosystem to
+  keep action versions current automatically.
+fix_code:
+  - language: yaml
+    label: Update official actions from node16 to node20-based versions
+    code: |
+      - uses: actions/checkout@v4           # was @v3 (node16)
+      - uses: actions/setup-node@v4         # was @v3 (node16)
+        with:
+          node-version: '20'
+      - uses: actions/cache@v4              # was @v3 (node16)
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
+
+  - language: yaml
+    label: Update custom action.yml to node20 runtime
+    code: |
+      # In your action's action.yml
+      runs:
+        using: node20
+        main: dist/index.js
+
+  - language: yaml
+    label: Enable Dependabot for github-actions ecosystem
+    code: |
+      # .github/dependabot.yml
+      version: 2
+      updates:
+        - package-ecosystem: github-actions
+          directory: /
+          schedule:
+            interval: weekly
+prevention:
+  - "Enable Dependabot for the github-actions package ecosystem to receive automatic PRs for action version updates"
+  - "Audit all action.yml files in custom actions for runs.using: node16 before the hard cutoff"
+  - "Watch the actions/* repositories on GitHub for major version releases that upgrade the runtime"
+  - "Prefer Dependabot or Renovate over manually pinned major versions to stay ahead of deprecations"
+docs:
+  - url: https://github.blog/changelog/2023-09-22-github-actions-transitioning-from-node-16-to-node-20/
+    label: "GitHub Changelog: Transitioning from Node.js 16 to Node.js 20 (Sep 2023)"
+  - url: https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions#runs-for-javascript-actions
+    label: "Actions metadata syntax: runs.using"

package/errors/runner-environment/ubuntu-latest-ubuntu-24-python2-package-removal.yml

@@ -0,0 +1,75 @@
+id: runner-environment-093
+title: ubuntu-latest Now Points to Ubuntu 24.04 — Python 2 and Legacy Packages Removed
+category: runner-environment
+severity: error
+tags:
+  - ubuntu-latest
+  - ubuntu-24-04
+  - python2
+  - apt-get
+  - runner-migration
+patterns:
+  - regex: 'E: Package ''python'' has no installation candidate'
+    flags: i
+  - regex: 'python: command not found'
+    flags: i
+  - regex: 'Unable to locate package python2'
+    flags: i
+  - regex: 'E: Package ''libssl1\.1'' has no installation candidate'
+    flags: i
+error_messages:
+  - "E: Package 'python' has no installation candidate"
+  - "python: command not found"
+  - "Unable to locate package python2"
+  - "E: Package 'libssl1.1' has no installation candidate"
+root_cause: |
+  GitHub changed ubuntu-latest to point to Ubuntu 24.04 on November 7, 2024
+  (announced via GitHub Changelog on September 25, 2024). Ubuntu 24.04 (Noble
+  Numbat) removes several packages that were present on Ubuntu 20.04 and 22.04:
+
+  - The `python` package (Python 2.7) is entirely absent; only `python3` is available
+  - `python2` and `python-is-python2` are not installable via apt
+  - `libssl1.1` (OpenSSL 1.1.x) is removed; only OpenSSL 3.x ships with 24.04
+  - Various other legacy apt packages dropped in the 24.04 LTS release
+
+  Workflows that ran `sudo apt-get install python`, invoked `python script.py`
+  (instead of `python3`), or installed packages transitively depending on
+  libssl1.1 started failing immediately after the image switch.
+fix: |
+  Option 1: Replace all `python` calls with `python3` and use `actions/setup-python`
+  to install a specific Python 3 version rather than relying on the system default.
+
+  Option 2: Pin the runner to `ubuntu-22.04` explicitly if Python 2 is genuinely
+  required or if you need time to migrate. Note that ubuntu-22.04 will eventually
+  be retired from the GitHub-hosted runner fleet.
+
+  Audit all `apt-get install` steps for packages removed in Ubuntu 24.04, including
+  libssl1.1, python2, python-is-python2, libffi7, and others listed in the Ubuntu
+  24.04 release notes.
+fix_code:
+  - language: yaml
+    label: Use actions/setup-python and replace python with python3
+    code: |
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Run script
+        run: python3 script.py
+
+  - language: yaml
+    label: Pin explicit runner version to avoid ubuntu-latest drift
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-22.04  # explicit version; do not rely on ubuntu-latest
+prevention:
+  - "Pin explicit runner versions (ubuntu-22.04, ubuntu-24.04) instead of ubuntu-latest to prevent surprise image changes"
+  - "Use actions/setup-python for all Python installs rather than apt-get"
+  - "Replace python with python3 in all shell commands and scripts"
+  - "Subscribe to GitHub Changelog for runner image update announcements before they take effect"
+docs:
+  - url: https://github.blog/changelog/2024-09-25-actions-new-images-and-ubuntu-latest-changes/
+    label: "GitHub Changelog: ubuntu-latest points to Ubuntu 24.04 (Sep 2024)"
+  - url: https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners
+    label: "GitHub-hosted runner images documentation"

package/errors/silent-failures/fork-pr-secrets-empty-string-steps-silently-skipped.yml

@@ -0,0 +1,97 @@
+id: silent-failures-042
+title: Fork pull_request Secrets Are Empty Strings — Secret-Gated Steps Silently Skip
+category: silent-failures
+severity: silent-failure
+tags:
+  - fork
+  - pull-request
+  - secrets
+  - empty-string
+  - conditional-step
+patterns:
+  - regex: 'secrets\.[A-Z_]+ != ''''.*if.*condition'
+    flags: i
+  - regex: 'npm ERR! code E401'
+    flags: ''
+  - regex: 'Error: HttpError: Resource not accessible by integration'
+    flags: i
+error_messages:
+  - "npm ERR! code E401"
+  - "Error: HttpError: Resource not accessible by integration"
+  - "(No log output — the step shows 'skipped' status when secrets.MY_TOKEN != '' evaluates false on fork PRs)"
+root_cause: |
+  When a pull_request event is triggered from a fork, GitHub Actions intentionally
+  provides empty strings ("") for all secrets in the `secrets` context — not null,
+  but empty string. This is a security measure to prevent secret exfiltration from
+  untrusted fork code running in the base repository's context.
+
+  The silent-failure pattern occurs when a workflow guards a step with a secrets
+  check:
+
+    - if: ${{ secrets.NPM_TOKEN != '' }}
+      run: npm publish
+
+  On fork PRs, `secrets.NPM_TOKEN` is `""`, so the condition evaluates to `false`
+  and the step is silently skipped with no error, no warning, and no indication
+  in normal logs. Developers expecting either a published artifact or a clear
+  failure instead see a green workflow with a quietly skipped deploy step.
+
+  A related failure mode: when the empty secret IS used directly (without a guard),
+  the downstream tool emits a generic auth error (E401, 403) that gives no indication
+  the root cause is an empty secret from a fork trigger.
+fix: |
+  Separate concerns: run untrusted fork code in a `pull_request` workflow (no
+  secrets needed), then gate secret-requiring operations on a `workflow_run`
+  workflow that triggers after the pull_request workflow completes. The
+  workflow_run event runs in the base branch context and has full access to
+  repository secrets.
+
+  If you must use secrets in a `pull_request` workflow (e.g., to post PR comments
+  via GITHUB_TOKEN), rely on the automatically-provided GITHUB_TOKEN with
+  appropriate `permissions:` — do not depend on user-defined secrets in
+  pull_request context from forks.
+
+  Avoid the `if: ${{ secrets.MY_SECRET != '' }}` guard pattern entirely;
+  document the fork limitation explicitly in the workflow file instead.
+fix_code:
+  - language: yaml
+    label: "Split pattern: pull_request for tests (no secrets), workflow_run for deploys"
+    code: |
+      # pr-tests.yml — runs untrusted fork code, no secrets needed
+      on: pull_request
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm ci && npm test
+
+  - language: yaml
+    label: workflow_run continuation with secrets (runs in base branch context)
+    code: |
+      # pr-deploy.yml — triggers after pr-tests completes; has full secret access
+      on:
+        workflow_run:
+          workflows: [PR Tests]
+          types: [completed]
+      jobs:
+        publish:
+          if: ${{ github.event.workflow_run.conclusion == 'success' }}
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm publish
+              env:
+                NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+prevention:
+  - "Never write if: ${{ secrets.MY_SECRET != '' }} as a fork guard — this silently evaluates false on all fork PRs"
+  - "Use the pull_request + workflow_run split pattern for any workflow needing both fork code and repository secrets"
+  - "Add a comment in your workflow file explaining that secret-gated steps intentionally skip on fork PRs"
+  - "Use GITHUB_TOKEN with explicit permissions: blocks for operations that only require base repository access"
+docs:
+  - url: https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions#using-secrets
+    label: "GitHub Docs: Security hardening for GitHub Actions — using secrets"
+  - url: https://securitylab.github.com/resources/github-actions-preventing-pwn-requests/
+    label: "GitHub Security Lab: Preventing pwn requests (pull_request_target risks)"
+  - url: https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_run
+    label: "GitHub Docs: workflow_run event"

package/errors/silent-failures/github-sha-pr-merge-commit-status-invisible.yml

@@ -0,0 +1,95 @@
+id: silent-failures-041
+title: "`github.sha` Is the Merge Commit on Pull Request Events — Commit Status Invisible"
+category: silent-failures
+severity: silent-failure
+tags:
+  - github.sha
+  - pull_request
+  - commit-status
+  - merge-commit
+  - sha
+  - statuses
+patterns:
+  - regex: 'github\.sha'
+    flags: "i"
+  - regex: 'pull_request\.head\.sha'
+    flags: "i"
+error_messages:
+  - "No error — commit status silently attached to ephemeral merge commit not visible in PR timeline"
+  - "No pending/passing status appears on the PR despite successful workflow run"
+root_cause: |
+  On pull_request and pull_request_target events, github.sha is set to the SHA of a temporary
+  merge commit GitHub creates to test mergeability (refs/pull/<n>/merge), NOT the actual head
+  commit of the feature branch (refs/pull/<n>/head). This merge commit is ephemeral and is
+  never directly visible in the PR timeline or commit history.
+
+  Developers who pass github.sha to the GitHub Commit Status API (POST
+  /repos/{owner}/{repo}/statuses/{sha}), build provenance attestation tools, cosign, or other
+  tooling expecting the PR head commit get a silent mismatch: the API call succeeds with HTTP
+  201, the status is written, but it targets a commit no reviewer can see. The PR status checks
+  panel remains empty or stale, required checks are never satisfied, and the PR cannot be merged
+  even though the workflow ran successfully.
+
+  This is distinct from the checkout/ref problem where the wrong code is built — here the build
+  is correct but status reporting is silently targeting the wrong commit.
+fix: |
+  Use github.event.pull_request.head.sha instead of github.sha when targeting the PR head
+  commit for status APIs or attestation. For non-PR events (push, workflow_dispatch,
+  schedule), github.sha is correct. Use a combined expression for reusable workflows that
+  run on both event types.
+fix_code:
+  - language: yaml
+    label: "WRONG — status set on merge commit (never shows on PR)"
+    code: |
+      - name: Set commit status
+        uses: actions/github-script@v7
+        with:
+          script: |
+            await github.rest.repos.createCommitStatus({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              sha: context.sha,  // merge commit SHA on pull_request events
+              state: 'success',
+              context: 'my-check',
+            });
+  - language: yaml
+    label: "RIGHT — use PR head SHA for pull_request events"
+    code: |
+      - name: Set commit status
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const sha = context.eventName === 'pull_request'
+              ? context.payload.pull_request.head.sha  // actual PR head commit
+              : context.sha;
+            await github.rest.repos.createCommitStatus({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              sha,
+              state: 'success',
+              context: 'my-check',
+            });
+  - language: yaml
+    label: "RIGHT — pass head SHA via env for run steps"
+    code: |
+      - name: Attest or sign artifact
+        env:
+          COMMIT_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
+        run: |
+          cosign sign-blob --bundle bundle.json artifact.tar.gz
+          # $COMMIT_SHA is the visible PR head SHA on pull_request events,
+          # falls back to github.sha for push/schedule/workflow_dispatch
+prevention:
+  - "Never use github.sha directly for Commit Status API calls in pull_request workflows — always use github.event.pull_request.head.sha."
+  - "For workflows triggered by both push and pull_request, use the safe fallback expression: ${{ github.event.pull_request.head.sha || github.sha }}."
+  - "After adding required status checks, verify they actually appear in the PR timeline — a missing check often means the wrong SHA is being targeted."
+  - "Run 'echo ${{ github.sha }} ${{ github.event.pull_request.head.sha }}' in a debug step to confirm the SHAs differ on a PR event."
+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 context — github.sha documentation"
+  - url: "https://docs.github.com/en/rest/commits/statuses"
+    label: "GitHub REST API — Commit statuses"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#pull_request"
+    label: "Events that trigger workflows — pull_request event and merge commit"
+  - url: "https://stackoverflow.com/questions/71264370/why-is-github-sha-not-pointing-to-the-pr-head-commit-on-pull-request-events"
+    label: "Stack Overflow — Why is github.sha not the PR head commit on pull_request events?"

package/errors/triggers/pull-request-labeled-type-not-default.yml

@@ -0,0 +1,98 @@
+id: triggers-030
+title: "`pull_request` Default Activity Types Exclude `labeled` and `unlabeled` — Label-Gated Workflows Never Fire"
+category: triggers
+severity: silent-failure
+tags:
+  - pull_request
+  - labeled
+  - unlabeled
+  - activity-types
+  - types
+  - label-gate
+patterns:
+  - regex: 'on:\s*\n\s*pull_request:\s*\n(?!\s*types:)'
+    flags: "im"
+  - regex: 'types:\s*\[?\s*labeled'
+    flags: "i"
+error_messages:
+  - "No error — workflow simply never runs when a label is added to or removed from a PR"
+root_cause: |
+  The pull_request event triggers on three activity types by default: opened, synchronize,
+  and reopened. The labeled and unlabeled activity types — which fire when a label is added
+  or removed from a pull request — are NOT in the default set. Any workflow that relies on
+  label additions to trigger CI (deploy-preview gates, security scan exclusions, manual
+  override flags, environment promotion labels) will silently never run.
+
+  This affects common workflows such as:
+  - "preview" label triggers a staging deployment
+  - "approved-for-staging" label kicks off an integration test suite
+  - "skip-e2e" label skips expensive test steps
+  - "force-rebuild" label retriggers a build without a new commit
+
+  Because there is no workflow run at all (no skipped run, no failed run, no log entry),
+  the failure is completely invisible. Developers typically spend significant time debugging
+  the conditional logic inside the workflow before discovering the trigger itself never fired.
+  The workflow only runs if the PR is also opened, synchronized, or reopened coincidentally
+  with the label operation.
+fix: |
+  Explicitly declare all required activity types in the pull_request trigger using the
+  types: key. Include labeled (and unlabeled if removals also matter) alongside the
+  standard types if the workflow should run for both code changes and label changes.
+fix_code:
+  - language: yaml
+    label: "WRONG — pull_request without types never fires on label add"
+    code: |
+      on:
+        pull_request:         # defaults: opened, synchronize, reopened only
+          branches: [main]
+
+      jobs:
+        preview:
+          if: contains(github.event.pull_request.labels.*.name, 'preview')
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Deploying preview..."  # never reached from label addition
+  - language: yaml
+    label: "RIGHT — explicitly include labeled in types"
+    code: |
+      on:
+        pull_request:
+          branches: [main]
+          types:
+            - opened
+            - synchronize
+            - reopened
+            - labeled         # fires when a label is added
+            - unlabeled       # fires when a label is removed
+
+      jobs:
+        preview:
+          if: contains(github.event.pull_request.labels.*.name, 'preview')
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Deploying preview..."
+  - language: yaml
+    label: "RIGHT — label-only workflow (fires only on label events)"
+    code: |
+      on:
+        pull_request:
+          types: [labeled, unlabeled]
+
+      jobs:
+        handle-label:
+          if: github.event.label.name == 'deploy-preview'
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Label '${{ github.event.label.name }}' added/removed"
+prevention:
+  - "Always explicitly declare types: when workflow logic depends on specific PR activity — labels, reviews, drafts, assignments, or milestones."
+  - "The default pull_request types are ONLY opened, synchronize, and reopened — all other activity types must be opt-in."
+  - "Test label-triggered workflows by adding the label manually after the workflow file is merged to the default branch."
+  - "Use github.event.action in run steps to distinguish between labeled and unlabeled events when both types are declared."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#pull_request"
+    label: "Events that trigger workflows — pull_request activity types"
+  - url: "https://docs.github.com/en/webhooks/webhook-events-and-payloads#pull_request"
+    label: "Webhook events — pull_request payload (full activity type list)"
+  - url: "https://stackoverflow.com/questions/63699767/github-actions-on-pull-request-labeled-trigger-not-working"
+    label: "Stack Overflow — GitHub Actions on: pull_request labeled trigger not working"

package/errors/yaml-syntax/cache-v3-save-always-unexpected-input.yml

@@ -0,0 +1,85 @@
+id: yaml-syntax-033
+title: "`save-always` Input Does Not Exist in `actions/cache` v3 — Unexpected Input Error"
+category: yaml-syntax
+severity: error
+tags:
+  - actions/cache
+  - save-always
+  - v3
+  - v4
+  - unexpected-input
+  - version-mismatch
+patterns:
+  - regex: "Unexpected input\\(s\\) 'save-always'"
+    flags: "i"
+  - regex: "Unexpected input.*save-always.*valid inputs are"
+    flags: "i"
+error_messages:
+  - "Unexpected input(s) 'save-always', valid inputs are ['path', 'key', 'restore-keys', 'upload-chunk-size', 'enableCrossOsArchive', 'fail-on-cache-miss', 'lookup-only']"
+  - "Warning: Unexpected input(s) 'save-always'"
+root_cause: |
+  The save-always input was introduced in actions/cache v4.0.0 to allow the internal
+  post-step cache save to run even when the job fails or is cancelled, bypassing the
+  hardcoded post-if: success() guard present in v3. In v3, saving on failure required
+  explicitly splitting the monolithic cache step into separate actions/cache/restore and
+  actions/cache/save steps with if: always().
+
+  Developers who copy examples from v4 documentation or Stack Overflow answers written
+  after December 2023 and apply them to a workflow still pinned to actions/cache@v3
+  receive an "Unexpected input(s) 'save-always'" warning or error. In v3 the input is
+  silently ignored in some versions and causes a non-zero exit in others. Either way,
+  the intent (save cache on failure) is never fulfilled.
+fix: |
+  Upgrade to actions/cache@v4 (or v4+) to use save-always: true directly. If upgrading
+  is not possible, replace the single cache step with explicit restore + save steps and
+  guard the save step with if: always().
+fix_code:
+  - language: yaml
+    label: "WRONG — save-always on cache@v3 (input does not exist)"
+    code: |
+      - uses: actions/cache@v3
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
+          save-always: true  # does not exist in v3 — unexpected input error
+  - language: yaml
+    label: "RIGHT — upgrade to cache@v4 to use save-always"
+    code: |
+      - uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
+          save-always: true  # introduced in v4.0.0
+  - language: yaml
+    label: "RIGHT — v3 workaround with explicit restore and save steps"
+    code: |
+      - name: Restore cache
+        id: cache-restore
+        uses: actions/cache/restore@v3
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Save cache
+        if: always()
+        uses: actions/cache/save@v3
+        with:
+          path: ~/.npm
+          key: ${{ steps.cache-restore.outputs.cache-primary-key }}
+prevention:
+  - "Pin all new workflows to actions/cache@v4 — v3 is missing save-always, restore-first-match-in-branch, and other v4 inputs."
+  - "When copying cache examples from documentation, check the version badge — inputs differ significantly between v3 and v4."
+  - "Enable Dependabot or Renovate for action version updates to avoid accumulating version-mismatch debt."
+  - "If still on v3, use the split restore/save pattern with if: always() for any workflow that must cache on failure."
+docs:
+  - url: "https://github.com/actions/cache/releases/tag/v4.0.0"
+    label: "actions/cache v4.0.0 release notes — save-always introduced"
+  - url: "https://github.com/actions/cache/blob/main/tips-and-workarounds.md#saving-cache-even-if-the-build-fails"
+    label: "actions/cache — Saving cache even if the build fails"
+  - url: "https://github.com/actions/cache/blob/main/save/README.md"
+    label: "actions/cache/save — Explicit save action"
+  - url: "https://stackoverflow.com/questions/60491837/saving-cache-on-job-failure-in-github-actions"
+    label: "Stack Overflow — Saving cache on job failure in GitHub Actions (200+ votes)"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@htekdev/actions-debugger",
-  "version": "1.0.36",
+  "version": "1.0.38",
   "description": "65+ real GitHub Actions errors, queryable by agents. CLI + MCP server + Copilot skills + error database.",
   "type": "module",
   "main": "./dist/index.js",