@htekdev/actions-debugger 1.0.90 → 1.0.92

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

@@ -0,0 +1,86 @@
+id: caching-artifacts-051
+title: 'download-artifact@v4 places each artifact in a named subdirectory, breaking v3 flat path assumption'
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - download-artifact
+  - v4-migration
+  - directory-structure
+  - breaking-change
+  - path
+patterns:
+  - regex: 'Downloading artifact.*to.*'
+    flags: 'i'
+  - regex: 'ENOENT.*no such file or directory'
+    flags: 'i'
+  - regex: 'no such file or directory.*dist\/'
+    flags: 'i'
+error_messages:
+  - "Downloading artifact: my-artifact to /home/runner/work/repo/dist"
+  - "Error: ENOENT: no such file or directory, open 'dist/index.js'"
+  - "Error: Cannot find module '/home/runner/work/repo/dist/index.js'"
+  - "cp: cannot stat 'dist/main.js': No such file or directory"
+root_cause: |
+  In actions/download-artifact@v3, downloading a named artifact with `path: dist`
+  placed files directly inside the `dist/` directory (flat layout). In v4,
+  the action changed to place each artifact in a subdirectory named after the
+  artifact: files land at `dist/<artifact-name>/filename` instead of `dist/filename`.
+
+  This is a silent failure: the `download-artifact` step succeeds with exit code 0
+  and emits no warning about the path change. Downstream steps that reference
+  `dist/index.js` fail with "no such file" errors — the file is actually at
+  `dist/my-artifact/index.js`. The behavior is especially confusing in matrix
+  workflows where each job uploads an artifact with a unique name, and the
+  consuming job downloads all artifacts into a single `path:`.
+
+  The change was made to support downloading multiple artifacts into the same
+  `path:` without name collisions, but it breaks any workflow that migrated from
+  v3 without adjusting downstream path references.
+fix: |
+  Option 1 (recommended): Set the `path:` to a staging directory and reference
+  files using the artifact subdirectory path, or use `merge-multiple: true` to
+  flatten all artifacts into the `path:` directory.
+
+  Option 2: Name the artifact the same as the target directory and download into
+  the parent, so the subdirectory becomes the expected location.
+
+  Option 3: Add a step to move the artifact contents up one level after download.
+fix_code:
+  - language: yaml
+    label: 'Use merge-multiple: true to restore v3 flat behavior for single artifact'
+    code: |
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist-bundle
+          path: dist
+          merge-multiple: true   # Flattens into dist/ directly, matching v3 behavior
+  - language: yaml
+    label: 'Adjust downstream path to include artifact subdirectory'
+    code: |
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist-bundle
+          path: staging
+
+      # Files land at staging/dist-bundle/index.js — reference accordingly
+      - run: node staging/dist-bundle/index.js
+  - language: yaml
+    label: 'Download all matrix artifacts and merge into one directory'
+    code: |
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: build-*        # Matches all matrix artifacts
+          path: dist
+          merge-multiple: true   # All files merged flat into dist/
+prevention:
+  - "When migrating from download-artifact@v3 to v4, audit all `path:` references and downstream file access patterns"
+  - "Use `merge-multiple: true` if you need the v3 flat download behavior for a single named artifact"
+  - "Set `path:` to a staging directory and explicitly reference the `path/<artifact-name>/` subdirectory in downstream steps"
+  - "Run the workflow once after migrating and check the action log for 'Downloading artifact: X to Y' to verify the actual destination path"
+docs:
+  - url: 'https://github.com/actions/download-artifact/blob/main/docs/migration-guide.md'
+    label: 'download-artifact migration guide: v3 to v4 breaking changes'
+  - url: 'https://github.com/actions/download-artifact?tab=readme-ov-file#inputs'
+    label: 'download-artifact@v4 inputs reference — merge-multiple option'
+  - url: 'https://github.com/actions/upload-artifact/discussions/562'
+    label: 'Community discussion: v4 directory structure change from v3'

package/errors/permissions-auth/permissions-auth-051.yml

@@ -0,0 +1,103 @@
+id: permissions-auth-051
+title: 'GITHUB_TOKEN push blocked by repository ruleset despite contents: write permission'
+category: permissions-auth
+severity: error
+tags:
+  - github-token
+  - rulesets
+  - contents-write
+  - branch-protection
+  - bypass-list
+patterns:
+  - regex: 'GH013: Repository rule violations found for refs\/'
+    flags: 'i'
+  - regex: 'remote: error: Changes must be made through a pull request'
+    flags: 'i'
+  - regex: 'refusing to allow.*to create or update'
+    flags: 'i'
+error_messages:
+  - "remote: error: GH013: Repository rule violations found for refs/heads/main."
+  - "remote: error: GH013: Repository rule violations found for refs/tags/v1.0.0."
+  - "remote: error: Changes must be made through a pull request."
+  - "error: failed to push some refs to 'https://github.com/ORG/REPO.git'"
+  - "refusing to allow a GitHub App to create or update file"
+root_cause: |
+  GitHub Rulesets (generally available January 2025) allow organization and repository
+  administrators to define push rules that enforce requirements such as "all pushes
+  must come through a pull request", "signed commits required", or "tag patterns
+  must match a format". Unlike legacy branch protection rules, rulesets apply to
+  ALL actors including GitHub Apps and the GITHUB_TOKEN by default — regardless of
+  the `contents: write` permission granted in the workflow's `permissions:` block.
+
+  The `contents: write` permission only controls whether the token is *authorized*
+  to make write API calls; it does not grant exemption from repository rulesets.
+  Rulesets have a separate "bypass list" in Settings > Rules > Rulesets that must
+  explicitly include "GitHub Actions" (or a specific GitHub App) to allow workflow
+  pushes to bypass ruleset restrictions.
+
+  This error affects workflows that push commits directly (e.g., auto-format,
+  changelog generation, version bump commits) or push tags (e.g., release tagging)
+  to branches or tags governed by a ruleset.
+fix: |
+  Option 1 (recommended): Add GitHub Actions to the ruleset bypass list.
+  Go to Settings > Rules > Rulesets > (select the ruleset) > Bypass list >
+  Add bypass > select "GitHub Actions". This allows workflow GITHUB_TOKEN
+  pushes to bypass the ruleset.
+
+  Option 2: Use a Personal Access Token (PAT) or GitHub App token from a user
+  account that is in the bypass list. Pass the token via a secret and use it
+  in the push step.
+
+  Option 3: Restructure the workflow to push via a pull request instead of
+  directly to the protected branch, satisfying the "PR required" ruleset rule.
+fix_code:
+  - language: yaml
+    label: 'Use a PAT secret to push when GITHUB_TOKEN is blocked by rulesets'
+    code: |
+      jobs:
+        release:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                token: ${{ secrets.RELEASE_PAT }}  # PAT from bypass-listed account
+                fetch-depth: 0
+
+            # ... version bump or commit steps ...
+
+            - name: Push release commit and tag
+              env:
+                GITHUB_TOKEN: ${{ secrets.RELEASE_PAT }}
+              run: |
+                # Use the PAT-authenticated remote for push
+                echo "Push authorized via PAT from bypass-listed account"
+  - language: yaml
+    label: 'Use a GitHub App token with bypass list membership'
+    code: |
+      jobs:
+        release:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/create-github-app-token@v2
+              id: app-token
+              with:
+                app-id: ${{ vars.RELEASE_APP_ID }}
+                private-key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}
+
+            - uses: actions/checkout@v4
+              with:
+                token: ${{ steps.app-token.outputs.token }}
+
+            # Push step uses the App token — ensure the App is in bypass list
+prevention:
+  - "When enabling rulesets on a repository or organization, immediately check CI/CD workflows that push directly to protected branches or tags"
+  - "Add GitHub Actions to ruleset bypass lists proactively when creating rulesets that restrict direct pushes"
+  - "Prefer pushing via pull requests (open PR, auto-merge) over direct commits in automated workflows — this satisfies 'PR required' rules and avoids bypass list management"
+  - "Audit existing legacy branch protection rules when migrating to rulesets — bypass behavior differs: branch protection 'Restrict who can push' exempts admins by default; rulesets do not"
+docs:
+  - url: 'https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets'
+    label: 'GitHub Docs: Available rules for rulesets'
+  - url: 'https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/creating-rulesets-for-a-repository#granting-bypass-permissions-for-your-ruleset'
+    label: 'GitHub Docs: Granting bypass permissions for a ruleset'
+  - url: 'https://github.blog/changelog/2025-01-29-github-rulesets-are-generally-available/'
+    label: 'GitHub Changelog: Rulesets generally available — January 2025'

package/errors/runner-environment/runner-environment-157.yml

@@ -0,0 +1,92 @@
+id: runner-environment-157
+title: 'setup-python EOL Python version triggers slow pyenv compilation on ubuntu-24.04'
+category: runner-environment
+severity: warning
+tags:
+  - setup-python
+  - pyenv
+  - ubuntu-24.04
+  - python-version
+  - toolcache
+  - build-time
+patterns:
+  - regex: 'Version \d+\.\d+\.\d+ was not found in the local cache'
+    flags: 'i'
+  - regex: 'pyenv install python-\d+\.\d+\.\d+'
+    flags: 'i'
+  - regex: 'python-build: .*not installed'
+    flags: 'i'
+error_messages:
+  - "Version 3.8.20 was not found in the local cache"
+  - "Version 3.9.19 was not found in the local cache"
+  - "pyenv install python-3.8.20"
+  - "python-build: python not found in PATH"
+  - "Successfully installed cpython: 3.9.18 (took: 523.19 seconds)"
+root_cause: |
+  ubuntu-24.04 runners ship with Python 3.11, 3.12, and 3.13 in the pre-installed
+  toolcache. Python 3.8 (EOL October 2024), 3.9, and 3.10 were removed from the
+  ubuntu-24.04 toolcache entirely. When actions/setup-python requests one of these
+  versions, it cannot find a cached build and falls back to compiling Python from
+  source via pyenv. The compilation process — downloading Python source, running
+  ./configure, make, make install with GCC — typically takes 5–10 minutes and can
+  exhaust the default 6-hour job timeout in heavily parallelized pipelines or
+  cause unexpectedly slow CI on free-tier runners. The warning "Version X was not
+  found in the local cache" is emitted but easy to miss in long logs, and the
+  action still exits 0 on success, making the slowdown invisible until CI bills
+  or timeout failures appear.
+fix: |
+  Option 1 (recommended): Upgrade to a Python version pre-installed on ubuntu-24.04
+  (3.11, 3.12, or 3.13). These are available instantly from the toolcache.
+
+  Option 2: Pin the runner to ubuntu-22.04, which retains Python 3.9 and 3.10
+  in the toolcache through its support window.
+
+  Option 3: Add the deadsnakes PPA before calling setup-python to provide fast
+  pre-built binaries for older Python versions on ubuntu-24.
+
+  Option 4: Use a container image that pre-bundles your Python version to avoid
+  the toolcache entirely.
+fix_code:
+  - language: yaml
+    label: 'Upgrade to a toolcache-available Python version'
+    code: |
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'   # Pre-installed on ubuntu-24.04; no pyenv fallback
+  - language: yaml
+    label: 'Use ubuntu-22.04 runner if 3.9 or 3.10 is required'
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-22.04    # Retains Python 3.9/3.10 in toolcache
+          steps:
+            - uses: actions/setup-python@v5
+              with:
+                python-version: '3.10'
+  - language: yaml
+    label: 'Deadsnakes PPA for fast pre-built older Python on ubuntu-24.04'
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-24.04
+          steps:
+            - name: Add deadsnakes PPA
+              run: |
+                sudo add-apt-repository ppa:deadsnakes/ppa
+                sudo apt-get update
+                sudo apt-get install -y python3.9 python3.9-venv python3.9-dev
+            - uses: actions/setup-python@v5
+              with:
+                python-version: '3.9'
+prevention:
+  - "Avoid pinning `python-version` to EOL releases (3.8 EOL Oct 2024, 3.9 EOL Oct 2025)"
+  - "Check the ubuntu-24.04 runner toolcache inventory at github.com/actions/runner-images for available Python versions"
+  - "Use `python-version-file: .python-version` or `pyproject.toml` to track the project's minimum supported version and update it when runners drop EOL toolcache entries"
+  - "Set a `timeout-minutes` on the job so pyenv compilation failures surface quickly rather than running for hours"
+docs:
+  - url: 'https://github.com/actions/setup-python/issues/726'
+    label: 'setup-python: Python 3.8/3.9 not found in toolcache on ubuntu-24.04'
+  - url: 'https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2404-Readme.md'
+    label: 'ubuntu-24.04 runner image readme — pre-installed Python versions'
+  - url: 'https://devguide.python.org/versions/'
+    label: 'Python release lifecycle — EOL dates by version'

package/errors/runner-environment/windows-max-path-260-npm-build-failure.yml

@@ -0,0 +1,87 @@
+id: runner-environment-158
+title: 'Windows MAX_PATH 260-character limit causes npm and build tool failures'
+category: runner-environment
+severity: error
+tags:
+  - windows
+  - max-path
+  - npm
+  - node_modules
+  - path-length
+  - enoent
+  - build
+patterns:
+  - regex: 'The filename or extension is too long'
+    flags: 'i'
+  - regex: 'ENOENT.*node_modules.*node_modules'
+    flags: 'i'
+  - regex: 'error MSB3095.*path.*too long'
+    flags: 'i'
+  - regex: 'The system cannot find the path specified'
+    flags: 'i'
+error_messages:
+  - "The filename or extension is too long."
+  - "ENOENT: no such file or directory, open 'C:\\Users\\runner\\work\\..."
+  - "error MSB3095: Invalid argument. 'path' is too long."
+  - "npm ERR! path C:\\Users\\runner\\work\\..."
+root_cause: |
+  Windows enforces a 260-character maximum path length (MAX_PATH) inherited from
+  the Win32 API. Deep node_modules dependency trees easily exceed this limit: the
+  GitHub-hosted runner workspace is already at
+  C:\Users\runner\work\<repository>\<repository>\ (~50 characters) before any
+  source files are added. A typical transitive npm dependency path like
+  node_modules\pkg\node_modules\sub\node_modules\deep\index.js can push the total
+  well past 260 characters. MSBuild, Java build tools, and other Windows toolchains
+  have the same limitation.
+
+  GitHub-hosted Windows runners (windows-2022, windows-latest) have the
+  LongPathsEnabled registry key set to 1 at the OS level, but Git must still be
+  separately configured with core.longpaths = true, and some Node.js internal APIs
+  call the legacy Win32 CreateFile path which ignores the registry opt-in unless
+  the application explicitly declares long-path awareness in its executable manifest.
+  The result is ENOENT or "path too long" failures that appear to indicate missing
+  files rather than a path-length limit.
+fix: |
+  Option 1 (most effective): Use a short path: in actions/checkout to reduce the
+  base path length. path: a sets the workspace to C:\...\work\repo\a.
+  Option 2: Configure Git long paths and use --legacy-peer-deps to flatten
+  npm dependency nesting.
+  Option 3: Shorten the repository name, which directly reduces the workspace
+  path length.
+fix_code:
+  - language: yaml
+    label: 'Use short checkout path to reduce base path length'
+    code: |
+      jobs:
+        build:
+          runs-on: windows-latest
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                path: a   # Reduces base path by ~20-30 characters vs default
+            - run: npm ci
+              working-directory: a
+  - language: yaml
+    label: 'Enable Git long paths and flatten npm tree'
+    code: |
+      jobs:
+        build:
+          runs-on: windows-latest
+          steps:
+            - name: Configure Git long paths
+              run: git config --global core.longpaths true
+            - uses: actions/checkout@v4
+            - name: Install with flattened dependencies
+              run: npm ci --legacy-peer-deps
+prevention:
+  - 'Use path: a (or another single-char name) in actions/checkout to reduce baseline path length on Windows'
+  - 'Keep GitHub repository names short when Windows CI is required'
+  - 'Avoid deeply nested workspace directory structures'
+  - 'Run npm ci --legacy-peer-deps to reduce node_modules nesting on npm 7+ which introduced deeper trees'
+docs:
+  - url: 'https://learn.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation'
+    label: 'Microsoft Docs: Maximum file path limitation (MAX_PATH)'
+  - url: 'https://git-scm.com/docs/git-config#Documentation/git-config.txt-coreprotectNTFS'
+    label: 'Git: core.longpaths config'
+  - url: 'https://docs.npmjs.com/cli/v10/commands/npm-ci'
+    label: 'npm ci — clean install'

package/errors/silent-failures/pull-request-branches-filter-not-inherited.yml

@@ -0,0 +1,73 @@
+id: silent-failures-086
+title: 'on.pull_request does not inherit branches filter from sibling on.push trigger'
+category: silent-failures
+severity: silent-failure
+tags:
+  - pull_request
+  - push
+  - branches-filter
+  - trigger
+  - unexpected-runs
+  - filter-inheritance
+patterns:
+  - regex: 'on:\s*\n\s*push:\s*\n\s*branches:\s*\n.*\n\s*pull_request:\s*\n(?!\s*branches:)'
+    flags: 'ms'
+error_messages: []
+root_cause: |
+  When a workflow defines multiple triggers under on:, each trigger's configuration
+  is fully independent — there is no filter inheritance between sibling triggers.
+  A common pattern is to restrict on.push to specific branches (e.g., main,
+  release/**) while adding on.pull_request with no branches: key, expecting the
+  PR trigger to respect the same branch scope.
+
+  In YAML mapping semantics, on.push.branches: [main] applies exclusively to push
+  events. on.pull_request with no branches: key means "trigger for pull requests
+  targeting ANY branch in the repository." This causes the workflow to run on every
+  PR opened against feature branches, release candidates, or any other branch —
+  running expensive CI on PRs the developer intended to exclude.
+
+  The GitHub Actions UI shows these runs as triggered by pull_request with no
+  indication that the branches: filter was missing. The behavior appears correct
+  (workflow ran) but occurs on unintended PRs.
+fix: |
+  Explicitly add a branches: filter to on.pull_request that defines the target
+  branches for which CI should run. Note that on.pull_request.branches matches the
+  BASE branch (the branch the PR targets), not the head/feature branch.
+fix_code:
+  - language: yaml
+    label: 'Explicit branches filter on both triggers'
+    code: |
+      on:
+        push:
+          branches: [main, 'release/**']
+        pull_request:
+          branches: [main, 'release/**']  # Required — NOT inherited from on.push
+      jobs:
+        ci:
+          runs-on: ubuntu-latest
+          steps:
+            - run: npm test
+  - language: yaml
+    label: 'Common mistake — missing branches on pull_request'
+    code: |
+      # WRONG — pull_request triggers for ALL target branches
+      on:
+        push:
+          branches: [main]
+        pull_request:           # No branches filter — triggers for every PR
+      # CORRECT
+      on:
+        push:
+          branches: [main]
+        pull_request:
+          branches: [main]      # Only PRs targeting main
+prevention:
+  - 'Review each trigger block independently — on.push and on.pull_request filters are never shared'
+  - 'Add an explicit branches: under on.pull_request whenever you use branches: under on.push'
+  - 'Remember: on.pull_request.branches matches the BASE branch of the PR, not the feature branch'
+  - 'Use actionlint to validate trigger configurations before committing'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#using-filters'
+    label: 'GitHub Docs: Using filters — each trigger is configured independently'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#onpull_requestpull_request_targetbranchesbranches-ignore'
+    label: 'GitHub Actions: pull_request branches filter matches base branch'

package/errors/triggers/delete-event-fires-branch-and-tag.yml

@@ -0,0 +1,75 @@
+id: triggers-061
+title: 'on.delete fires for branch and tag deletion — no ref_type filter at trigger level'
+category: triggers
+severity: silent-failure
+tags:
+  - delete
+  - ref_type
+  - branch
+  - tag
+  - unexpected-runs
+patterns:
+  - regex: 'on:\s*\n\s*delete:'
+    flags: 'ms'
+error_messages: []
+root_cause: |
+  The on.delete event fires whenever any branch or tag is deleted in the repository.
+  Unlike some events that support a types: activity filter, on.delete has no types
+  option — there is no trigger-level way to restrict it to branch deletions only or
+  tag deletions only. Workflows that perform branch-specific cleanup (removing
+  temporary deployment environments, rotating secrets, updating external project
+  boards, or archiving feature branch artifacts) run for EVERY tag deletion as well,
+  unless an explicit runtime condition is added inside the workflow.
+
+  The on.create event has the same dual-fire behavior (documented separately). Both
+  events expose github.event.ref_type in the workflow context as either 'branch' or
+  'tag', but this value is only available inside the workflow body — it cannot be
+  used as a trigger-level filter.
+
+  A common scenario: a workflow cleans up branch-specific cloud environments on
+  delete. When a developer deletes the release tag v1.2.3, the workflow fires
+  unexpectedly — potentially tearing down a production environment that was deployed
+  from that tag.
+fix: |
+  Add an if: condition using github.event.ref_type to guard jobs or steps that
+  should only execute for one type of deletion. Use 'branch' or 'tag' as the
+  comparison value.
+fix_code:
+  - language: yaml
+    label: 'Guard cleanup by ref_type at the job level'
+    code: |
+      on:
+        delete:
+      jobs:
+        cleanup-branch-environment:
+          # Only run for branch deletions — skip tag deletions
+          if: github.event.ref_type == 'branch'
+          runs-on: ubuntu-latest
+          steps:
+            - name: Remove branch-specific deployment
+              run: echo "Cleaning up env for branch ${{ github.event.ref }}"
+  - language: yaml
+    label: 'Separate jobs for branch vs tag deletion'
+    code: |
+      on:
+        delete:
+      jobs:
+        cleanup-branch:
+          if: github.event.ref_type == 'branch'
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Branch deleted ${{ github.event.ref }}"
+        cleanup-tag:
+          if: github.event.ref_type == 'tag'
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Tag deleted ${{ github.event.ref }}"
+prevention:
+  - 'Always guard on.delete workflow jobs with if: github.event.ref_type == ''branch'' or ''tag'''
+  - 'Be aware that on.create has the same behavior — both create and delete fire for branches and tags'
+  - 'Test delete workflows by deleting both a branch and a tag to verify they behave as expected'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#delete'
+    label: 'GitHub Docs: delete event — fires for branches and tags'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/contexts#github-context'
+    label: 'GitHub Docs: github.event.ref_type context'

package/errors/triggers/pull-request-review-all-types-default.yml

@@ -0,0 +1,69 @@
+id: triggers-062
+title: 'on.pull_request_review fires for all review types (submitted, edited, dismissed) when types is omitted'
+category: triggers
+severity: silent-failure
+tags:
+  - pull_request_review
+  - review
+  - types
+  - dismissed
+  - submitted
+  - unexpected-runs
+patterns:
+  - regex: 'on:\s*\n\s*pull_request_review:\s*\n(?!\s*types:)'
+    flags: 'ms'
+error_messages: []
+root_cause: |
+  The pull_request_review event fires for three activity types:
+    - submitted: a new review is posted (approved, changes_requested, or commented)
+    - edited: a reviewer edits their review comment text
+    - dismissed: an existing approval or changes_requested review is dismissed
+
+  When on.pull_request_review: is specified without a types: filter, GitHub fires
+  the workflow for ALL three activity types. Developers typically use this event to
+  trigger a deployment or notification on PR approval. Without types: [submitted],
+  the workflow also runs when a reviewer edits their comment spelling or when an
+  approval is dismissed by a maintainer — often causing incorrect or failed workflow
+  runs in contexts where the PR is no longer in an approved state.
+
+  This behavior mirrors on.pull_request without types: (which fires for opened,
+  synchronize, and reopened by default) but is arguably more surprising because
+  "editing a review comment" and "dismissing a review" are far less common
+  developer actions than submitting a new review.
+fix: |
+  Add types: [submitted] to restrict the trigger to new review submissions.
+  If you only want to react to approvals specifically, also add an if: condition
+  checking github.event.review.state == 'approved'.
+fix_code:
+  - language: yaml
+    label: 'Restrict to submitted reviews only'
+    code: |
+      on:
+        pull_request_review:
+          types: [submitted]   # Only new review submissions — not edited or dismissed
+      jobs:
+        notify-on-review:
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Review state ${{ github.event.review.state }}"
+  - language: yaml
+    label: 'Trigger only on PR approvals'
+    code: |
+      on:
+        pull_request_review:
+          types: [submitted]
+      jobs:
+        deploy-on-approval:
+          if: github.event.review.state == 'approved'
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "PR approved — proceeding with staging deploy"
+prevention:
+  - 'Always specify types: [submitted] under on.pull_request_review unless dismissed or edited is explicitly needed'
+  - 'Combine types: [submitted] with if: github.event.review.state == ''approved'' for approval-gated workflows'
+  - 'Test pull_request_review workflows by also dismissing reviews to ensure unexpected runs are avoided'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#pull_request_review'
+    label: 'GitHub Docs: pull_request_review event — activity types'
+  - url: 'https://docs.github.com/en/webhooks/webhook-events-and-payloads#pull_request_review'
+    label: 'GitHub Webhooks: pull_request_review payload — review.state values'

package/errors/yaml-syntax/yaml-syntax-057.yml

@@ -0,0 +1,93 @@
+id: yaml-syntax-057
+title: 'needs: referencing undefined job ID causes instant workflow validation failure'
+category: yaml-syntax
+severity: error
+tags:
+  - needs
+  - job-id
+  - validation
+  - typo
+  - workflow-syntax
+patterns:
+  - regex: "Job '.*' depends on unknown job '.*'"
+    flags: 'i'
+  - regex: "A job named '.*' does not exist in this workflow"
+    flags: 'i'
+  - regex: 'The workflow is not valid.*depends on unknown job'
+    flags: 'i'
+error_messages:
+  - "The workflow is not valid. .github/workflows/ci.yml (Line 42, Col 14): Job 'deploy' depends on unknown job 'biuld'."
+  - "A job named 'biuld' does not exist in this workflow."
+  - "Job 'release' depends on unknown job 'test-and-build'."
+  - "The workflow is not valid. .github/workflows/release.yml: Job 'publish' depends on unknown job 'build_and_test'."
+root_cause: |
+  The `needs:` key in a job definition must exactly reference the IDs of other jobs
+  defined under `jobs:` in the same workflow file. Job IDs are the YAML map keys
+  (e.g., `jobs.build:`, `jobs.test:`), not the `name:` display values.
+
+  A typo in a `needs:` value (e.g., `needs: [biuld]` instead of `needs: [build]`,
+  or `needs: test-and-build` when the job is named `test_and_build`) causes GitHub
+  Actions to reject the entire workflow at parse time with a validation error.
+  No jobs run — the workflow fails before any step executes.
+
+  This error is particularly common after renaming jobs, since the `name:` field
+  (display name in the UI) can be changed without affecting the job ID used in
+  `needs:`. Developers who update `name:` but forget to update downstream `needs:`
+  references see the workflow fail immediately on next push with no prior warning.
+fix: |
+  Ensure every value in `needs:` exactly matches a job ID key defined at the
+  same level under `jobs:`. Job IDs are case-sensitive and use the exact YAML key
+  name — not the `name:` display value.
+
+  Use `actionlint` locally or in pre-commit hooks to catch unknown `needs:` references
+  before pushing.
+fix_code:
+  - language: yaml
+    label: 'Correct needs: to match the exact job ID key'
+    code: |
+      jobs:
+        build:          # <-- This is the job ID (the YAML key)
+          name: Build and Test   # This is the display name — NOT used in needs:
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "building"
+
+        deploy:
+          needs: [build]   # Must reference the job ID key, not the name: value
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "deploying"
+  - language: yaml
+    label: 'Rename both job ID and needs: reference after a job rename'
+    code: |
+      # WRONG — job was renamed from 'build' to 'build-and-test' but needs: not updated
+      # jobs:
+      #   build-and-test:
+      #     ...
+      #   deploy:
+      #     needs: [build]   # Error: 'build' no longer exists
+
+      # CORRECT — update needs: to match the new job ID
+      jobs:
+        build-and-test:
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "building"
+
+        deploy:
+          needs: [build-and-test]   # Updated to match renamed job ID
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "deploying"
+prevention:
+  - "Use `actionlint` (rhysd/actionlint) locally or as a pre-commit hook — it validates `needs:` references against defined job IDs at lint time"
+  - "Keep job IDs short and stable (e.g., `build`, `test`, `deploy`); use the `name:` field for human-readable display names that can be changed freely"
+  - "When renaming a job ID, search the entire workflow file for all `needs:` references to that ID before committing"
+  - "Enable the actionlint GitHub Actions workflow check in your repository to catch validation errors in PRs before merge"
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idneeds'
+    label: 'GitHub Docs: jobs.<job_id>.needs syntax'
+  - url: 'https://rhysd.github.io/actionlint/'
+    label: 'actionlint — static checker for GitHub Actions workflow files'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idname'
+    label: 'GitHub Docs: jobs.<job_id>.name vs job ID distinction'

package/package.json

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