@htekdev/actions-debugger 1.0.54 → 1.0.56

package/errors/known-unsolved/known-unsolved-037.yml

@@ -0,0 +1,124 @@
+id: known-unsolved-037
+title: "Skipped jobs show as 'skipped' — branch protection required status checks block PR merge"
+category: known-unsolved
+severity: limitation
+tags:
+  - required-status-checks
+  - branch-protection
+  - skipped
+  - conditional-job
+  - merge-blocked
+  - known-limitation
+patterns:
+  - regex: 'if:\s+github\.event_name\s+!=\s+'
+    flags: i
+  - regex: 'if:\s+\$\{\{\s*github\.event_name\s*!=\s*'
+    flags: i
+error_messages:
+  - "Required status check 'ci/test' was not successful — status: skipped"
+  - "Branch protection rule requires passing status checks before merging"
+root_cause: |
+  When a job's if: condition evaluates to false, GitHub Actions marks that job as
+  "Skipped" in the Checks API. Branch protection rules that require a specific check
+  to pass only accept a conclusion of "success" — not "skipped", "cancelled", or
+  "neutral".
+
+  This creates a practical trap: a team sets up a required check for a job like
+  ci/test, then later adds an if: condition to skip that job on certain events
+  (for example, to avoid running tests on tag pushes or documentation-only changes).
+  The conditional logic is correct for workflow execution, but the skipped conclusion
+  permanently blocks all PRs where that condition evaluates to false.
+
+  GitHub has documented this as intentional: a skipped job is not a successful job.
+  There is no configuration option to treat "skipped" as equivalent to "success" for
+  branch protection purposes as of 2026. The workaround requires a structural change
+  to the workflow.
+fix: |
+  This is a known limitation with no direct fix. The recommended workarounds are:
+
+  1. ALWAYS-PASS WRAPPER JOB: Create a wrapper job that always runs and reports
+     the real outcome. The wrapper job becomes the required status check instead of
+     the real CI job. If CI was skipped (e.g., docs-only change), the wrapper passes.
+     If CI ran and failed, the wrapper fails.
+
+  2. MOVE THE CONDITION INSIDE THE JOB: Instead of using if: at the job level, keep
+     the job always running and use if: at the step level. An empty job always
+     succeeds, so the required status check passes.
+
+  3. PATHS FILTER PATTERN (dorny/paths-filter): Use a separate filtering job and
+     pass its output as a condition parameter to downstream jobs while keeping a
+     pass-through job for status check reporting.
+
+  4. RE-EVALUATE THE REQUIRED CHECK: If the check is truly optional for some events,
+     consider removing it from required status checks and instead enforce it only at
+     the merge queue level.
+fix_code:
+  - language: yaml
+    label: "Problem: conditional job is skipped, blocking required status check"
+    code: |
+      on: [push, pull_request]
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          # This job is required in branch protection, but gets skipped on push to main
+          if: github.event_name == 'pull_request'
+          steps:
+            - run: npm test
+            # On push events, this job is SKIPPED, blocking required status check
+  - language: yaml
+    label: "Fix: always-pass wrapper job becomes the required status check"
+    code: |
+      on: [push, pull_request]
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          if: github.event_name == 'pull_request'
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm test
+
+        # Set THIS job as the required status check in branch protection
+        ci-status:
+          runs-on: ubuntu-latest
+          needs: [test]
+          if: always()
+          steps:
+            - name: Report CI result
+              run: |
+                result="${{ needs.test.result }}"
+                if [[ "$result" == "success" || "$result" == "skipped" ]]; then
+                  echo "CI passed or was intentionally skipped — OK to merge"
+                else
+                  echo "CI failed (result: $result)"
+                  exit 1
+                fi
+  - language: yaml
+    label: "Alternative: move condition inside job so job always runs and passes when empty"
+    code: |
+      on: [push, pull_request]
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          # No if: at job level — job always runs and always produces a conclusion
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Run tests (pull_request only)
+              if: github.event_name == 'pull_request'
+              run: npm test
+              # If step is skipped, job still succeeds — required check passes
+prevention:
+  - "Never add an if: condition to a job that is a required status check — use a wrapper job instead"
+  - "Use the always-pass wrapper pattern from the start when adding new required status checks"
+  - "Test required check behavior by creating a draft PR that intentionally triggers the skip condition"
+  - "Document which jobs are required status checks in a comment at the top of the workflow file"
+docs:
+  - url: "https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/troubleshooting-required-status-checks"
+    label: "GitHub Docs: Troubleshooting required status checks"
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idif"
+    label: "GitHub Docs: Job-level if conditions"
+  - url: "https://github.com/dorny/paths-filter"
+    label: "dorny/paths-filter: Conditional execution with status reporting"

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

@@ -0,0 +1,142 @@
+id: permissions-auth-040
+title: "GITHUB_TOKEN is read-only by default in new repositories — write operations fail with 403"
+category: permissions-auth
+severity: error
+tags:
+  - GITHUB_TOKEN
+  - read-only
+  - permissions
+  - 403
+  - new-repo
+  - workflow-permissions
+patterns:
+  - regex: 'remote:\s*Permission to .* denied to github-actions\[bot\]'
+    flags: i
+  - regex: 'Error:\s*Resource not accessible by integration'
+    flags: i
+  - regex: 'HttpError:\s*Resource not accessible by integration'
+    flags: i
+  - regex: '403.*github-actions\[bot\]'
+    flags: i
+error_messages:
+  - "remote: Permission to org/repo.git denied to github-actions[bot]"
+  - "Error: Resource not accessible by integration"
+  - "HttpError: Resource not accessible by integration"
+  - "fatal: unable to access 'https://github.com/org/repo/': The requested URL returned error: 403"
+  - "GitHub Actions is not permitted to create or approve pull requests"
+root_cause: |
+  In February 2023 (GitHub Changelog), GitHub changed the default GITHUB_TOKEN
+  permissions for all new repositories and new organizations from read-write to
+  read-only. Repositories created before this change retain their original default
+  (read-write) unless an administrator explicitly changes the org-level setting.
+
+  This creates two failure scenarios:
+
+  1. COPIED WORKFLOWS: A developer copies a workflow from an older repo or a public
+     template that relies on the default read-write GITHUB_TOKEN (for example, to push
+     a build artifact, create a release, comment on a PR, or open a pull request). In a
+     new repo, that same workflow fails with 403 or "Resource not accessible by
+     integration" because the token only has read permissions.
+
+  2. ORG POLICY CHANGE: An organization administrator enables the read-only default
+     at the organization level (Settings > Actions > General > Workflow permissions).
+     All repos in the org immediately start failing any workflow that performs write
+     operations without an explicit permissions block.
+
+  The failure message is typically cryptic and does not mention that the root cause is
+  the workflow permissions default — it only says the token was denied.
+fix: |
+  Add explicit permissions blocks to workflows or jobs that perform write operations.
+  GitHub recommends the principle of least privilege: grant only the specific write
+  permission needed, not blanket read-write access.
+
+  At the workflow level, a top-level permissions: block sets defaults for all jobs.
+  At the job level, a permissions: block overrides the workflow-level default for that
+  job only. Job-level is preferred — it minimises the blast radius if a job is
+  compromised.
+
+  Common permissions needed:
+  - contents: write — push commits, create releases, upload release assets
+  - pull-requests: write — create/comment on pull requests
+  - issues: write — create/comment on issues
+  - packages: write — publish to GitHub Packages
+  - pages: write — deploy to GitHub Pages (also needs id-token: write for OIDC)
+
+  Alternatively, change the default at repo level: Settings > Actions > General >
+  Workflow permissions > Read and write permissions. Not recommended for security-
+  conscious teams.
+fix_code:
+  - language: yaml
+    label: "Problem: workflow relies on default write token, fails in new repos"
+    code: |
+      # No permissions block — relies on default, which is READ-ONLY in new repos
+      on: push
+
+      jobs:
+        release:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - name: Build
+              run: npm run build
+            - name: Create GitHub Release
+              uses: softprops/action-gh-release@v2
+              with:
+                files: dist/**
+              # Fails with 403 in new repos — needs contents:write
+  - language: yaml
+    label: "Fix: explicit job-level permissions (least privilege)"
+    code: |
+      on: push
+
+      jobs:
+        release:
+          runs-on: ubuntu-latest
+          permissions:
+            contents: write    # Required to create releases and upload assets
+          steps:
+            - uses: actions/checkout@v4
+            - name: Build
+              run: npm run build
+            - name: Create GitHub Release
+              uses: softprops/action-gh-release@v2
+              with:
+                files: dist/**
+  - language: yaml
+    label: "Workflow-level permissions (when multiple jobs all need write access)"
+    code: |
+      on: push
+
+      # Set workflow-level default — overridden per job as needed
+      permissions:
+        contents: write
+        pull-requests: write
+
+      jobs:
+        build-and-release:
+          runs-on: ubuntu-latest
+          # Inherits workflow-level permissions
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm run build
+
+        comment-on-pr:
+          runs-on: ubuntu-latest
+          permissions:
+            pull-requests: write   # Job-level — more restrictive than workflow default
+            contents: read
+          steps:
+            - uses: actions/checkout@v4
+prevention:
+  - "Always declare explicit permissions blocks in workflows that push, create releases, comment, or deploy — never rely on defaults"
+  - "Run 'actionlint' locally — it warns when a workflow uses write-requiring actions without corresponding permissions"
+  - "Use the minimum permissions required: grant 'contents: write' only on jobs that need it, not at workflow level"
+  - "When copying a workflow from another repo, check whether it has a permissions block — add one if missing"
+  - "Review the GitHub Actions audit log when a workflow fails with 403 to confirm the token permissions in use"
+docs:
+  - url: "https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication#permissions-for-the-github_token"
+    label: "GitHub Docs: GITHUB_TOKEN permissions"
+  - url: "https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#setting-the-permissions-of-the-github_token-for-your-repository"
+    label: "GitHub Docs: Setting default workflow permissions"
+  - url: "https://github.blog/changelog/2023-02-02-github-actions-updating-the-default-github_token-permissions-to-read-only/"
+    label: "GitHub Changelog: Default GITHUB_TOKEN permissions changed to read-only (Feb 2023)"

package/errors/silent-failures/silent-failures-055.yml

@@ -0,0 +1,99 @@
+id: silent-failures-055
+title: "'github.event_name' is 'workflow_call' inside reusable workflows — not the caller's event"
+category: silent-failures
+severity: silent-failure
+tags:
+  - reusable-workflow
+  - workflow_call
+  - event_name
+  - github-context
+  - conditional
+  - silent
+patterns:
+  - regex: 'github\.event_name\s*==\s*[''"]push[''"]'
+    flags: i
+  - regex: 'github\.event_name\s*==\s*[''"]pull_request[''"]'
+    flags: i
+  - regex: 'github\.event_name\s*==\s*[''"]workflow_dispatch[''"]'
+    flags: i
+error_messages:
+  - "Evaluating: github.event_name == 'push' => false"
+  - "Step skipped: if condition 'github.event_name == \"push\"' was false"
+root_cause: |
+  When a workflow is called as a reusable workflow via on: workflow_call, GitHub Actions
+  sets github.event_name to "workflow_call" inside that workflow — NOT to the triggering
+  event from the caller workflow.
+
+  A common mistake is to write conditional logic in a reusable workflow that checks
+  github.event_name expecting the caller's event (push, pull_request, workflow_dispatch,
+  etc.). These conditions always evaluate to false when the workflow is invoked via
+  workflow_call, silently skipping the affected steps or entire jobs.
+
+  The behaviour is especially confusing because developers often test the reusable workflow
+  in isolation via workflow_dispatch — in which case github.event_name IS correct. The
+  silent skip only appears when the workflow is called from another workflow, and the skipped
+  step or job disappears from the run summary with no error message.
+fix: |
+  Pass the caller's event name as an explicit input to the reusable workflow. The caller
+  reads github.event_name from its own context (where it is correct) and passes it as a
+  string input. Inside the reusable workflow, check inputs.caller_event (or whatever name
+  you choose) instead of github.event_name.
+
+  Alternatively, restructure so that event-specific logic stays in the caller workflow and
+  the reusable workflow only receives final parameters — not the raw event name.
+fix_code:
+  - language: yaml
+    label: "Problem: event_name check always false in reusable workflow"
+    code: |
+      # reusable.yml — WRONG: event_name is always "workflow_call" here
+      on:
+        workflow_call:
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Deploy only on push
+              if: github.event_name == 'push'   # Always false — event_name is "workflow_call"
+              run: echo "Deploying..."
+  - language: yaml
+    label: "Fix: accept caller_event as an explicit input"
+    code: |
+      # reusable.yml — CORRECT: accept the caller's event as an input
+      on:
+        workflow_call:
+          inputs:
+            caller_event:
+              type: string
+              required: true
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Deploy only on push
+              if: inputs.caller_event == 'push'   # Correct — uses the passed-in value
+              run: echo "Deploying..."
+  - language: yaml
+    label: "Caller workflow: pass github.event_name as input"
+    code: |
+      # caller.yml — pass the caller's event name to the reusable workflow
+      on: [push, pull_request]
+
+      jobs:
+        call-reusable:
+          uses: ./.github/workflows/reusable.yml
+          with:
+            caller_event: ${{ github.event_name }}   # "push" or "pull_request"
+prevention:
+  - "Never use 'github.event_name' in a reusable workflow to detect the caller's event — it will always be 'workflow_call'"
+  - "Pass event-specific data as explicit inputs; document expected values in the input description field"
+  - "When testing a reusable workflow via workflow_dispatch, simulate the production caller_event value via inputs to catch conditional errors early"
+  - "The same rule applies to github.event.* properties — many will be empty or refer to the workflow_call event, not the caller's event"
+docs:
+  - url: "https://docs.github.com/en/actions/sharing-automations/reusing-workflows"
+    label: "GitHub Docs: Reusing workflows"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#github-context"
+    label: "GitHub Docs: github context reference"
+  - url: "https://docs.github.com/en/actions/sharing-automations/reusing-workflows#limitations"
+    label: "GitHub Docs: Reusable workflow limitations"

package/errors/silent-failures/silent-failures-056.yml

@@ -0,0 +1,105 @@
+id: silent-failures-056
+title: "'continue-on-error: true' makes a failed job report success in required status checks"
+category: silent-failures
+severity: silent-failure
+tags:
+  - continue-on-error
+  - required-status-checks
+  - branch-protection
+  - checks-api
+  - silent
+  - branch-protection-bypass
+patterns:
+  - regex: 'continue-on-error:\s*true'
+    flags: i
+error_messages:
+  - "Job succeeded (continue-on-error)"
+  - "Required status check passed (job actually failed but continue-on-error: true)"
+root_cause: |
+  When a job has continue-on-error: true set, GitHub Actions converts the job's conclusion
+  from failure to success before writing the result to the Checks API. The branch
+  protection system only sees the API-level conclusion — which is "success" — and allows
+  the pull request to merge.
+
+  The job timeline in the GitHub UI shows a yellow icon with "(Cancelled)" or similar
+  wording, but the Checks API and branch protection treat it as passed. Developers
+  relying on required status checks to enforce quality gates unknowingly lose that
+  protection for any job marked continue-on-error: true.
+
+  This is particularly dangerous on jobs that run security scans, license checks, or
+  integration tests where the team deliberately added them as required checks to block
+  broken or risky changes from merging.
+fix: |
+  Avoid using continue-on-error: true on jobs that are configured as required status
+  checks in branch protection rules. Instead, handle acceptable failure conditions
+  explicitly inside the job using if: steps.*.outcome == 'failure' logic.
+
+  If you need to always continue a workflow past a flaky or optional step but still
+  surface failures in status checks, use a separate sentinel job that:
+  1. Depends on the real job with needs:
+  2. Runs with if: always()
+  3. Fails explicitly if the upstream job failed
+
+  This pattern separates "keep the workflow running" from "record the real outcome".
+fix_code:
+  - language: yaml
+    label: "Problem: continue-on-error silently hides failures from status checks"
+    code: |
+      jobs:
+        security-scan:
+          runs-on: ubuntu-latest
+          continue-on-error: true   # DANGER: required status check will PASS even if scan fails
+          steps:
+            - name: Run security scan
+              run: ./run-scan.sh
+  - language: yaml
+    label: "Fix: use a sentinel job to preserve the real outcome"
+    code: |
+      jobs:
+        security-scan:
+          runs-on: ubuntu-latest
+          # No continue-on-error here
+          steps:
+            - name: Run security scan
+              run: ./run-scan.sh
+
+        # This is the job to set as the required status check
+        security-gate:
+          runs-on: ubuntu-latest
+          needs: [security-scan]
+          if: always()
+          steps:
+            - name: Check security scan result
+              if: needs.security-scan.result != 'success'
+              run: |
+                echo "Security scan did not pass (result: ${{ needs.security-scan.result }})"
+                exit 1
+  - language: yaml
+    label: "Alternative: handle acceptable failures inside the step, not the job"
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Run optional extended tests
+              id: extended
+              run: ./run-extended-tests.sh
+              continue-on-error: true   # Step-level is safer than job-level
+
+            - name: Fail job if extended tests failed unexpectedly
+              if: steps.extended.outcome == 'failure'
+              run: |
+                echo "Extended tests failed — blocking merge"
+                exit 1
+prevention:
+  - "Never set continue-on-error: true at the job level for jobs that are required status checks"
+  - "Use continue-on-error: true at the step level instead — it does not affect the Checks API job conclusion"
+  - "Audit your branch protection required checks against all jobs that have continue-on-error: true"
+  - "Use the sentinel job pattern to separate workflow continuation from status reporting"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idcontinue-on-error"
+    label: "GitHub Docs: continue-on-error syntax"
+  - url: "https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-status-checks-before-merging"
+    label: "GitHub Docs: Required status checks before merging"
+  - url: "https://docs.github.com/en/rest/checks/runs"
+    label: "GitHub REST API: Checks runs"

package/errors/triggers/triggers-039.yml

@@ -0,0 +1,115 @@
+id: triggers-039
+title: "'github.sha' in pull_request_target points to base branch HEAD, not the PR's head commit"
+category: triggers
+severity: silent-failure
+tags:
+  - pull_request_target
+  - github-sha
+  - base-branch
+  - pr-head
+  - checkout
+  - security
+  - silent
+patterns:
+  - regex: 'pull_request_target'
+    flags: i
+  - regex: 'github\.event\.pull_request\.head\.sha'
+    flags: i
+  - regex: 'github\.sha.*pull_request_target'
+    flags: i
+error_messages:
+  - "Tests passed but PR code was never executed (checked out base branch at github.sha)"
+root_cause: |
+  The pull_request_target event fires in the context of the BASE branch of a pull request,
+  not the PR's head branch. Consequently, github.sha inside a pull_request_target workflow
+  is the HEAD commit SHA of the BASE branch — typically main or master — not the PR
+  contributor's changes.
+
+  This design is intentional: pull_request_target runs with repository secrets and write
+  permissions available, so GitHub restricts it to trusted base-branch code to prevent
+  malicious PR code from exfiltrating secrets. However, it causes a silent logic error when
+  developers expect github.sha (or the default actions/checkout behaviour, which checks out
+  github.sha) to build and test the PR's changes.
+
+  The result is a CI run that appears to succeed — but it compiled and tested the base
+  branch code, not the pull request's changes. The PR author sees green CI even though
+  their changes were never executed.
+fix: |
+  To work with PR head code in a pull_request_target workflow, explicitly specify the PR
+  head SHA using github.event.pull_request.head.sha in the checkout step's ref: input.
+
+  SECURITY WARNING: checking out untrusted PR code in a workflow that has access to secrets
+  creates a pwn-request vulnerability. Only check out PR head code in jobs with minimal
+  permissions and no secret exposure.
+
+  For most CI use cases — building, linting, testing — use the standard pull_request event
+  instead of pull_request_target. The pull_request event correctly checks out PR changes
+  but runs without repository secrets, which is the safe and intended design.
+fix_code:
+  - language: yaml
+    label: "Problem: default checkout in pull_request_target checks out base branch"
+    code: |
+      on: pull_request_target
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+              # No ref specified — uses github.sha which is BASE branch HEAD, not PR code
+            - run: npm test   # Tests base branch, not the PR changes
+  - language: yaml
+    label: "Explicit PR head checkout (only when no secrets are exposed)"
+    code: |
+      on: pull_request_target
+
+      jobs:
+        label-and-check:
+          runs-on: ubuntu-latest
+          permissions:
+            pull-requests: write   # Minimal permissions — no secrets
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                ref: ${{ github.event.pull_request.head.sha }}
+                # Only safe because this job has no secret access
+                # Do NOT add secrets: or environment: to jobs that do this
+  - language: yaml
+    label: "Recommended: use pull_request for testing, pull_request_target only for privileged operations"
+    code: |
+      # Standard PR testing — pull_request has no secrets but correctly checks out PR changes
+      on: pull_request
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+              # github.sha is the PR merge commit — correct for testing PR changes
+            - run: npm test
+
+      ---
+      # Separate privileged workflow for labeling/commenting — uses pull_request_target
+      # This one works with base-branch context (github.sha = base HEAD) — which is correct
+      # for privileged operations that should only run trusted code
+      on: pull_request_target
+
+      jobs:
+        label:
+          runs-on: ubuntu-latest
+          permissions:
+            pull-requests: write
+          steps:
+            - uses: actions/labeler@v5
+prevention:
+  - "Default to 'pull_request' event for building and testing PR code — it correctly checks out PR changes and has no secrets"
+  - "Use 'pull_request_target' only for privileged operations that genuinely need secrets or write permissions (labeling, commenting, deployment approval)"
+  - "Never expose repository secrets in the same job that checks out untrusted PR head code via github.event.pull_request.head.sha"
+  - "Add a comment next to any pull_request_target checkout step documenting which ref is used and why it is safe"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#pull_request_target"
+    label: "GitHub Docs: pull_request_target event"
+  - url: "https://securitylab.github.com/resources/github-actions-preventing-pwn-requests/"
+    label: "GitHub Security Lab: Preventing pwn requests"
+  - url: "https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions"
+    label: "GitHub Docs: Security hardening for GitHub Actions"

package/errors/triggers/triggers-040.yml

@@ -0,0 +1,104 @@
+id: triggers-040
+title: "Missing 'on: merge_group' trigger — required status checks fail in merge queue"
+category: triggers
+severity: error
+tags:
+  - merge-queue
+  - merge_group
+  - required-status-checks
+  - branch-protection
+  - ci-failure
+  - triggers
+patterns:
+  - regex: 'merge_group'
+    flags: i
+  - regex: 'Required status checks were not passing.*merge.queue'
+    flags: i
+error_messages:
+  - "Required status check 'ci/test' was not reported — PR ejected from merge queue"
+  - "This branch requires linear history. The merge queue could not merge this pull request."
+root_cause: |
+  GitHub's merge queue (available since May 2023 GA) uses a dedicated event called
+  merge_group to trigger workflows. This is distinct from the pull_request event.
+
+  When a pull request enters the merge queue, GitHub creates a temporary merge branch
+  and fires the merge_group event. Workflows that only declare on: pull_request (or
+  other events) do not trigger on merge_group and therefore never create any status
+  check runs for the queued PR.
+
+  Branch protection rules that require specific status checks see no check result for
+  the merge group run and treat the absence as failure, ejecting the PR from the queue
+  with a message that the required checks were not passing.
+
+  The merge queue was added to GitHub Actions in May 2023 (GitHub Changelog). Existing
+  workflows created before that date have no merge_group trigger and must be updated
+  manually. Projects that enable merge queue on an existing repo will silently find
+  that all PRs are blocked from being merged via the queue.
+fix: |
+  Add merge_group: to the on: trigger block alongside pull_request (and push, if used).
+  The merge_group event accepts no filter options — it fires whenever any PR enters
+  the merge queue for a protected branch.
+
+  If your workflow uses branch filters under on.pull_request.branches, those filters
+  do NOT apply to merge_group — the event always fires regardless of branch name.
+  This is intentional: the merge queue uses temporary synthetic branches.
+fix_code:
+  - language: yaml
+    label: "Problem: workflow only triggers on pull_request, not in merge queue"
+    code: |
+      # BEFORE: only runs on pull_request — never fires in merge queue
+      on:
+        pull_request:
+          branches: [main]
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm test
+  - language: yaml
+    label: "Fix: add merge_group trigger so CI runs in the merge queue"
+    code: |
+      # AFTER: runs on both pull_request and when entering the merge queue
+      on:
+        pull_request:
+          branches: [main]
+        merge_group:        # Required for merge queue — no filter options available
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm test
+  - language: yaml
+    label: "With push trigger (common three-trigger pattern)"
+    code: |
+      on:
+        push:
+          branches: [main]
+        pull_request:
+          branches: [main]
+        merge_group:        # Always needed if merge queue is enabled on the repo
+
+      jobs:
+        ci:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm ci
+            - run: npm test
+            - run: npm run lint
+prevention:
+  - "Any time you enable merge queue on a branch, audit all required-check workflows and add 'merge_group:' to each"
+  - "The merge_group event accepts no filter keys — do not try to add 'branches:' or 'types:' under it"
+  - "Test merge queue behavior by adding a PR to the queue and checking the Actions tab for the merge group run"
+  - "Add a comment near the merge_group trigger explaining its purpose for teammates unfamiliar with merge queues"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#merge_group"
+    label: "GitHub Docs: merge_group event"
+  - url: "https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-a-merge-queue"
+    label: "GitHub Docs: Managing a merge queue"
+  - url: "https://github.blog/changelog/2023-05-12-github-actions-merge-queue-is-generally-available/"
+    label: "GitHub Changelog: Merge queue GA (May 2023)"

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

@@ -0,0 +1,91 @@
+id: yaml-syntax-038
+title: "'::save-state::' and '::get-state::' workflow commands deprecated — upgrade to GITHUB_STATE"
+category: yaml-syntax
+severity: warning
+tags:
+  - save-state
+  - get-state
+  - deprecated
+  - workflow-commands
+  - environment-files
+  - GITHUB_STATE
+patterns:
+  - regex: 'The `save-state` command is deprecated'
+    flags: i
+  - regex: 'The `get-state` command is deprecated'
+    flags: i
+  - regex: '::save-state name='
+    flags: ''
+  - regex: '::get-state name='
+    flags: ''
+error_messages:
+  - "Warning: The `save-state` command is deprecated and will be disabled soon. Please upgrade to using Environment Files."
+  - "Warning: The `get-state` command is deprecated and will be disabled soon. Please upgrade to using Environment Files."
+root_cause: |
+  GitHub Actions originally provided workflow commands ::save-state name=FOO::value and
+  ::get-state name=FOO:: as a way to persist data between the main body of a step and its
+  pre: or post: hooks in JavaScript actions.
+
+  GitHub deprecated these commands when it introduced environment files (GITHUB_STATE,
+  GITHUB_ENV, GITHUB_OUTPUT) as a more robust alternative. Workflows and actions that use
+  the old echo "::save-state name=...::value" or echo "::get-state name=...:" syntax now
+  produce deprecation warnings in workflow logs.
+
+  When these commands are eventually disabled, steps using them will silently fail to persist
+  state — the post: hook will read an empty string from the state variable, causing subtle
+  logic errors. Actions published to the Marketplace are particularly affected because older
+  versions used these commands before the deprecation was announced.
+fix: |
+  Replace the deprecated workflow commands with the GITHUB_STATE environment file approach:
+  - To write state: append "KEY=value" to $GITHUB_STATE (shell) or write to
+    process.env['GITHUB_STATE'] (Node.js)
+  - To read state in pre:/post: hooks: read the environment variable STATE_<KEY>
+
+  In shell-based steps the pattern is identical to GITHUB_ENV and GITHUB_OUTPUT.
+  In JavaScript actions, upgrade to @actions/core v1.10.0+ and use the saveState() and
+  getState() helpers, which internally write to GITHUB_STATE.
+fix_code:
+  - language: yaml
+    label: "Deprecated: ::save-state:: and ::get-state:: commands (produces warnings)"
+    code: |
+      # DEPRECATED — produces warning in logs, will eventually break
+      - name: Save state (deprecated)
+        run: echo "::save-state name=SERVER_PID::12345"
+
+      - name: Read state in post step (deprecated)
+        run: echo "Saved PID was $(echo "::get-state name=SERVER_PID::")"
+  - language: yaml
+    label: "Correct: GITHUB_STATE environment file"
+    code: |
+      # Write state to GITHUB_STATE file
+      - name: Save state
+        run: echo "SERVER_PID=12345" >> $GITHUB_STATE
+
+      # State is automatically available as STATE_<KEY> in later phases
+      - name: Read state (available in main, pre, and post phases)
+        run: echo "Server PID was $STATE_SERVER_PID"
+  - language: yaml
+    label: "PowerShell equivalent"
+    code: |
+      - name: Save state (PowerShell)
+        shell: pwsh
+        run: |
+          "SERVER_PID=12345" | Out-File -FilePath $env:GITHUB_STATE -Append
+
+      - name: Read state (PowerShell)
+        shell: pwsh
+        run: |
+          Write-Host "Server PID was $env:STATE_SERVER_PID"
+prevention:
+  - "Audit actions with pre: or post: hooks — these are the primary consumers of save-state/get-state"
+  - "Upgrade to @actions/core v1.10.0+ which uses GITHUB_STATE internally via saveState()/getState()"
+  - "Search existing workflows and composite actions for '::save-state' and '::get-state' patterns before they are disabled"
+  - "Pin to action versions that have migrated to GITHUB_STATE; check CHANGELOG for migration notes"
+  - "The same deprecation cycle affected ::set-output:: (now GITHUB_OUTPUT) and ::set-env:: (now GITHUB_ENV)"
+docs:
+  - url: "https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#environment-files"
+    label: "GitHub Docs: Workflow commands — environment files"
+  - url: "https://github.blog/changelog/2022-10-11-github-actions-deprecating-save-state-and-set-output-commands/"
+    label: "GitHub Changelog: Deprecating save-state and set-output commands (Oct 2022)"
+  - url: "https://github.com/actions/toolkit/releases/tag/%40actions%2Fcore%401.10.0"
+    label: "actions/toolkit: @actions/core v1.10.0 release notes"

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

@@ -0,0 +1,115 @@
+id: yaml-syntax-039
+title: "'type: choice' not supported for workflow_call inputs — validation error when combining with workflow_dispatch"
+category: yaml-syntax
+severity: error
+tags:
+  - workflow_call
+  - workflow_dispatch
+  - inputs
+  - type-choice
+  - validation
+  - combined-triggers
+patterns:
+  - regex: 'Input type .choice. is not supported'
+    flags: i
+  - regex: 'Unexpected value .choice.'
+    flags: i
+  - regex: 'Invalid workflow file.*type.*choice'
+    flags: i
+error_messages:
+  - "Invalid workflow file: Input type 'choice' is not supported for workflow_call triggers. Allowed types: boolean, number, string"
+  - "Unexpected value 'choice', expected one of: boolean, number, string"
+  - "Invalid value for inputs.*.type: 'choice'"
+root_cause: |
+  GitHub Actions supports different input types depending on the trigger:
+  - workflow_dispatch supports: boolean, choice, environment, number, string
+  - workflow_call supports only: boolean, number, string
+
+  When developers combine both triggers in the same workflow file (a common pattern for
+  workflows that can be called by other workflows AND dispatched manually), they define a
+  shared inputs: block. If those shared inputs use type: choice — valid for workflow_dispatch
+  but not workflow_call — the workflow fails schema validation with a cryptic error.
+
+  The error message does not always clearly indicate which trigger is rejecting the type,
+  causing developers to search for choice support across GitHub Actions documentation rather
+  than recognising it as a trigger-specific limitation. The same restriction applies to
+  type: environment.
+fix: |
+  For inputs shared between workflow_dispatch and workflow_call, use type: string and
+  document the allowed values in the description field. The GitHub UI renders a free-text
+  field for manual dispatch instead of a dropdown, but callers still pass controlled values.
+
+  For strict input validation, add a shell step at the start of the job that fails if the
+  input value is not in the allowed set.
+
+  If the dropdown UI is essential for manual dispatch, create a thin dispatcher workflow
+  (workflow_dispatch only with type: choice) that calls the main reusable workflow passing
+  the validated value as a string.
+fix_code:
+  - language: yaml
+    label: "Problem: type: choice breaks workflow_call validation"
+    code: |
+      on:
+        workflow_dispatch:
+          inputs:
+            environment:
+              type: choice           # Valid for workflow_dispatch only
+              options: [dev, staging, prod]
+        workflow_call:
+          inputs:
+            environment:
+              type: choice           # INVALID for workflow_call — causes validation error
+  - language: yaml
+    label: "Fix: use type: string with documented allowed values"
+    code: |
+      on:
+        workflow_dispatch:
+          inputs:
+            environment:
+              type: string
+              description: "Target environment. Allowed values: dev, staging, prod"
+              default: dev
+        workflow_call:
+          inputs:
+            environment:
+              type: string
+              description: "Target environment. Allowed values: dev, staging, prod"
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Validate environment input
+              run: |
+                case "${{ inputs.environment }}" in
+                  dev|staging|prod) echo "Environment: ${{ inputs.environment }}" ;;
+                  *) echo "Invalid environment: ${{ inputs.environment }}"; exit 1 ;;
+                esac
+  - language: yaml
+    label: "Alternative: dispatcher wrapper preserves dropdown UI for manual runs"
+    code: |
+      # dispatcher.yml — manual dispatch wrapper with choice dropdown
+      on:
+        workflow_dispatch:
+          inputs:
+            environment:
+              type: choice
+              options: [dev, staging, prod]
+
+      jobs:
+        dispatch:
+          uses: ./.github/workflows/deploy.yml    # calls the reusable workflow
+          with:
+            environment: ${{ inputs.environment }}  # passes as string
+prevention:
+  - "workflow_call inputs support only: boolean, number, string — not choice or environment"
+  - "Use type: string with a description listing allowed values when an input is shared across both triggers"
+  - "Add input validation as the first job step to fail fast when an unexpected value is passed via workflow_call"
+  - "Run actionlint locally before pushing — it catches unsupported input types at development time"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#onworkflow_callinputs"
+    label: "GitHub Docs: on.workflow_call.inputs syntax"
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#onworkflow_dispatchinputs"
+    label: "GitHub Docs: on.workflow_dispatch.inputs syntax"
+  - url: "https://rhysd.github.io/actionlint/"
+    label: "actionlint: static checker for GitHub Actions workflow files"

package/package.json

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