@htekdev/actions-debugger 1.0.108 → 1.0.109

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/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.108",
+  "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",