@htekdev/actions-debugger 1.0.107 → 1.0.109

package/errors/caching-artifacts/cache-key-runner-os-insufficient-ubuntu-version-migration.yml

@@ -0,0 +1,90 @@
+id: caching-artifacts-063
+title: "runner.os insufficient in cache key after ubuntu-22.04 to ubuntu-24.04 migration — glibc-incompatible binaries silently restored"
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - cache-key
+  - runner.os
+  - ubuntu-24.04
+  - binary-compatibility
+  - glibc
+  - migration
+patterns:
+  - regex: 'symbol lookup error.*undefined symbol'
+    flags: 'i'
+  - regex: 'version.*GLIBC.*not found'
+    flags: 'i'
+  - regex: 'GLIBCXX.*not found'
+    flags: 'i'
+error_messages:
+  - "symbol lookup error: ./bin/app: undefined symbol: __libc_single_threaded"
+  - "version `GLIBC_2.38' not found (required by ./bin/app)"
+  - "GLIBCXX_3.4.32 not found in /usr/lib/x86_64-linux-gnu/libstdc++.so.6"
+root_cause: |
+  `runner.os` returns "Linux" for ALL Linux-based GitHub-hosted runners regardless of
+  Ubuntu distribution version: ubuntu-22.04 (glibc 2.35, GCC 11) and ubuntu-24.04
+  (glibc 2.39, GCC 13) both return "Linux".
+
+  When a workflow migrates from `runs-on: ubuntu-22.04` to `runs-on: ubuntu-latest`
+  (which became ubuntu-24.04 in March 2025), cache keys using only `${{ runner.os }}`
+  continue to match previously saved caches from ubuntu-22.04. Compiled native binaries
+  — Rust/Cargo target directories, CMake build outputs, Go CGO artifacts, Python
+  Cython-compiled extensions, pre-built Node.js native addons — are restored from
+  the ubuntu-22.04 cache onto an ubuntu-24.04 runner.
+
+  Because ubuntu-24.04 ships a newer glibc (2.39 vs 2.35) and updated libstdc++, binaries
+  compiled against the older ABI fail at runtime with dynamic linker errors:
+
+    symbol lookup error: ./bin/app: undefined symbol: __libc_single_threaded
+    version `GLIBC_2.38' not found (required by ./bin/app)
+
+  The cache restore step succeeds and shows a green checkmark. The failure surfaces only
+  when the restored binary is executed later in the pipeline, potentially hours into a
+  build. Because the compile step is skipped (cache hit), the error appears to come from
+  the execution step with no indication that a stale cross-version cache is the cause.
+fix: |
+  Add the runner image version to the cache key so that binary artifacts are not shared
+  across different Ubuntu distribution versions. GitHub-hosted runners expose the image
+  version as the `ImageVersion` environment variable (e.g. "20250312.1"). Alternatively,
+  hash `/etc/os-release` as a portable OS version fingerprint.
+fix_code:
+  - language: yaml
+    label: "Include ImageVersion in cache key to isolate per Ubuntu release"
+    code: |
+      - name: Cache Cargo build artifacts
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target/
+          # ImageVersion (e.g. "20250312.1") differs between ubuntu-22.04 and ubuntu-24.04
+          # Prevents restoring ubuntu-22.04 glibc-2.35 binaries on ubuntu-24.04 glibc-2.39
+          key: ${{ runner.os }}-${{ env.ImageVersion }}-cargo-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-${{ env.ImageVersion }}-cargo-
+  - language: yaml
+    label: "Alternative: hash /etc/os-release for portable OS version fingerprint"
+    code: |
+      - name: Cache compiled artifacts
+        uses: actions/cache@v4
+        with:
+          path: build/
+          key: >-
+            ${{ runner.os }}-
+            ${{ hashFiles('/etc/os-release') }}-
+            cmake-${{ hashFiles('CMakeLists.txt', '**/CMakeLists.txt') }}
+          restore-keys: |
+            ${{ runner.os }}-${{ hashFiles('/etc/os-release') }}-cmake-
+prevention:
+  - "After migrating `runs-on` from a specific ubuntu version to `ubuntu-latest`, bust existing caches by adding a new key prefix or bumping a cache version counter"
+  - "Include `${{ env.ImageVersion }}` in cache keys whenever the cached content contains compiled native binaries"
+  - "Use `runner.arch` for x64/ARM64 differences and `ImageVersion` for OS version differences together for complete binary cache isolation"
+  - "Prefer caching dependency manifests and source-level artifacts over compiled binaries when cross-version compatibility is uncertain"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows"
+    label: "GitHub Actions — caching dependencies"
+  - url: "https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2404-Readme.md"
+    label: "ubuntu-24.04 runner image specification (glibc and GCC versions)"
+  - url: "https://github.blog/changelog/2025-03-05-github-actions-ubuntu-latest-is-now-ubuntu-24-04/"
+    label: "GitHub Changelog — ubuntu-latest is now ubuntu-24.04 (March 2025)"

package/errors/caching-artifacts/caching-artifacts-064.yml

@@ -0,0 +1,92 @@
+id: caching-artifacts-064
+title: 'Third-party actions bundling @actions/cache npm v3 return "Cache service responded with 422" after Dec 2024 backend migration'
+category: caching-artifacts
+severity: error
+tags:
+  - actions-cache
+  - deprecated-api
+  - cache-backend
+  - 422
+  - npm-package
+  - third-party-action
+  - migration
+patterns:
+  - regex: 'Cache service responded with 422'
+    flags: 'i'
+  - regex: 'Failed to save cache.*422|Failed to restore cache.*422'
+    flags: 'i'
+  - regex: 'cache.*HTTP 422|HTTP 422.*cache'
+    flags: 'i'
+error_messages:
+  - "Cache service responded with 422"
+  - "Error: Cache service responded with 422"
+  - "Failed to save cache: Cache service responded with 422"
+  - "Warning: Failed to restore cache: Cache service responded with 422"
+root_cause: |
+  In December 2024, GitHub migrated the Actions cache backend to a new service API.
+  The deprecated v3 cache API endpoints now return HTTP 422 instead of processing
+  cache requests. Any action that embeds `@actions/cache` npm package at v3.x sends
+  requests to the old endpoint and receives 422 responses.
+
+  This affects any action — not just `actions/cache` itself — that bundles the old
+  `@actions/cache` npm package internally. Common affected actions:
+  - `actions/setup-node@v2` / `@v3` (embed @actions/cache v3)
+  - `actions/setup-python@v4` and earlier
+  - `actions/setup-go@v4` and earlier
+  - Custom or third-party JavaScript/composite actions that haven't updated
+    their package-lock.json since early 2024
+
+  The 422 error appears in the step output but the visible message does not mention
+  deprecated API versions or npm package issues — it only shows the HTTP status code.
+
+  Note: This is distinct from `caching-artifacts-056` (actions/cache v1/v2 hard
+  deprecation which shows "automatically failed because it uses a deprecated version").
+  That error comes from the version check; this error comes from the actual API call.
+fix: |
+  Upgrade the affected action to a version that bundles `@actions/cache` npm v4+.
+  For first-party GitHub actions, use the latest major version:
+  - `actions/setup-node`   → upgrade to @v4 or @v5
+  - `actions/setup-python` → upgrade to @v5
+  - `actions/setup-go`     → upgrade to @v5
+  - `actions/cache` used directly → upgrade to @v4
+
+  For third-party actions, open an issue asking the maintainer to update
+  @actions/cache in their package-lock.json and re-bundle the action.
+
+  As a temporary workaround, disable caching in the action to unblock CI:
+fix_code:
+  - language: yaml
+    label: 'Upgrade setup-* actions to latest major version with updated cache client'
+    code: |
+      # Before (bundled @actions/cache v3 — returns 422 after Dec 2024 migration)
+      - uses: actions/setup-node@v2
+        with:
+          node-version: '18'
+          cache: 'npm'
+
+      # After (@actions/cache v4+ bundled — compatible with current cache service)
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '18'
+          cache: 'npm'
+  - language: yaml
+    label: 'Disable caching as temporary workaround if action cannot be upgraded'
+    code: |
+      - uses: actions/setup-node@v2
+        with:
+          node-version: '18'
+          cache: ''   # empty string disables cache, avoids 422 until action is upgraded
+prevention:
+  - 'Keep all setup-* actions at their latest major version to stay compatible with the cache service API'
+  - 'Audit all uses: references for versions older than January 2024 — they may bundle stale @actions/cache v3'
+  - 'Enable Dependabot version updates for GitHub Actions to automatically surface major version bumps'
+  - 'After any GitHub changelog cache-migration notice, scan workflows for outdated action pins'
+docs:
+  - url: 'https://github.blog/changelog/2024-12-05-notice-of-upcoming-releases-and-breaking-changes-for-github-actions'
+    label: 'GitHub Changelog — Notice of cache migration and deprecated action versions (Dec 2024)'
+  - url: 'https://github.com/actions/toolkit/tree/main/packages/cache'
+    label: 'actions/toolkit — @actions/cache npm package changelog'
+  - url: 'https://github.com/actions/setup-node/issues/1275'
+    label: 'actions/setup-node#1275 — Cache service 422 errors with older action versions (13 reactions)'
+  - url: 'https://github.com/orgs/community/discussions/155534'
+    label: 'GitHub Community — Cache service 422 flaky restores during Dec 2024 migration'

package/errors/known-unsolved/cross-job-tmp-files-separate-runners.yml

@@ -0,0 +1,121 @@
+id: known-unsolved-057
+title: 'Jobs run on separate fresh runners — /tmp and filesystem are not shared between jobs'
+category: known-unsolved
+severity: limitation
+tags:
+  - jobs
+  - runner
+  - filesystem
+  - tmp
+  - isolation
+  - artifacts
+  - cross-job
+  - runner-environment
+patterns:
+  - regex: 'No such file or directory.*/tmp/'
+    flags: 'i'
+  - regex: 'ENOENT.*no such file.*tmp|cannot.*open.*/tmp/.*no such'
+    flags: 'i'
+  - regex: 'file.*not found.*/tmp|/tmp/.*does not exist'
+    flags: 'i'
+error_messages:
+  - "/tmp/output.json: No such file or directory"
+  - "Error: ENOENT: no such file or directory, open '/tmp/result.txt'"
+  - "/tmp/build-manifest.json: No such file or directory"
+root_cause: |
+  Each job in a GitHub Actions workflow runs on a completely separate, freshly
+  provisioned runner instance. There is NO shared filesystem between jobs. Files
+  written to `/tmp`, `$RUNNER_TEMP`, `$GITHUB_WORKSPACE`, or any other path during
+  one job are invisible to all subsequent jobs.
+
+  This is a fundamental architectural property: GitHub provisions a new virtual machine
+  for each job. The previous job's VM is terminated before the next job starts. No
+  filesystem state survives the job boundary.
+
+  Common patterns that fail for this reason:
+  1. Build job writes `/tmp/report.json` → deploy job tries to read `/tmp/report.json`
+  2. Test job saves coverage to `$RUNNER_TEMP/coverage.xml` → reporter job looks for it
+  3. Compile job produces `./dist/app` → signing job tries to use `./dist/app` without
+     re-downloading it via artifacts
+  4. First job exports env vars via `$GITHUB_ENV` → second job expects those env vars
+     (env vars set via GITHUB_ENV are also job-scoped and do not persist)
+  5. Steps within the SAME job DO share `/tmp` and the workspace — the limitation is
+     specifically at the JOB boundary
+
+  Self-hosted runner pools with persistent workspaces can accidentally appear to share
+  state between jobs on the same machine, but this is unreliable (another job may have
+  cleaned the directory) and creates security risks (secret leakage between runs).
+fix: |
+  There is no mechanism to share filesystem state between jobs without explicitly
+  transferring the data. Two patterns solve this:
+
+  1. Use `actions/upload-artifact` at the end of the producing job and
+     `actions/download-artifact` at the start of the consuming job.
+     Best for: files, binaries, test results, build outputs.
+
+  2. Use job `outputs:` to pass small string values. The producing job emits
+     `echo "key=value" >> $GITHUB_OUTPUT` and declares it under `outputs:`.
+     The consuming job reads it as `needs.<job>.outputs.<key>`.
+     Best for: version strings, commit SHAs, boolean flags, counts.
+fix_code:
+  - language: yaml
+    label: 'Pass files between jobs using upload-artifact / download-artifact'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Build binary
+              run: make build   # produces ./dist/app
+
+            - name: Upload for next job
+              uses: actions/upload-artifact@v4
+              with:
+                name: app-binary
+                path: ./dist/app   # upload so sign job can download it
+
+        sign:
+          needs: build
+          runs-on: ubuntu-latest
+          steps:
+            - name: Download binary
+              uses: actions/download-artifact@v4
+              with:
+                name: app-binary
+                path: ./dist
+
+            - name: Sign binary
+              run: cosign sign ./dist/app
+  - language: yaml
+    label: 'Pass small string data between jobs using job outputs'
+    code: |
+      jobs:
+        compute-version:
+          runs-on: ubuntu-latest
+          outputs:
+            version: ${{ steps.ver.outputs.version }}
+          steps:
+            - id: ver
+              run: echo "version=$(cat VERSION)" >> "$GITHUB_OUTPUT"
+
+        deploy:
+          needs: compute-version
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Deploying v${{ needs.compute-version.outputs.version }}"
+prevention:
+  - 'Never rely on /tmp, $RUNNER_TEMP, or workspace paths to share data between jobs — use artifacts or job outputs'
+  - 'Remember: only steps within the same job share a filesystem; different jobs always get separate runners'
+  - 'Use actions/upload-artifact@v4 for files; use job outputs for strings; use caches only for dependency restoration'
+  - 'Environment variables set with GITHUB_ENV are also job-scoped and do not persist across job boundaries'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/storing-and-sharing-data-from-a-workflow'
+    label: 'GitHub Docs — Storing and sharing data between jobs using artifacts'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/passing-information-between-jobs'
+    label: 'GitHub Docs — Passing information between jobs using outputs'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-where-your-workflow-runs/about-github-hosted-runners'
+    label: 'GitHub Docs — About GitHub-hosted runners (each job gets a fresh VM)'
+  - url: 'https://github.com/orgs/community/discussions/26671'
+    label: 'GitHub Community — Sharing files and filesystem data between workflow jobs'

package/errors/permissions-auth/create-github-app-token-invalid-key-data.yml

@@ -0,0 +1,94 @@
+id: permissions-auth-062
+title: 'create-github-app-token "Invalid keyData" — private key passed via env var with escaped \\n sequences'
+category: permissions-auth
+severity: error
+tags:
+  - github-app
+  - private-key
+  - invalid-key-data
+  - environment-variable
+  - newlines
+  - create-github-app-token
+  - webcrypto
+patterns:
+  - regex: 'Invalid keyData'
+    flags: 'i'
+  - regex: 'DOMException.*Invalid keyData|DataError.*Invalid keyData'
+    flags: 'i'
+  - regex: 'Failed to create token for .+ \(attempt \d+\): Invalid keyData'
+    flags: 'i'
+error_messages:
+  - "DOMException [DataError]: Invalid keyData"
+  - "Failed to create token for \"repo-name\" (attempt 1): Invalid keyData"
+  - "Failed to create token for \"repo-name\" (attempt 2): Invalid keyData"
+  - "Error: Invalid keyData"
+root_cause: |
+  The `actions/create-github-app-token` action v2+ uses the Web Crypto API
+  (`crypto.subtle.importKey()`) to load the GitHub App private key. This API
+  is strict about key formatting — it throws `DOMException [DataError]: Invalid keyData`
+  if the PEM key material is malformed at the byte level.
+
+  The most common trigger is passing the private key via an environment variable
+  where literal `\n` two-character sequences appear instead of actual newline (0x0A)
+  bytes. This happens when:
+  1. The key is constructed inline in YAML with `"-----BEGIN...\nMIIE...\n-----END..."`
+     where `\n` is a YAML string escape, not a real newline in the multi-line base64 body
+  2. An external CI system or secrets manager serializes the PEM key as a single line
+     with literal backslash-n separators before injecting it into the Actions environment
+  3. Shell variable interpolation collapses the newlines (e.g., `echo $PRIVATE_KEY`)
+
+  The Web Crypto SubtleCrypto API attempts to Base64-decode the key body. When the
+  PEM line breaks are backslash-n characters (0x5C 0x6E) instead of 0x0A, the Base64
+  chunks are malformed and importKey() throws "Invalid keyData" immediately — before
+  any GitHub API call is made.
+
+  This is distinct from "A JSON web token could not be decoded" (permissions-auth-021)
+  which occurs when the key IS imported successfully but the resulting JWT is rejected
+  by GitHub's API — a later-stage failure caused by different formatting issues such
+  as trailing whitespace, CRLF endings, or missing PEM headers.
+fix: |
+  Pass the private key directly as an action input using the GitHub Actions secret
+  expression `${{ secrets.APP_PRIVATE_KEY }}`. When GitHub resolves a secret, it
+  preserves the original stored bytes including actual newlines. Do NOT pass the key
+  through env: variables or inline string construction.
+
+  To store the key with correct newlines, set the secret from the downloaded .pem file
+  using the GitHub CLI:
+    gh secret set APP_PRIVATE_KEY < my-app.private-key.pem
+fix_code:
+  - language: yaml
+    label: 'Correct: pass private key directly as action input from secret'
+    code: |
+      - uses: actions/create-github-app-token@v1
+        id: app-token
+        with:
+          app-id: ${{ vars.APP_ID }}
+          private-key: ${{ secrets.APP_PRIVATE_KEY }}   # newlines preserved by Actions runtime
+  - language: yaml
+    label: 'Wrong: constructing key inline with \\n escape sequences (causes Invalid keyData)'
+    code: |
+      # DO NOT DO THIS — \n are literal two-char sequences, not newlines
+      - name: Broken token generation
+        env:
+          KEY: "-----BEGIN RSA PRIVATE KEY-----\nMIIEow...\n-----END RSA PRIVATE KEY-----"
+        run: |
+          echo "$KEY" > /tmp/key.pem
+          # The action will fail with: DOMException [DataError]: Invalid keyData
+  - language: shell
+    label: 'Set secret from .pem file using GitHub CLI (preserves real newlines)'
+    code: |
+      gh secret set APP_PRIVATE_KEY < my-app.2024-01-15.private-key.pem
+prevention:
+  - 'Always set APP_PRIVATE_KEY secret using `gh secret set KEY < file.pem`, not by pasting the raw PEM text with \\n sequences'
+  - 'Pass the key exclusively as `private-key: ${{ secrets.KEY }}` — never via env: or inline string interpolation'
+  - 'If importing from an external secrets manager, ensure the manager preserves actual newline bytes (0x0A) when injecting into GitHub Actions secrets'
+  - 'Verify the secret was set correctly: run `gh secret list` and confirm the key was recently updated'
+docs:
+  - url: 'https://github.com/actions/create-github-app-token'
+    label: 'actions/create-github-app-token README'
+  - url: 'https://github.com/actions/create-github-app-token/issues/184'
+    label: 'actions/create-github-app-token#184 — Invalid keyData when key passed via environment variable'
+  - url: 'https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/importKey'
+    label: 'MDN — SubtleCrypto.importKey() — DOMException DataError causes'
+  - url: 'https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-private-key-for-a-github-app'
+    label: 'GitHub Docs — Generating a private key for a GitHub App'

package/errors/permissions-auth/create-github-app-token-v2-default-single-repo-scope.yml

@@ -0,0 +1,70 @@
+id: permissions-auth-061
+title: "actions/create-github-app-token v2 — default token scope limited to current repository only"
+category: permissions-auth
+severity: error
+tags:
+  - github-app
+  - create-github-app-token
+  - multi-repo
+  - token-scope
+  - v2-migration
+patterns:
+  - regex: 'Resource not accessible by integration'
+    flags: 'i'
+  - regex: 'actions/create-github-app-token@v2'
+    flags: 'i'
+error_messages:
+  - "Resource not accessible by integration"
+  - "RequestError [HttpError]: Resource not accessible by integration"
+root_cause: |
+  actions/create-github-app-token underwent a breaking scope change in v2 (released 2024).
+
+  In v1: when no `repositories` input is specified, the generated token is scoped to ALL
+  repositories the GitHub App installation has access to.
+
+  In v2: when no `repositories` or `owner` input is specified, the token is scoped ONLY
+  to the current repository where the workflow is running. This matches the GitHub App
+  installation token API default behavior when requesting a per-repository token.
+
+  Workflows that used v1 and relied on the token to access other repositories (for
+  cross-repo clones, API calls, pushes, or artifact publishing) silently receive a
+  limited-scope token in v2. Operations on other repos return "Resource not accessible
+  by integration" or "HTTP 404 Not Found" with no clear indication that a v2 migration
+  caused the regression.
+fix: |
+  Explicitly declare the repositories the token should cover using the `repositories`
+  input (comma-separated repository names, without the org prefix). To grant access to
+  all repositories the app has access to within the same organization, use the `owner`
+  input instead.
+fix_code:
+  - language: yaml
+    label: "Explicit multi-repo token scope (v2)"
+    code: |
+      - name: Generate token
+        id: app-token
+        uses: actions/create-github-app-token@v2
+        with:
+          app-id: ${{ vars.APP_ID }}
+          private-key: ${{ secrets.PRIVATE_KEY }}
+          # List every repository the token needs access to
+          repositories: "repo-a,repo-b,infra-configs"
+  - language: yaml
+    label: "Org-wide token scope using owner input (v2)"
+    code: |
+      - name: Generate token
+        id: app-token
+        uses: actions/create-github-app-token@v2
+        with:
+          app-id: ${{ vars.APP_ID }}
+          private-key: ${{ secrets.PRIVATE_KEY }}
+          # Grants access to all repos the app has access to in the org
+          owner: ${{ github.repository_owner }}
+prevention:
+  - "When upgrading from v1 to v2, audit all usages for cross-repo operations and add an explicit `repositories:` or `owner:` input"
+  - "Pin to a major version tag and review the CHANGELOG before upgrading any action that generates authentication tokens"
+  - "Test cross-repo operations in a staging workflow immediately after a major version upgrade"
+docs:
+  - url: "https://github.com/actions/create-github-app-token/releases/tag/v2.0.0"
+    label: "actions/create-github-app-token v2.0.0 release notes (scope change)"
+  - url: "https://github.com/actions/create-github-app-token/blob/main/README.md#inputs"
+    label: "actions/create-github-app-token README — repositories and owner inputs"

package/errors/silent-failures/github-event-head-commit-null-non-push-events.yml

@@ -0,0 +1,99 @@
+id: silent-failures-095
+title: "github.event.head_commit is null on non-push events — commit message checks silently return false"
+category: silent-failures
+severity: silent-failure
+tags:
+  - github-context
+  - head-commit
+  - workflow-dispatch
+  - event-context
+  - commit-message
+  - null-context
+patterns:
+  - regex: 'github\.event\.head_commit\.message'
+    flags: 'i'
+  - regex: 'github\.event\.head_commit\b'
+    flags: 'i'
+error_messages:
+  - "contains(github.event.head_commit.message, ...) returns false on workflow_dispatch"
+  - "github.event.head_commit is null"
+root_cause: |
+  The `github.event.head_commit` context object is only populated on `push` events.
+  On all other trigger types — `workflow_dispatch`, `pull_request`, `pull_request_target`,
+  `schedule`, `workflow_call`, `workflow_run`, `release`, and others — the property is
+  null, and all child fields evaluate to empty string `""` in expressions.
+
+  A very common workflow pattern is to gate deployment or release steps based on the
+  commit message:
+
+    if: contains(github.event.head_commit.message, '[deploy]')
+
+  When this condition is evaluated on a `workflow_dispatch` run, a scheduled run, or
+  any non-push trigger, `github.event.head_commit` is null and `contains()` receives
+  an empty string. The expression silently returns false and the step is skipped.
+
+  No error, no warning, and no indication in the workflow log that the condition was
+  never evaluated against real commit message data. Developers manually triggering the
+  workflow see their step silently skipped with no explanation.
+
+  This is particularly confusing because:
+  - The workflow completes successfully with a green checkmark
+  - The step appears in the log as skipped with no reason given
+  - Manual `workflow_dispatch` runs show no null-context warning
+fix: |
+  Guard the commit message check with an explicit event type condition, or provide a
+  workflow_dispatch input as an equivalent gate for manual runs.
+fix_code:
+  - language: yaml
+    label: "Guard commit message check to push events only"
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Deploy on tagged commit message
+              # Only evaluate head_commit.message on push events where it is defined
+              if: >-
+                github.event_name == 'push' &&
+                contains(github.event.head_commit.message, '[deploy]')
+              run: ./scripts/deploy.sh
+  - language: yaml
+    label: "Support push and manual dispatch with input fallback"
+    code: |
+      on:
+        push:
+          branches: [main]
+        workflow_dispatch:
+          inputs:
+            deploy:
+              description: 'Trigger deployment manually'
+              type: boolean
+              default: false
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Resolve deploy flag
+              id: flag
+              run: |
+                if [[ "${{ github.event_name }}" == "push" ]]; then
+                  MSG="${{ github.event.head_commit.message }}"
+                  echo "enabled=$([[ "$MSG" == *'[deploy]'* ]] && echo true || echo false)" >> $GITHUB_OUTPUT
+                else
+                  echo "enabled=${{ inputs.deploy }}" >> $GITHUB_OUTPUT
+                fi
+
+            - name: Deploy
+              if: steps.flag.outputs.enabled == 'true'
+              run: ./scripts/deploy.sh
+prevention:
+  - "Never use `github.event.head_commit.*` without first checking `github.event_name == 'push'`"
+  - "Use `workflow_dispatch` inputs with boolean type as the manual-trigger equivalent of commit-message gates"
+  - "Document which events activate each step — add inline comments explaining gating conditions"
+  - "Test multi-trigger workflows by manually running them and verifying steps behave as expected"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#push"
+    label: "GitHub Actions push event — head_commit availability"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/contexts#github-context"
+    label: "GitHub context reference — github.event object"

package/errors/silent-failures/timeout-minutes-result-cancelled-not-failure.yml

@@ -0,0 +1,95 @@
+id: silent-failures-096
+title: "Job timeout-minutes sets result to 'cancelled' not 'failure' — if: failure() notification jobs silently skip timed-out jobs"
+category: silent-failures
+severity: silent-failure
+tags:
+  - timeout-minutes
+  - job-result
+  - if-failure
+  - notification
+  - cancelled
+  - cleanup-job
+patterns:
+  - regex: 'if:.*failure\(\)'
+    flags: 'i'
+  - regex: 'timeout-minutes:\s*\d+'
+    flags: 'i'
+error_messages:
+  - "This step was skipped because a previous step failed"
+  - "notification job skipped — upstream job timed out but result is 'cancelled' not 'failure'"
+root_cause: |
+  When a job exceeds its `timeout-minutes:` limit, GitHub Actions cancels the job and
+  sets its `result` to `"cancelled"` — NOT `"failure"`. This is a consistent but
+  widely misunderstood behavior.
+
+  A standard pattern is to add a notification or cleanup job that runs when builds fail:
+
+    notify:
+      needs: build
+      if: failure()
+      runs-on: ubuntu-latest
+
+  The `failure()` status check function returns true only when at least one upstream job
+  has result `"failure"`. It does NOT match `"cancelled"`. When `build` times out,
+  `needs.build.result` is `"cancelled"`, so `if: failure()` evaluates to false and
+  the notification job is silently skipped.
+
+  The four terminal job result values are: "success", "failure", "cancelled", "skipped".
+  The built-in functions map to:
+  - `failure()` → true when any upstream job result is "failure"
+  - `cancelled()` → true when any upstream job result is "cancelled"
+  - `success()` → true when all upstream jobs result in "success" (default)
+  - `always()` → always true regardless of upstream results
+
+  Developers are often surprised that a timed-out build does not trigger their alerting
+  job. The UI shows the timed-out job in orange ("Cancelled"), while the notification
+  job appears grey ("Skipped") — there is no direct indication that the skip is due to
+  the timeout rather than an unrelated condition.
+fix: |
+  Expand the notification job condition to explicitly cover both `failure` and `cancelled`
+  results, using `always()` to ensure the job runs regardless of upstream outcomes.
+fix_code:
+  - language: yaml
+    label: "Catch both failure and timeout (cancelled) in notification job"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          timeout-minutes: 30
+          steps:
+            - uses: actions/checkout@v4
+            - run: make build
+
+        notify:
+          needs: build
+          # Use always() so the job runs; then check for failure OR cancelled (timeout)
+          if: always() && (needs.build.result == 'failure' || needs.build.result == 'cancelled')
+          runs-on: ubuntu-latest
+          steps:
+            - name: Send alert
+              run: |
+                echo "Build result: ${{ needs.build.result }}"
+                # call your notification webhook here
+  - language: yaml
+    label: "Multi-job pipeline — catch any non-success terminal state"
+    code: |
+      jobs:
+        report:
+          needs: [build, test, deploy]
+          if: >-
+            always() &&
+            (contains(needs.*.result, 'failure') ||
+             contains(needs.*.result, 'cancelled'))
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Pipeline did not complete successfully"
+prevention:
+  - "Replace bare `if: failure()` with `if: always() && (needs.X.result == 'failure' || needs.X.result == 'cancelled')` whenever upstream jobs have `timeout-minutes:` set"
+  - "Treat `timeout-minutes` as a cancellation mechanism — timed-out jobs report `cancelled` not `failure`"
+  - "Test your notification path by temporarily reducing `timeout-minutes` to confirm the alerting logic fires on timeout"
+  - "Document in team runbooks that CI timeouts appear orange ('Cancelled') not red ('Failed') in the Actions UI"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/using-conditions-to-control-job-execution"
+    label: "GitHub Actions — status check functions (failure, cancelled, always)"
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idtimeout-minutes"
+    label: "GitHub Actions workflow syntax — timeout-minutes"

package/errors/yaml-syntax/workflow-dispatch-input-type-object-invalid.yml

@@ -0,0 +1,84 @@
+id: yaml-syntax-067
+title: 'workflow_dispatch input type: object is not valid — "Unexpected value" validation error'
+category: yaml-syntax
+severity: error
+tags:
+  - workflow_dispatch
+  - inputs
+  - type-object
+  - validation-error
+  - yaml
+patterns:
+  - regex: 'on\.workflow_dispatch\.inputs\.\w+\.type.*Unexpected value'
+    flags: 'i'
+  - regex: "Unexpected value 'object'"
+    flags: 'i'
+  - regex: 'Input type .object. is not supported'
+    flags: 'i'
+error_messages:
+  - "Invalid workflow file: on.workflow_dispatch.inputs.config.type: Unexpected value 'object'"
+  - "Invalid workflow file: .github/workflows/deploy.yml: Unexpected value 'object'"
+root_cause: |
+  `workflow_dispatch` inputs support only five types: `string`, `boolean`, `choice`,
+  `environment`, and `number`. There is no `object` type. Developers attempting to pass
+  complex structured data (JSON objects, arrays) via a workflow_dispatch input often
+  try `type: object`, which causes an immediate YAML schema validation error and
+  prevents the workflow from running at all.
+
+  The valid type list:
+  - string      — plain text value
+  - boolean     — true/false checkbox in UI
+  - choice      — dropdown from a fixed options list
+  - environment — GitHub environment picker
+  - number      — numeric value (coerced to string at runtime)
+
+  There is no object, array, list, or json type for workflow_dispatch inputs.
+  The workflow file fails validation and does not appear as runnable in the
+  Actions UI.
+fix: |
+  Use `type: string` and serialize the complex data as a JSON string. Parse it inside
+  the workflow using the `fromJSON()` expression function or `jq` in a run step.
+fix_code:
+  - language: yaml
+    label: 'Pass complex data as a JSON string — use type: string, not type: object'
+    code: |
+      on:
+        workflow_dispatch:
+          inputs:
+            config:
+              type: string          # NOT type: object
+              description: 'JSON config e.g. {"env":"prod","replicas":3}'
+              default: '{}'
+              required: false
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Parse config input
+              run: |
+                ENV=$(echo '${{ inputs.config }}' | jq -r .env)
+                REPLICAS=$(echo '${{ inputs.config }}' | jq -r .replicas)
+                echo "Deploying to $ENV with $REPLICAS replicas"
+  - language: yaml
+    label: 'Access nested fields with fromJSON() in expressions'
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          env:
+            ENV_NAME: ${{ fromJSON(inputs.config).env }}
+          steps:
+            - run: echo "Environment is $ENV_NAME"
+prevention:
+  - 'Only use type: string, boolean, choice, environment, or number for workflow_dispatch inputs'
+  - 'For structured data, serialize as a JSON string and parse inside the job with jq or fromJSON()'
+  - 'Use actionlint to catch unsupported input types before pushing the workflow file'
+  - 'Document the expected JSON schema in the input description field so callers know the format'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_dispatch'
+    label: 'GitHub Docs — workflow_dispatch inputs (valid types: string, boolean, choice, environment, number)'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/evaluate-expressions-in-workflows-and-actions#fromjson'
+    label: 'GitHub Docs — fromJSON() expression function'
+  - url: 'https://stackoverflow.com/questions/76181396/github-actions-workflow-with-input-type-object-not-running'
+    label: 'Stack Overflow — workflow_dispatch with input type object not running'

package/package.json

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