@htekdev/actions-debugger 1.0.35 → 1.0.37

package/errors/known-unsolved/checkout-eu-runner-timeout-regional-degradation.yml

@@ -0,0 +1,97 @@
+id: known-unsolved-033
+title: 'actions/checkout Hangs or Times Out From EU GitHub-Hosted Runners (Regional Degradation)'
+category: known-unsolved
+severity: error
+tags:
+  - checkout
+  - performance
+  - eu-runners
+  - timeout
+  - regional
+  - infrastructure
+patterns:
+  - regex: 'fatal: unable to access.*https://github\.com.*timed out'
+    flags: 'i'
+  - regex: 'fatal: unable to access.*https://github\.com.*Could not resolve host'
+    flags: 'i'
+  - regex: 'Error: Process completed with exit code 128'
+    flags: 'i'
+error_messages:
+  - "fatal: unable to access 'https://github.com/owner/repo/': Operation timed out"
+  - "Error: Process completed with exit code 128."
+  - 'actions/checkout step hanging for 5-30 minutes with no output'
+root_cause: |
+  Starting May 19, 2026, workflows running on GitHub-hosted runners in European
+  data centers began experiencing severely degraded actions/checkout performance.
+  The fetch/clone phase hangs silently for 5-30 minutes before either completing
+  slowly or timing out, regardless of repository size. Workflows that previously
+  completed checkout in 10-30 seconds are affected.
+
+  The root cause is an infrastructure-level degradation on GitHub's side
+  affecting the European runner subnet's connectivity to GitHub's Smart HTTP
+  server or CDN endpoints. This is distinct from general large-repo slowness:
+  even tiny repositories with shallow clones exhibit the hang. GitHub has not
+  published a root cause analysis or resolution timeline as of June 2026.
+
+  Notably, runners in US regions (us-east-1, us-west-2) are not affected —
+  the issue is specific to EU runner region routing. The error manifests as
+  either a silent hang (no log output during the fetch phase) or an eventual
+  "Operation timed out" exit code 128.
+
+  Source: actions/checkout#2441 (52 reactions, opened May 24, 2026, still open).
+fix: |
+  No upstream fix available — this is a GitHub infrastructure issue with no
+  workaround that completely eliminates the problem. Mitigations to reduce
+  impact:
+
+  1. Add timeout-minutes to checkout steps to prevent indefinite hangs and
+     fail fast with a clear error rather than a silent stuck pipeline.
+
+  2. Use fetch-depth: 1 (shallow clone) to reduce transfer size, which may
+     reduce hang duration even if it does not eliminate it.
+
+  3. Use sparse-checkout to limit the files transferred from the CDN.
+
+  4. For critical pipelines, consider temporarily switching to ubuntu-latest
+     with an explicit us-east-1 runner label if your GitHub plan supports
+     regional runner selection.
+
+  5. Subscribe to GitHub Status (githubstatus.com) for EU infrastructure
+     degradation notices — incidents affecting this region are tracked there.
+fix_code:
+  - language: yaml
+    label: 'Shallow clone with timeout to fail fast during EU degradation'
+    code: |
+      steps:
+        - name: Checkout
+          uses: actions/checkout@v4
+          timeout-minutes: 5      # fail fast instead of hanging for 30+ minutes
+          with:
+            fetch-depth: 1        # shallow clone reduces CDN transfer size
+  - language: yaml
+    label: 'Sparse checkout to minimize data fetched during regional degradation'
+    code: |
+      steps:
+        - name: Sparse checkout
+          uses: actions/checkout@v4
+          timeout-minutes: 5
+          with:
+            fetch-depth: 1
+            sparse-checkout: |
+              src/
+              tests/
+              package.json
+              go.mod
+prevention:
+  - 'Always specify fetch-depth: 1 for workflows that do not require full commit history'
+  - 'Add timeout-minutes to every checkout step to prevent indefinite pipeline hangs'
+  - 'Monitor p99 checkout duration from EU runners as a CI health SLI'
+  - 'Subscribe to GitHub Status page (githubstatus.com) for EU infrastructure degradation notices'
+  - 'Use sparse-checkout in large monorepos to reduce CDN dependency during fetch'
+docs:
+  - url: 'https://github.com/actions/checkout/issues/2441'
+    label: 'actions/checkout #2441: Checkouts extremely slow or timing out from EU (52 reactions, May 2026)'
+  - url: 'https://www.githubstatus.com/'
+    label: 'GitHub Status page for infrastructure incidents'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/evaluate-expressions-in-workflows-and-actions'
+    label: 'GitHub Docs: sparse-checkout in actions/checkout'

package/errors/permissions-auth/checkout-v6-includif-symlinked-work-credential-failure.yml

@@ -0,0 +1,93 @@
+id: permissions-auth-032
+title: 'checkout@v6 Credential Injection Fails on Self-Hosted Runners With Symlinked _work Directory'
+category: permissions-auth
+severity: error
+tags:
+  - checkout-v6
+  - self-hosted
+  - symlink
+  - credentials
+  - includif
+  - macos
+patterns:
+  - regex: 'fatal: could not read Username for.*terminal prompts disabled'
+    flags: 'i'
+  - regex: 'includeIf.*gitdir.*_work'
+    flags: 'i'
+  - regex: 'fatal: repository.*not found'
+    flags: 'i'
+error_messages:
+  - "fatal: could not read Username for 'https://github.com': terminal prompts disabled"
+  - 'Error: fatal: repository not found'
+  - 'Authentication failed'
+root_cause: |
+  actions/checkout@v6 changed credential injection from writing directly into
+  the repository configuration file as http.https://github.com/.extraheader
+  (the v5 approach) to using includeIf "gitdir:..." directives that reference
+  a temporary credentials file stored in _work/_temp/.
+
+  v6 writes the includeIf path using the symlink path of the runner _work
+  directory. However, the version control system evaluates gitdir: conditions
+  against the resolved (real) absolute path — it follows symlinks when
+  determining the current repository's directory.
+
+  When the runner _work directory is a symlink to an external volume (a common
+  setup for macOS Apple Silicon runners using external SSD storage), the
+  includeIf path written by v6 uses the symlink path
+  (e.g., /Users/runner/actions-runner-N/_work/repo/.git) but the actual
+  resolved path is different
+  (e.g., /Volumes/External/actions-runner-N-work/repo/.git).
+  These never match, so the credentials config file is never loaded and the
+  fetch step fails with "terminal prompts disabled."
+
+  v5 is unaffected because it injects credentials directly into the repository
+  configuration file rather than using conditional includes.
+  Source: actions/checkout#2393 (open March 2026, macOS Apple Silicon).
+fix: |
+  Option 1 (recommended): Pin to actions/checkout@v5 for workflows running on
+  self-hosted runners with symlinked _work directories. v5 injects credentials
+  directly and is not affected by this symlink resolution issue.
+
+  Option 2: Reconfigure the runner to use the real volume path directly.
+  Remove the symlink from _work and mount the external volume at the actual
+  runner work path location. This eliminates the symlink entirely.
+
+  Option 3: Use persist-credentials: false with a separate authentication
+  step that does not rely on the includeIf mechanism.
+fix_code:
+  - language: yaml
+    label: 'Pin to v5 as workaround for symlinked _work runners (checkout#2393)'
+    code: |
+      steps:
+        - name: Checkout
+          # Pinned to v5 — v6 includeIf credential injection fails when runner
+          # _work directory is a symlink to an external volume (checkout#2393)
+          uses: actions/checkout@v5
+          with:
+            token: ${{ secrets.GITHUB_TOKEN }}
+  - language: yaml
+    label: 'Use persist-credentials false with explicit token for subsequent steps'
+    code: |
+      steps:
+        - name: Checkout without credential persistence
+          uses: actions/checkout@v6
+          with:
+            persist-credentials: false
+
+        - name: Subsequent steps using explicit token
+          env:
+            GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          run: |
+            echo "Use GITHUB_TOKEN env var in subsequent authenticated operations"
+prevention:
+  - 'Audit self-hosted runner _work paths for symlinks before upgrading from checkout@v5 to v6'
+  - 'Avoid symlinking the runner _work directory — use bind mounts or configure the real path'
+  - 'Test checkout behavior on self-hosted runners in a canary workflow before rolling out v6'
+  - 'Check the resolved path differs from the symlink path when debugging "terminal prompts disabled" errors'
+docs:
+  - url: 'https://github.com/actions/checkout/issues/2393'
+    label: 'actions/checkout #2393: v6 includeIf credential matching fails on symlinked _work (open March 2026)'
+  - url: 'https://github.com/actions/checkout/issues/2313'
+    label: 'actions/checkout #2313: v6 breaks Docker actions using credential auth (related, closed)'
+  - url: 'https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/configuring-the-self-hosted-runner-application-as-a-service'
+    label: 'GitHub Docs: Configuring the self-hosted runner as a service'

package/errors/runner-environment/ephemeral-runner-not-found-after-register.yml

@@ -0,0 +1,115 @@
+id: runner-environment-090
+title: 'Ephemeral Self-Hosted Runner Fails Immediately With "An error occurred: Runner not found"'
+category: runner-environment
+severity: error
+tags:
+  - self-hosted
+  - ephemeral
+  - runner-not-found
+  - registration
+  - broker
+  - jit
+patterns:
+  - regex: 'An error occurred: Runner not found'
+    flags: 'i'
+  - regex: 'RunnerNotFoundException'
+    flags: 'i'
+error_messages:
+  - 'An error occurred: Runner not found'
+  - 'GitHub.Actions.RunService.WebApi.RunnerNotFoundException'
+  - 'Listening for Jobs'
+root_cause: |
+  GitHub's broker endpoint returns RunnerNotFoundException immediately after
+  a successful registration and connection for ephemeral self-hosted runners
+  configured with replace mode. The runner completes registration ("Successfully
+  replaced the runner"), establishes connection ("Runner connection is good"),
+  starts listening for jobs, then receives a RunnerNotFoundException from the
+  broker HTTP client within seconds.
+
+  The error originates in BrokerHttpClient.cs where the broker API returns a
+  404/RunnerNotFoundException for the registered runner slot. This can occur
+  when the broker has stale slot state from the previous ephemeral runner
+  iteration that collides with the newly registered runner identity during the
+  brief window between registration and first poll.
+
+  The runner has no graceful retry handling for this condition — it exits with
+  status 1, causing systemd to restart it repeatedly, rapidly exhausting GitHub
+  App installation tokens through frequent re-registration cycles.
+
+  Affects all architectures (x86_64, aarch64, s390x) on various runner versions.
+  Spikes during periods of elevated load on GitHub broker infrastructure.
+  Source: actions/runner#3857 (116 reactions, open May 2025).
+fix: |
+  1. Switch from replace-mode ephemeral runners to JIT (Just-In-Time) runner
+     tokens. JIT runners receive a pre-assigned job ID and avoid the broker
+     slot replacement race entirely.
+  2. Update the runner to the latest version (v2.334.0+) which improves retry
+     behavior around transient broker errors.
+  3. Add restart delay in the systemd service unit to prevent token exhaustion
+     on rapid restart loops:
+       RestartSec=30
+       StartLimitIntervalSec=300
+       StartLimitBurst=5
+  4. Monitor runner diagnostic logs in _diag/Runner_*.log for the
+     RunnerNotFoundException pattern to distinguish broker errors from
+     configuration issues.
+fix_code:
+  - language: yaml
+    label: 'Systemd service unit with restart throttle to prevent token exhaustion'
+    code: |
+      # /etc/systemd/system/actions-runner.service
+      [Unit]
+      Description=GitHub Actions Self-Hosted Runner
+      After=network-online.target
+
+      [Service]
+      ExecStart=/home/runner/actions-runner/run.sh
+      Restart=on-failure
+      RestartSec=30
+      StartLimitIntervalSec=300
+      StartLimitBurst=5
+      User=runner
+
+      [Install]
+      WantedBy=multi-user.target
+  - language: yaml
+    label: 'Workflow using JIT runner token to avoid broker slot collision'
+    code: |
+      jobs:
+        provision-runner:
+          runs-on: ubuntu-latest
+          outputs:
+            runner-token: ${{ steps.jit.outputs.encoded_jit_config }}
+          steps:
+            - name: Generate JIT runner token
+              id: jit
+              uses: actions/github-script@v7
+              with:
+                script: |
+                  const { data } = await github.rest.actions.generateRunnerJitconfigForRepo({
+                    owner: context.repo.owner,
+                    repo: context.repo.repo,
+                    name: 'ephemeral-jit-runner',
+                    runner_group_id: 1,
+                    labels: ['self-hosted', 'ephemeral', 'linux']
+                  });
+                  core.setOutput('encoded_jit_config', data.encoded_jit_config);
+
+        build:
+          needs: provision-runner
+          runs-on: [self-hosted, ephemeral, linux]
+          steps:
+            - uses: actions/checkout@v4
+prevention:
+  - 'Use JIT runner tokens instead of replace-mode registration to eliminate broker slot race'
+  - 'Set systemd RestartSec to at least 30 seconds to avoid GitHub App token exhaustion'
+  - 'Monitor _diag/Runner_*.log for RunnerNotFoundException patterns and alert on restart frequency'
+  - 'Keep runner version current — broker compatibility fixes are regularly backported'
+  - 'Consider Kubernetes ARC ephemeral runners where pod lifecycle handles registration cleanly'
+docs:
+  - url: 'https://github.com/actions/runner/issues/3857'
+    label: 'actions/runner #3857: An error occurred: Runner not found (116 reactions, open May 2025)'
+  - url: 'https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/autoscaling-with-self-hosted-runners#using-just-in-time-runners'
+    label: 'GitHub Docs: Just-in-time runners (JIT)'
+  - url: 'https://docs.github.com/en/rest/actions/self-hosted-runners#create-configuration-for-a-just-in-time-runner-for-a-repository'
+    label: 'GitHub REST API: Generate JIT runner config'

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/worker-wedged-task-orchestration-job-not-found.yml

@@ -0,0 +1,119 @@
+id: runner-environment-091
+title: 'Self-Hosted Runner Worker Wedges Indefinitely After TaskOrchestrationJobNotFoundException'
+category: runner-environment
+severity: error
+tags:
+  - self-hosted
+  - runner-worker
+  - wedged
+  - slot-starvation
+  - v2-runservice
+  - macos
+  - apple-silicon
+patterns:
+  - regex: 'TaskOrchestrationJobNotFoundException.*workflow instance not found'
+    flags: 'i'
+  - regex: 'Job not found:.*workflow instance not found'
+    flags: 'i'
+  - regex: 'CompleteJobAsync.*TaskOrchestrationJobNotFoundException'
+    flags: 'i'
+error_messages:
+  - 'GitHub.DistributedTask.WebApi.TaskOrchestrationJobNotFoundException: Job not found: <job-guid>. workflow instance not found'
+  - 'TaskOrchestrationJobNotFoundException: workflow instance not found'
+  - 'System.AggregateException: One or more errors occurred. (Job not found:'
+root_cause: |
+  When a self-hosted runner Worker process calls CompleteJobAsync in the V2
+  RunService path (useV2Flow: true, RunServiceHttpClient.CompleteJobAsync)
+  and the GitHub orchestrator has discarded the job record (e.g., due to a
+  server-side timeout, infrastructure failover, or job cancellation during
+  finalization), the Worker receives TaskOrchestrationJobNotFoundException
+  with "workflow instance not found."
+
+  After exhausting configured retry attempts (default maxAttempts), the Worker
+  logs the exception and stops processing — but critically, it fails to call
+  Environment.Exit and the process remains alive at ~0.1% CPU with no active
+  work, no child processes, and no job cleanup activity.
+
+  The parent Runner.Listener treats the still-running Worker process as a busy
+  runner slot and refuses to spawn a new Worker. This causes runner slot
+  starvation: the affected runner stops accepting new jobs until the wedged
+  Worker is externally terminated (kill, reboot, or watchdog).
+
+  On one 3-host Apple Silicon runner pool (v2.334.0), this affected 32.8% of
+  Worker invocations (50 of 152) over three weeks, with one incident wedging
+  all three Workers simultaneously and blocking CI for 3+ hours.
+  Source: actions/runner#4418 (open May 2026).
+fix: |
+  No upstream fix available — the Worker does not exit on non-retryable
+  CompleteJobAsync failures. Mitigations:
+
+  1. Deploy a watchdog that monitors _diag/Worker_*.log for the
+     TaskOrchestrationJobNotFoundException pattern and kills the wedged
+     Worker process by PID.
+
+  2. Use Kubernetes ARC ephemeral runners where the pod lifecycle replaces
+     the entire runner environment after each job — a wedged Worker is
+     automatically cleaned up when the pod is recycled.
+
+  3. Configure a hard systemd runtime limit (RuntimeMaxSec) that terminates
+     any runner process exceeding your longest expected job duration plus a
+     safety margin.
+
+  4. Add an external health-check cron that queries the GitHub API for runner
+     status and restarts the runner service if slots show "busy" longer than
+     expected.
+fix_code:
+  - language: yaml
+    label: 'Kubernetes ARC ephemeral runner configuration (avoids wedged Worker state)'
+    code: |
+      # ARC RunnerDeployment — pods are recycled after each job
+      apiVersion: actions.summerwind.dev/v1alpha1
+      kind: RunnerDeployment
+      metadata:
+        name: ephemeral-runner-deployment
+      spec:
+        replicas: 3
+        template:
+          spec:
+            ephemeral: true          # pod recycled after each job, no wedge possible
+            repository: owner/repo
+            labels:
+              - self-hosted
+              - ephemeral
+  - language: yaml
+    label: 'Scheduled watchdog workflow to detect stalled runner slots via API'
+    code: |
+      on:
+        schedule:
+          - cron: '*/15 * * * *'    # every 15 minutes
+
+      jobs:
+        runner-health-check:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Detect stalled self-hosted runners
+              uses: actions/github-script@v7
+              with:
+                script: |
+                  const runners = await github.rest.actions.listSelfHostedRunnersForRepo({
+                    owner: context.repo.owner,
+                    repo: context.repo.repo
+                  });
+                  const offline = runners.data.runners.filter(r => r.status === 'offline');
+                  if (offline.length > 0) {
+                    core.warning('Offline/stalled runners: ' + offline.map(r => r.name).join(', '));
+                    // Trigger your runner restart webhook here
+                  }
+prevention:
+  - 'Use ephemeral Kubernetes ARC runners — pod recycle eliminates wedged Worker slot starvation'
+  - 'Monitor _diag/Worker_*.log for TaskOrchestrationJobNotFoundException patterns'
+  - 'Set systemd RuntimeMaxSec to maximum expected job duration plus 30 minutes'
+  - 'Track runner slot busy duration — sudden sustained busy state with no job output indicates wedge'
+  - 'Deploy a watchdog process alongside the runner that monitors Worker PID lifetime'
+docs:
+  - url: 'https://github.com/actions/runner/issues/4418'
+    label: 'actions/runner #4418: Worker wedges after TaskOrchestrationJobNotFoundException (open May 2026)'
+  - url: 'https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/autoscaling-with-self-hosted-runners'
+    label: 'GitHub Docs: Autoscaling with self-hosted runners'
+  - url: 'https://github.com/actions/actions-runner-controller'
+    label: 'actions/actions-runner-controller: Kubernetes ARC runner controller'

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.35",
+  "version": "1.0.37",
   "description": "65+ real GitHub Actions errors, queryable by agents. CLI + MCP server + Copilot skills + error database.",
   "type": "module",
   "main": "./dist/index.js",