@htekdev/actions-debugger 1.0.81 → 1.0.82

package/errors/concurrency-timing/workflow-level-vs-job-level-concurrency-scope.yml

@@ -0,0 +1,92 @@
+id: concurrency-timing-041
+title: "Workflow-level concurrency cancels entire workflow — job-level concurrency only gates that specific job"
+category: concurrency-timing
+severity: silent-failure
+tags:
+  - concurrency
+  - cancel-in-progress
+  - workflow-level
+  - job-level
+  - scope
+  - deployment
+  - test-cancellation
+patterns:
+  - regex: '^concurrency:\s*$'
+    flags: 'm'
+  - regex: 'jobs\.[a-zA-Z_][a-zA-Z0-9_-]*:\s*\n(\s+.*\n)*\s+concurrency:'
+    flags: 'm'
+error_messages:
+  - "Run was cancelled. (workflow-level concurrency cancelled entire run including unrelated jobs)"
+  - "Skipping job deploy because it is not needed (cancelled by workflow-level concurrency group)"
+root_cause: |
+  The concurrency: key in GitHub Actions behaves fundamentally differently depending on
+  where it is placed in the workflow file:
+
+  WORKFLOW-LEVEL (top-level key, outside jobs:):
+  Cancels or queues the ENTIRE workflow run. When a new run starts for the same concurrency
+  group, all pending or in-progress jobs in the workflow are affected — including build,
+  test, lint, and deploy jobs. The full workflow run is treated as the atomic unit.
+
+  JOB-LEVEL (inside jobs.<job_id>: as a sibling of runs-on: and steps:):
+  Only gates THAT SPECIFIC JOB. Other jobs in the same workflow run execute concurrently
+  without restriction. Serialization or cancellation applies only to the job that declares
+  the concurrency block.
+
+  Common mistake #1: developer adds workflow-level concurrency intending to prevent
+  duplicate deployments, but accidentally causes active test/build jobs to be cancelled
+  on every new push — wasting compute and breaking CI feedback.
+
+  Common mistake #2: developer adds job-level concurrency expecting the whole workflow
+  to be serialized, but parallel test runs from multiple pushes execute simultaneously.
+fix: |
+  Use job-level concurrency on only the deploy job when you want to serialize
+  deployments without interrupting parallel test runs. Use workflow-level concurrency
+  only when you intend for the entire workflow to serialize or cancel on new push.
+fix_code:
+  - language: yaml
+    label: "Correct: job-level concurrency on deploy only — tests run freely"
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          # No concurrency — multiple test runs execute in parallel across pushes
+          steps:
+            - run: npm test
+
+        deploy:
+          needs: test
+          runs-on: ubuntu-latest
+          concurrency:
+            group: deploy-${{ github.ref_name }}
+            cancel-in-progress: false  # Queue deploys, never cancel in-flight
+          steps:
+            - run: ./deploy.sh
+  - language: yaml
+    label: "Caution: workflow-level concurrency cancels test and build jobs too"
+    code: |
+      # This cancels the ENTIRE workflow on new push — tests, build, and deploy all stop
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.ref }}
+        cancel-in-progress: true
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - run: npm test  # Also cancelled when a new push arrives
+
+        deploy:
+          needs: test
+          runs-on: ubuntu-latest
+          steps:
+            - run: ./deploy.sh
+prevention:
+  - "For deploy-only serialization, use job-level concurrency on only the deploy job"
+  - "Avoid cancel-in-progress: true at workflow level for deployment workflows — an interrupted deploy may leave infrastructure in an inconsistent state"
+  - "Use cancel-in-progress: ${{ github.event_name == 'pull_request' }} to cancel PR runs but preserve default-branch deployments"
+  - "Verify scope: if concurrency: is indented under a specific jobs.<id>: block it is job-level; if it is at the same indentation as jobs: it is workflow-level"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-concurrency"
+    label: "GitHub Docs: Using concurrency"
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#concurrency"
+    label: "GitHub Docs: concurrency syntax reference"

package/errors/known-unsolved/org-required-workflow-no-per-repo-override.yml

@@ -0,0 +1,88 @@
+id: known-unsolved-048
+title: 'Organization required workflows block all repo PRs with no per-repo override'
+category: known-unsolved
+severity: limitation
+tags:
+  - required-workflows
+  - organization
+  - branch-protection
+  - enterprise
+  - admin
+patterns:
+  - regex: 'Required status checks have not passed for this branch'
+    flags: 'i'
+  - regex: 'required workflows? are not complete'
+    flags: 'i'
+error_messages:
+  - 'Required status checks have not passed for this branch'
+  - 'The following required workflows are not complete: .github/workflows/required-check.yml'
+  - 'Required workflow failed: org-name/.github/.github/workflows/security-scan.yml'
+root_cause: |
+  GitHub Enterprise Cloud allows org admins to configure "Required workflows"
+  under Org Settings → Actions → Required workflows. These workflows run on
+  every push and pull_request event across every repository in the organization
+  and are automatically added as required status checks on all branches.
+
+  When a required workflow fails — due to a misconfiguration, missing secret,
+  incompatibility with a specific repository's structure, or a transient error
+  — all open PRs in every affected repository are blocked from merging. There
+  is no mechanism for repo admins or developers to bypass or exempt their
+  repository from the org-level required workflow. Only the org admin can fix
+  the required workflow or remove the requirement.
+
+  This creates an org-wide single point of failure: a bug in the centralized
+  required workflow instantly blocks all engineering teams from shipping.
+fix: |
+  There is no per-repository exemption for org required workflows. Mitigation
+  strategies for org admins:
+
+  1. Use `if:` conditions in the required workflow to skip gracefully for
+     incompatible repositories instead of failing.
+  2. Set `continue-on-error: true` on non-critical jobs within the required
+     workflow so that optional checks do not block merges.
+  3. Maintain a staging version of the required workflow tested on a canary
+     repo before rolling changes org-wide.
+  4. Set up alerting on required workflow failure rates to catch regressions
+     before they block the whole org.
+fix_code:
+  - language: yaml
+    label: 'Use if: conditions to gracefully skip incompatible repos'
+    code: |
+      # In org's .github repo: .github/workflows/required-check.yml
+      name: Required Security Scan
+      on: [push, pull_request]
+      jobs:
+        security-scan:
+          runs-on: ubuntu-latest
+          # Skip repos that are explicitly opted out
+          if: >-
+            !contains(
+              fromJSON('["org/legacy-repo", "org/infra-repo"]'),
+              github.repository
+            )
+          steps:
+            - uses: actions/checkout@v4
+            - name: Run scan
+              run: ./scripts/security-scan.sh
+
+  - language: yaml
+    label: 'Use continue-on-error for non-blocking checks'
+    code: |
+      jobs:
+        lint:
+          runs-on: ubuntu-latest
+          continue-on-error: true   # Won't block the required status check
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm run lint
+prevention:
+  - 'Test required workflows in a canary repository before enabling org-wide'
+  - 'Use `if:` guards to skip repos that cannot satisfy the required checks'
+  - 'Monitor required workflow failure rates with org-level Actions dashboards'
+  - 'Prefer `continue-on-error: true` for advisory checks that should not hard-block PRs'
+  - 'Keep required workflows minimal — only truly mandatory gates belong here'
+docs:
+  - url: 'https://docs.github.com/en/actions/administering-github-actions/required-workflows'
+    label: 'Required workflows — GitHub Docs'
+  - 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: 'Required status checks — GitHub Docs'

package/errors/runner-environment/larger-runner-labels-require-paid-plan.yml

@@ -0,0 +1,73 @@
+id: runner-environment-144
+title: '`runs-on` larger hosted runner labels require GitHub Teams or Enterprise plan'
+category: runner-environment
+severity: error
+tags:
+  - runs-on
+  - larger-runners
+  - billing
+  - teams
+  - enterprise
+  - ubuntu-latest-4-cores
+patterns:
+  - regex: 'No runner matching the required labels was found:\s+ubuntu-latest-[0-9]+-cores'
+    flags: 'i'
+  - regex: 'No runner matching the required labels was found:\s+windows-latest-[0-9]+-cores'
+    flags: 'i'
+  - regex: 'No runner matching the required labels was found:\s+macos-latest-[0-9]+-cores'
+    flags: 'i'
+error_messages:
+  - 'No runner matching the required labels was found: ubuntu-latest-4-cores'
+  - 'No runner matching the required labels was found: ubuntu-latest-8-cores'
+  - 'No runner matching the required labels was found: windows-latest-8-cores'
+  - 'No runner matching the required labels was found: macos-latest-xlarge'
+root_cause: |
+  GitHub offers larger hosted runners (4-core, 8-core, 16-core, 64-core) via
+  labels like `ubuntu-latest-4-cores`, `ubuntu-latest-8-cores`,
+  `ubuntu-22.04-8-cores`, `windows-latest-8-cores`, and `macos-latest-xlarge`.
+  These runners are only available on GitHub Teams and GitHub Enterprise Cloud
+  plans. On GitHub Free and GitHub Pro plans these labels are not provisioned,
+  so the queued job sits waiting until it times out or immediately fails with
+  "No runner matching the required labels was found."
+
+  GitHub does not display a clear billing-tier explanation in the error message,
+  leaving developers to guess whether the runner label is misspelled or simply
+  unavailable on their plan.
+fix: |
+  Switch to the standard `ubuntu-latest` (2-core) runner for free/pro accounts,
+  upgrade to GitHub Teams/Enterprise to unlock larger runners, or use
+  self-hosted runners with more CPU/RAM as an alternative.
+fix_code:
+  - language: yaml
+    label: 'Use standard runner on free/pro plans'
+    code: |
+      jobs:
+        build:
+          # ubuntu-latest is a 2-core runner available on all GitHub plans
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: make build
+
+  - language: yaml
+    label: 'Conditionally use larger runner for orgs on Teams/Enterprise'
+    code: |
+      jobs:
+        build:
+          # Use larger runner for org workflows, fall back for personal repos
+          runs-on: >-
+            ${{ startsWith(github.repository, 'my-org/') &&
+                'ubuntu-latest-8-cores' || 'ubuntu-latest' }}
+          steps:
+            - uses: actions/checkout@v4
+            - run: make build
+prevention:
+  - 'Verify your GitHub plan tier before using larger runner labels — check under Billing & plans → GitHub Actions'
+  - 'Use self-hosted runners with additional CPU as a free alternative for resource-intensive builds'
+  - 'Document which runner labels require a paid plan in your repository CONTRIBUTING guide'
+  - 'Use `ubuntu-latest` (2-core) for most workflows; only reach for larger runners when build profiling shows a genuine bottleneck'
+docs:
+  - url: 'https://docs.github.com/en/actions/using-github-hosted-runners/about-larger-runners/about-larger-runners'
+    label: 'About larger runners — GitHub Docs'
+  - url: 'https://docs.github.com/en/billing/managing-billing-for-your-products/managing-billing-for-github-actions/about-billing-for-github-actions'
+    label: 'About billing for GitHub Actions — GitHub Docs'

package/errors/runner-environment/macos-bash-32-no-bash4-features.yml

@@ -0,0 +1,110 @@
+id: runner-environment-148
+title: "macOS runners ship with bash 3.2 — bash 4.x/5.x features unavailable"
+category: runner-environment
+severity: error
+tags:
+  - macos
+  - bash
+  - bash-version
+  - associative-arrays
+  - shell-scripting
+
+patterns:
+  - regex: 'declare.*-A.*invalid option'
+    flags: i
+  - regex: 'mapfile.*command not found'
+    flags: i
+  - regex: 'readarray.*command not found'
+    flags: i
+  - regex: 'syntax error near unexpected token.*\|\&'
+    flags: i
+
+error_messages:
+  - "/bin/bash: line N: declare: -A: invalid option"
+  - "declare: usage: declare [-afFirtx] [-p] [name[=value] ...]"
+  - "/bin/bash: mapfile: command not found"
+  - "/bin/bash: readarray: command not found"
+
+root_cause: |
+  macOS ships with GNU Bash 3.2.57 at /bin/bash due to Apple's decision not to
+  include GPL v3 software in the base OS. Bash 4.0 (released 2009) and all later
+  versions are GPL v3. macOS has not updated the system bash beyond 3.2.x for
+  over 15 years as a result.
+
+  GitHub-hosted macOS runners (macos-13, macos-14, macos-15, macos-latest) all use
+  /bin/bash as the default shell for `shell: bash` run steps. This means all bash
+  scripts on macOS runners are subject to bash 3.2 limitations:
+
+  - Associative arrays: `declare -A map` — UNAVAILABLE (added in bash 4.0)
+  - mapfile / readarray built-ins — UNAVAILABLE (added in bash 4.0)
+  - `|&` (pipe stdout and stderr): syntax error (added in bash 4.0)
+  - `**` globbing for recursive matching — UNAVAILABLE (added in bash 4.0, requires shopt -s globstar)
+  - Case-modifying parameter expansion: `${var^^}`, `${var,,}` — UNAVAILABLE (bash 4.0)
+
+  Workflows that run on ubuntu runners may work fine because ubuntu ships bash 5.x,
+  then silently fail on macOS runners at the same step due to the bash version
+  difference.
+
+fix: |
+  Install modern bash via Homebrew and either update the PATH or use the full path
+  to the installed bash in the shell setting or script shebang.
+
+  For cross-platform workflows, avoid bash 4.x/5.x-only features or add an explicit
+  setup step for macOS.
+
+fix_code:
+  - language: yaml
+    label: "Install modern bash via Homebrew (macOS)"
+    code: |
+      jobs:
+        build:
+          runs-on: macos-latest
+          steps:
+            - name: Install modern bash
+              run: brew install bash
+
+            - name: Run script with bash 5
+              run: /opt/homebrew/bin/bash my-script.sh
+              # Intel macOS: /usr/local/bin/bash
+              # Apple Silicon (macos-14+): /opt/homebrew/bin/bash
+
+  - language: yaml
+    label: "Set shell to modern bash for all steps"
+    code: |
+      jobs:
+        build:
+          runs-on: macos-latest
+          steps:
+            - name: Install modern bash
+              run: brew install bash
+
+            - name: Script using bash 4+ features
+              shell: /opt/homebrew/bin/bash {0}
+              run: |
+                declare -A mymap
+                mymap[key]="value"
+                echo "${mymap[key]}"
+
+  - language: yaml
+    label: "Cross-platform workaround — avoid bash 4+ features"
+    code: |
+      - run: |
+          # Use python or node for associative arrays cross-platform
+          python3 -c "
+          mymap = {'key': 'value'}
+          print(mymap['key'])
+          "
+
+prevention:
+  - Test macOS workflows explicitly — a step that passes on ubuntu may fail on macos.
+  - Avoid bash 4.x/5.x-only features (declare -A, mapfile, readarray) in scripts intended to run on macOS.
+  - Add `brew install bash` as the first step in any macOS job that uses modern bash syntax.
+  - Use `bash --version` in a debug step to confirm which bash is being used.
+
+docs:
+  - url: https://www.gnu.org/software/bash/manual/bash.html#What-is-Bash_003f
+    label: "GNU Bash — version history and features"
+  - url: https://brew.sh
+    label: "Homebrew — install modern bash on macOS"
+  - url: https://github.com/actions/runner-images/blob/main/images/macos/macos-15-Readme.md
+    label: "macos-15 runner image — pre-installed software"

package/errors/runner-environment/pip-externally-managed-environment-pep668.yml

@@ -0,0 +1,83 @@
+id: runner-environment-145
+title: "ubuntu-22/24 pip install fails with 'externally-managed-environment' (PEP 668)"
+category: runner-environment
+severity: error
+tags:
+  - ubuntu
+  - python
+  - pip
+  - pep-668
+  - packages
+  - setup-python
+
+patterns:
+  - regex: 'externally.managed.environment'
+    flags: i
+  - regex: 'This environment is externally managed'
+    flags: i
+
+error_messages:
+  - "error: externally-managed-environment"
+  - "× This environment is externally managed"
+  - "╰─> To install Python packages system-wide, try apt install"
+
+root_cause: |
+  PEP 668, adopted in Python 3.11+ and backported by distros like Ubuntu 22.04 and
+  24.04, prevents pip from installing packages into the system Python environment.
+  Ubuntu 22.04 ships Python 3.10 but enforces PEP 668 in the system pip. Ubuntu 24.04
+  ships Python 3.12 with full PEP 668 enforcement.
+
+  GitHub Actions runners expose the system Python when no setup-python step is used.
+  System pip blocks global installs and raises this error to prevent breaking
+  OS-managed packages that depend on system Python libraries.
+
+  Workflows that previously ran `pip install <pkg>` or `pip3 install <pkg>` directly
+  on ubuntu-20.04 succeed silently, but fail on ubuntu-22.04 and ubuntu-24.04 because
+  those images enforce the system-managed environment restriction.
+
+fix: |
+  Use one of these approaches:
+
+  1. Use actions/setup-python (recommended) — configures an isolated Python
+     environment that allows pip installs freely.
+
+  2. Install with --break-system-packages flag — allows global install but may
+     conflict with apt-managed packages. Use only for CI where isolation is
+     acceptable.
+
+  3. Create a virtual environment inline with python -m venv.
+
+fix_code:
+  - language: yaml
+    label: "Use actions/setup-python (recommended)"
+    code: |
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: pip install my-package   # installs into the setup-python venv, no error
+
+  - language: yaml
+    label: "Virtual environment workaround"
+    code: |
+      - run: |
+          python3 -m venv .venv
+          source .venv/bin/activate
+          pip install my-package
+
+  - language: yaml
+    label: "Break system packages flag (use with caution)"
+    code: |
+      - run: pip install --break-system-packages my-package
+
+prevention:
+  - Always use actions/setup-python before any pip install in workflows targeting ubuntu-22.04 or ubuntu-24.04.
+  - Pin ubuntu version explicitly — upgrading from ubuntu-20.04 to ubuntu-latest silently adopts PEP 668 enforcement.
+  - Prefer virtual environments over global installs in CI for reproducibility.
+
+docs:
+  - url: https://peps.python.org/pep-0668/
+    label: "PEP 668 — Marking Python base environments as externally managed"
+  - url: https://github.com/actions/setup-python
+    label: "actions/setup-python — GitHub Actions"
+  - url: https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2404-Readme.md
+    label: "ubuntu-24.04 runner image — pre-installed software"

package/errors/runner-environment/ubuntu-24-ruby-not-preinstalled.yml

@@ -0,0 +1,74 @@
+id: runner-environment-146
+title: "ubuntu-24.04 runner — Ruby and gem not pre-installed"
+category: runner-environment
+severity: error
+tags:
+  - ubuntu-24
+  - ruby
+  - gem
+  - tools-missing
+  - migration
+
+patterns:
+  - regex: 'ruby\s*:\s*command not found'
+    flags: i
+  - regex: 'gem\s*:\s*command not found'
+    flags: i
+  - regex: 'No such file or directory.*ruby'
+    flags: i
+
+error_messages:
+  - "/usr/bin/bash: ruby: command not found"
+  - "/usr/bin/bash: gem: command not found"
+  - "Error: ruby not found"
+
+root_cause: |
+  GitHub's ubuntu-24.04 runner image does not include Ruby in its pre-installed
+  software list. Unlike ubuntu-22.04 (which ships Ruby 3.0.x from the Ubuntu 22
+  package repository), ubuntu-24.04 dropped Ruby as a default pre-installed tool.
+
+  Workflows that rely on `ruby`, `gem`, `bundle`, or `rake` being available without
+  an explicit setup step will fail with "command not found" when the runner image is
+  ubuntu-24.04 or when ubuntu-latest resolves to ubuntu-24.04.
+
+  This commonly affects:
+  - Workflows that run `gem install` or `bundle install` directly
+  - Custom scripts that call `ruby my-script.rb`
+  - Jekyll static site workflows without the setup-ruby action
+  - Workflows that inherited ubuntu-22.04 behavior when pinned to ubuntu-latest
+
+fix: |
+  Use the ruby/setup-ruby action to install Ruby on any runner. This is the
+  recommended approach for cross-platform consistency and version pinning.
+
+  Alternatively, install Ruby via apt-get if a specific package-managed version
+  is acceptable, but ruby/setup-ruby is strongly preferred for version control.
+
+fix_code:
+  - language: yaml
+    label: "Use ruby/setup-ruby action (recommended)"
+    code: |
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+          bundler-cache: true   # runs bundle install and caches gems
+
+      - run: ruby my-script.rb
+
+  - language: yaml
+    label: "Install via apt-get (version uncontrolled)"
+    code: |
+      - run: sudo apt-get install -y ruby ruby-dev
+
+prevention:
+  - Always use ruby/setup-ruby instead of relying on pre-installed Ruby.
+  - Test workflows against ubuntu-24.04 explicitly before switching ubuntu-latest.
+  - Check the ubuntu-24.04 pre-installed software list when migrating from ubuntu-22.04.
+
+docs:
+  - url: https://github.com/ruby/setup-ruby
+    label: "ruby/setup-ruby — GitHub Actions"
+  - url: https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2404-Readme.md
+    label: "ubuntu-24.04 runner image — pre-installed software"
+  - url: https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2204-Readme.md
+    label: "ubuntu-22.04 runner image — Ruby pre-installed"

package/errors/runner-environment/windows-shell-powershell-is-ps5-not-ps7.yml

@@ -0,0 +1,85 @@
+id: runner-environment-147
+title: "Windows runner 'shell: powershell' invokes PowerShell 5 not PowerShell 7"
+category: runner-environment
+severity: error
+tags:
+  - windows
+  - powershell
+  - pwsh
+  - shell
+  - powershell-version
+
+patterns:
+  - regex: 'The term .{0,20} is not recognized as the name of a cmdlet'
+    flags: i
+  - regex: 'Unexpected token.*\?\.'
+    flags: i
+  - regex: 'parameter cannot be found.*Parallel'
+    flags: i
+
+error_messages:
+  - "The term '??' is not recognized as the name of a cmdlet, function, script file, or operable program."
+  - "Unexpected token '?.' in expression or statement."
+  - "ForEach-Object: A parameter cannot be found that matches parameter name 'Parallel'."
+
+root_cause: |
+  On Windows GitHub-hosted runners, explicitly setting `shell: powershell` in a
+  workflow step invokes `powershell.exe` — Windows PowerShell 5.1 — NOT the modern
+  PowerShell 7.x (pwsh).
+
+  Windows PowerShell 5.1 is a separate executable that lacks numerous features
+  introduced in PowerShell 6.0 (Core) and later:
+  - Null-coalescing operator: `$a ?? $b` (requires PS 7.0+)
+  - Null-coalescing assignment: `$a ??= 'default'` (requires PS 7.0+)
+  - Null-conditional member access: `$obj?.Property` (requires PS 7.0+)
+  - Ternary operator: `$x ? $y : $z` (requires PS 7.0+)
+  - ForEach-Object -Parallel (requires PS 7.0+)
+  - Pipeline chain operators: `&&`, `||` (requires PS 7.0+)
+
+  The default shell on Windows runners (when no `shell:` key is specified) is `pwsh`
+  (PowerShell 7). This means workflows that omit `shell:` work fine, but any step that
+  explicitly adds `shell: powershell` regresses to PowerShell 5.1.
+
+  Developers often set `shell: powershell` when they mean "use PowerShell" without
+  knowing the distinction between Windows PowerShell and PowerShell 7.
+
+fix: |
+  Replace `shell: powershell` with `shell: pwsh` to use PowerShell 7.
+
+  If the workflow requires PowerShell 5.1 compatibility (rare), audit the script
+  and remove PS7-only syntax. However, in almost all cases the intent is PowerShell 7.
+
+fix_code:
+  - language: yaml
+    label: "Use pwsh for PowerShell 7 (fix)"
+    code: |
+      # Before (broken on modern PS syntax):
+      # - run: $value = $null ?? "default"
+      #   shell: powershell
+
+      # After (correct):
+      - run: $value = $null ?? "default"
+        shell: pwsh
+  - language: yaml
+    label: "Set pwsh as default shell for all Windows steps"
+    code: |
+      defaults:
+        run:
+          shell: pwsh
+
+      jobs:
+        build:
+          runs-on: windows-latest
+          steps:
+            - run: $value = $null ?? "default"   # uses pwsh by default
+
+prevention:
+  - 'Use `shell: pwsh` (not `shell: powershell`) in any step using PowerShell 6+ syntax.'
+  - 'Set `defaults.run.shell: pwsh` at workflow level to apply PowerShell 7 globally on Windows.'
+  - 'Use actionlint — it does not currently distinguish PS5 vs PS7 but code review should catch explicit `shell: powershell`.'
+
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-syntax-for-github-actions#jobsjob_idstepsshell'
+    label: 'Workflow syntax: shell — GitHub Docs'
+  - url: 'https://learn.microsoft.com/en-us/powershell/scripting/whats-new/differences-from-windows-powershell'
+    label: 'Differences between Windows PowerShell 5.1 and PowerShell 7 — Microsoft Docs'

package/errors/silent-failures/github-event-inputs-undefined-in-workflow-call.yml

@@ -0,0 +1,102 @@
+id: silent-failures-077
+title: '`github.event.inputs` is undefined (null) when workflow triggered via `workflow_call`'
+category: silent-failures
+severity: silent-failure
+tags:
+  - workflow-call
+  - workflow-dispatch
+  - inputs
+  - github-event-inputs
+  - reusable-workflow
+patterns:
+  - regex: 'github\.event\.inputs\.'
+    flags: 'g'
+  - regex: 'on:\s*\n\s+workflow_call:'
+    flags: 'im'
+error_messages:
+  - "Expression github.event.inputs.environment evaluated to ''"
+  - 'github.event.inputs is null'
+  - 'unexpected value '''''
+root_cause: |
+  When a workflow supports both `workflow_dispatch` and `workflow_call` triggers,
+  developers often use `github.event.inputs.param` to read input values.
+  This works for `workflow_dispatch` but silently fails for `workflow_call`:
+
+  - `workflow_dispatch`: inputs are surfaced at `github.event.inputs.*`
+    (always strings regardless of declared type)
+  - `workflow_call`: inputs are NOT placed in `github.event.inputs`; they are
+    only available via the `inputs` context (`inputs.param`)
+
+  When a reusable workflow is invoked via `workflow_call`, `github.event.inputs`
+  is an empty object — referencing `github.event.inputs.param` evaluates to an
+  empty string `''`, not an error. The workflow continues running with silently
+  missing parameter values, producing incorrect behavior rather than a visible
+  failure.
+
+  The `inputs` context (without `github.event.`) is the correct way to read
+  inputs in both scenarios, as it is populated for both `workflow_dispatch` and
+  `workflow_call`.
+fix: |
+  Replace all `github.event.inputs.*` references with `inputs.*` — the `inputs`
+  context works correctly for both `workflow_dispatch` and `workflow_call` events.
+fix_code:
+  - language: yaml
+    label: 'Use inputs context instead of github.event.inputs'
+    code: |
+      on:
+        workflow_dispatch:
+          inputs:
+            environment:
+              type: string
+              required: true
+        workflow_call:
+          inputs:
+            environment:
+              type: string
+              required: true
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            # BAD: github.event.inputs is empty/null in workflow_call context
+            - run: echo "Deploying to ${{ github.event.inputs.environment }}"
+
+            # GOOD: inputs context works for both workflow_dispatch and workflow_call
+            - run: echo "Deploying to ${{ inputs.environment }}"
+
+  - language: yaml
+    label: 'Dual-trigger workflow using inputs context correctly'
+    code: |
+      on:
+        workflow_dispatch:
+          inputs:
+            dry_run:
+              type: boolean
+              default: false
+        workflow_call:
+          inputs:
+            dry_run:
+              type: boolean
+              default: false
+
+      jobs:
+        release:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            # inputs.dry_run works for both dispatch and call
+            - if: '!inputs.dry_run'
+              run: ./publish.sh
+prevention:
+  - 'Always use the `inputs` context (not `github.event.inputs`) when reading inputs in workflows that support both `workflow_dispatch` and `workflow_call`'
+  - 'Grep your workflow files for `github.event.inputs` and replace with `inputs` before adding a `workflow_call` trigger'
+  - '`github.event.inputs` values are always strings; `inputs` respects the declared type (boolean, number, string, choice)'
+  - 'Test reusable workflows by calling them from another workflow, not just via the UI dispatch button'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_call'
+    label: 'workflow_call event — GitHub Docs'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_dispatch'
+    label: 'workflow_dispatch event — GitHub Docs'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#inputs-context'
+    label: 'inputs context — GitHub Docs'

package/errors/silent-failures/job-outputs-block-missing-needs-always-empty.yml

@@ -0,0 +1,85 @@
+id: silent-failures-076
+title: "Job outputs: block missing — needs.job.outputs.key is always empty string in downstream jobs"
+category: silent-failures
+severity: silent-failure
+tags:
+  - job-outputs
+  - needs-context
+  - GITHUB_OUTPUT
+  - outputs-block
+  - empty-string
+  - downstream-jobs
+patterns:
+  - regex: 'needs\.[a-z_][a-z0-9_-]*\.outputs\.[a-z_][a-z0-9_-]*'
+    flags: 'i'
+error_messages:
+  - "needs.deploy.outputs.artifact_url is always empty string"
+  - "needs.build.outputs.sha: empty output in downstream job"
+root_cause: |
+  Writing to $GITHUB_OUTPUT inside a step only makes the value available within that job
+  via steps.<step_id>.outputs.<key>. To expose an output to downstream jobs via
+  needs.<job>.outputs.<key>, the job must explicitly declare an outputs: block that maps
+  key names to step output expressions using ${{ steps.<id>.outputs.<key> }}.
+
+  Without the job-level outputs: mapping, $GITHUB_OUTPUT writes are silently ignored by
+  downstream consumers — needs.<job>.outputs.<key> evaluates to an empty string with no
+  warning, error, or annotation. The step that wrote to $GITHUB_OUTPUT exits with code 0
+  and no indication of the problem.
+
+  This two-step mechanism is required: the step writes to $GITHUB_OUTPUT (job-internal),
+  and the job's outputs: block re-exports selected values to the workflow's needs graph.
+fix: |
+  Add an outputs: block at the job level (as a sibling of runs-on:, steps:, etc.)
+  that maps the desired key names to the corresponding step output expressions.
+  Every key you want accessible via needs.<job>.outputs.<key> must appear in this block.
+fix_code:
+  - language: yaml
+    label: "Correct: job outputs: block declares which step outputs to expose"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          outputs:
+            artifact-version: ${{ steps.version.outputs.value }}
+            build-sha: ${{ steps.hash.outputs.sha }}
+          steps:
+            - name: Compute version
+              id: version
+              run: echo "value=1.2.3" >> $GITHUB_OUTPUT
+            - name: Compute hash
+              id: hash
+              run: echo "sha=$(sha256sum dist/app | cut -d' ' -f1)" >> $GITHUB_OUTPUT
+
+        deploy:
+          needs: build
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Deploying ${{ needs.build.outputs.artifact-version }}"
+  - language: yaml
+    label: "Wrong: outputs: block absent — needs.build.outputs.* is always empty"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          # No outputs: block — step writes are invisible to downstream jobs
+          steps:
+            - name: Compute version
+              id: version
+              run: echo "value=1.2.3" >> $GITHUB_OUTPUT
+
+        deploy:
+          needs: build
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "${{ needs.build.outputs.artifact-version }}"  # Always ''
+prevention:
+  - "Any job that produces values for downstream jobs MUST have a matching outputs: block"
+  - "Use actionlint — it warns when needs.<job>.outputs.<key> references an undeclared key"
+  - "Debug by printing ${{ toJSON(needs) }} in a downstream step to see all available outputs"
+  - "Note: steps.<id>.outputs.<key> within the same job does NOT require an outputs: block"
+  - "Composite action outputs and reusable workflow outputs have separate but analogous declaration requirements"
+docs:
+  - 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"
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idoutputs"
+    label: "GitHub Docs: jobs.<job_id>.outputs syntax"

package/errors/triggers/push-branches-filter-bypassed-by-tag-push.yml

@@ -0,0 +1,83 @@
+id: triggers-055
+title: "branches: filter does not apply to tag pushes — tag push always triggers unless tags-ignore is set"
+category: triggers
+severity: silent-failure
+tags:
+  - push
+  - branches-filter
+  - tags
+  - tag-push
+  - tags-ignore
+  - ref-type
+patterns:
+  - regex: 'on:\s*\n\s+push:\s*\n\s+branches:'
+    flags: 'm'
+  - regex: 'Triggered by refs/tags/'
+    flags: 'i'
+error_messages:
+  - "Run triggered by push to refs/tags/v1.0.0 (unexpected — only branches: [main] was set)"
+root_cause: |
+  The branches: filter under on.push: only evaluates branch refs (refs/heads/*). A push
+  to a tag ref (refs/tags/*) is an entirely separate ref type that the branches: filter
+  has no authority to gate. If no tags: or tags-ignore: filter is specified under
+  on.push:, ALL tag pushes pass through unconditionally.
+
+  This causes workflows intended to run "only on pushes to main" to also run on every
+  release tag, annotated tag, and automated tag created by CI pipelines.
+
+  Branch and tag filters are independent dimensions of the push event:
+    branches: / branches-ignore:  — applies ONLY to branch refs (refs/heads/*)
+    tags: / tags-ignore:          — applies ONLY to tag refs (refs/tags/*)
+
+  If a filter type is absent, all refs of that type pass through.
+  Setting branches: [main] does NOT automatically exclude tags.
+
+  The same mechanism applies in reverse: a tags: filter does not affect branch pushes.
+  And the paths: filter is also bypassed by tag pushes (see push-paths-filter-bypassed-by-tag).
+fix: |
+  To restrict the workflow to branch pushes only, add a tags-ignore: ['**'] pattern
+  to exclude all tag pushes. Alternatively, add an if: condition to check github.ref_type.
+fix_code:
+  - language: yaml
+    label: "Option 1: add tags-ignore to explicitly exclude all tag pushes"
+    code: |
+      on:
+        push:
+          branches:
+            - main
+            - 'release/**'
+          tags-ignore:
+            - '**'   # Exclude all tag pushes from triggering this workflow
+  - language: yaml
+    label: "Option 2: use if condition on the job to check ref_type"
+    code: |
+      on:
+        push:
+          branches:
+            - main
+
+      jobs:
+        build:
+          if: github.ref_type == 'branch'   # Skip if triggered by a tag push
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Only runs on branch pushes"
+  - language: yaml
+    label: "Option 3: explicitly allow specific tags alongside branches"
+    code: |
+      on:
+        push:
+          branches:
+            - main
+          tags:
+            - 'v[0-9]+.[0-9]+.[0-9]+'  # Only semver release tags; other tags excluded
+prevention:
+  - "Whenever you set branches:, also consider whether you need tags-ignore: ['**'] to exclude tag pushes"
+  - "Check if automated tooling (release-please, semantic-release, etc.) creates tags in your repo — they will trigger this workflow"
+  - "The same principle applies to paths: filter — it also does not block tag pushes"
+  - "Remember the rule: absent filter = all refs of that type pass through"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#onpushbranchestagsbranches-ignoretags-ignore"
+    label: "GitHub Docs: push event branches/tags filter syntax"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#push"
+    label: "GitHub Docs: Push event triggers"

package/errors/triggers/release-created-fires-on-draft.yml

@@ -0,0 +1,75 @@
+id: triggers-056
+title: '`on.release: types: [created]` fires when a draft release is first saved'
+category: triggers
+severity: silent-failure
+tags:
+  - release
+  - triggers
+  - draft
+  - created
+  - published
+patterns:
+  - regex: 'types:\s*\[?created\]?'
+    flags: 'i'
+  - regex: 'on:\s*\n\s+release:'
+    flags: 'im'
+error_messages:
+  - 'Triggered by: release'
+  - 'github.event.action: created'
+  - 'github.event.release.draft: true'
+root_cause: |
+  The `release` event with `types: [created]` fires when ANY release record is
+  first created in GitHub — including draft releases. When a developer clicks
+  "Save draft" to prepare release notes before publishing, GitHub fires the
+  `created` event immediately. This causes deployment or publish workflows to
+  run against an incomplete, unpublished draft.
+
+  The `created` type maps to the moment the release row is inserted in GitHub's
+  database, regardless of draft or published state. Many developers assume
+  `created` means "publicly released" because that mirrors the UI action of
+  clicking "Publish release", but the event fires earlier.
+
+  The correct type for "a release is now publicly visible" is `published`, which
+  fires only when the release transitions from draft (or pre-release) to a
+  published, non-draft release.
+fix: |
+  Use `types: [published]` for workflows that should only run when a release
+  becomes publicly available. Add an `if:` guard as a defensive layer when
+  using `created`.
+fix_code:
+  - language: yaml
+    label: 'Use published instead of created for deploy workflows'
+    code: |
+      # BAD: fires on draft creation too
+      on:
+        release:
+          types: [created]
+
+      # GOOD: fires only when release becomes publicly published
+      on:
+        release:
+          types: [published]
+  - language: yaml
+    label: 'Defensive if: guard when created type is required'
+    code: |
+      on:
+        release:
+          types: [created]
+      jobs:
+        deploy:
+          # Skip execution when triggered by a draft save
+          if: '!github.event.release.draft'
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: ./deploy.sh
+prevention:
+  - 'Prefer `types: [published]` for deployment workflows to avoid triggering on draft saves'
+  - 'Note: `published` also fires when a pre-release is promoted to a full release — guard with `!github.event.release.prerelease` if needed'
+  - 'Add `if: ''!github.event.release.draft''` as an explicit guard when using the `created` type'
+  - 'Test your release workflow by creating a draft release and verifying it does or does not trigger as expected'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#release'
+    label: 'release event — GitHub Docs'
+  - url: 'https://docs.github.com/en/rest/releases/releases#create-a-release'
+    label: 'Create a release REST API — GitHub Docs'

package/errors/yaml-syntax/secrets-in-workflow-level-env-block-rejected.yml

@@ -0,0 +1,91 @@
+id: yaml-syntax-051
+title: "secrets context unavailable in top-level workflow env: block — only valid at job/step level"
+category: yaml-syntax
+severity: error
+tags:
+  - secrets
+  - env-block
+  - workflow-level
+  - context-availability
+  - expression-error
+  - validation
+patterns:
+  - regex: 'Context access might be invalid: secrets'
+    flags: 'i'
+  - regex: 'Unrecognized named-value: .secrets.'
+    flags: 'i'
+  - regex: 'The workflow is not valid.*named-value.*secrets'
+    flags: 'i'
+error_messages:
+  - "The workflow is not valid. .github/workflows/build.yml (Line: 5, Col: 20): Unexpected value 'secrets'"
+  - "Context access might be invalid: secrets"
+  - "Unrecognized named-value: 'secrets'. Located at position 1 within expression: secrets.MY_SECRET"
+root_cause: |
+  The secrets context (${{ secrets.* }}) is only available at the job and step level,
+  not at the top-level (workflow-level) env: block. Placing secret references under the
+  top-level env: key generates a workflow validation error because GitHub evaluates
+  the workflow-level env: block before any job context is established and before
+  secret injection has occurred.
+
+  Available secret context locations:
+    OK  jobs.<job_id>.env:
+    OK  jobs.<job_id>.steps[*].env:
+    OK  jobs.<job_id>.steps[*].with:
+    OK  jobs.<job_id>.container.env:
+    OK  jobs.<job_id>.services.<id>.env:
+    NOT OK  env: (top-level, outside jobs:)
+    NOT OK  jobs.<job_id>.if:
+    NOT OK  jobs.<job_id>.steps[*].if:
+
+  This is the most common cause of the "Unexpected value 'secrets'" validation error
+  in newly written workflows. The workflow fails the pre-run validation check and
+  no jobs execute.
+fix: |
+  Move the secrets reference from the top-level env: block down to the job-level or
+  step-level env: block where the secrets context is available.
+fix_code:
+  - language: yaml
+    label: "Wrong: secrets in top-level env: block generates validation error"
+    code: |
+      env:
+        DB_PASSWORD: ${{ secrets.DB_PASSWORD }}   # Invalid at top level
+        API_TOKEN: ${{ secrets.API_TOKEN }}        # Invalid at top level
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - run: ./run-tests.sh
+  - language: yaml
+    label: "Correct: secrets moved to job-level env: block"
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          env:
+            DB_PASSWORD: ${{ secrets.DB_PASSWORD }}   # Valid at job level
+            API_TOKEN: ${{ secrets.API_TOKEN }}        # Valid at job level
+          steps:
+            - run: ./run-tests.sh
+  - language: yaml
+    label: "Alternative: secrets at step-level env: for minimal exposure"
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Run tests
+              run: ./run-tests.sh
+              env:
+                DB_PASSWORD: ${{ secrets.DB_PASSWORD }}   # Valid at step level
+prevention:
+  - "The top-level env: block only supports literals and expressions that don't reference secrets, needs, or job context"
+  - "Use top-level env: for constants like APP_ENV: production or NODE_ENV: test"
+  - "Prefer step-level env: for secrets to minimize the scope where secrets are exposed"
+  - "actionlint checks context availability and will flag secret-placement errors before push"
+  - "GitHub validates workflow files on push — the validation error appears as a failed check before any job runs"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/contexts#context-availability"
+    label: "GitHub Docs: Context availability"
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#env"
+    label: "GitHub Docs: Workflow env: syntax"

package/package.json

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