@htekdev/actions-debugger 1.0.75 → 1.0.77

package/errors/permissions-auth/org-policy-blocks-pr-creation-despite-pull-requests-write.yml

@@ -0,0 +1,115 @@
+id: permissions-auth-047
+title: "Org-Level Policy Blocks GitHub Actions from Creating or Approving Pull Requests Even with pull-requests: write"
+category: permissions-auth
+severity: error
+tags:
+  - pull-requests
+  - permissions
+  - org-policy
+  - github-token
+  - create-pr
+  - branch-protection
+patterns:
+  - regex: 'GitHub Actions is not permitted to create or approve pull requests'
+    flags: 'i'
+  - regex: 'Resource not accessible by integration'
+    flags: 'i'
+  - regex: 'HttpError.*403.*pull request'
+    flags: 'i'
+error_messages:
+  - "GitHub Actions is not permitted to create or approve pull requests."
+  - "HttpError: Resource not accessible by integration"
+  - "Error: 403 - {\"message\":\"GitHub Actions is not permitted to create or approve pull requests.\",\"documentation_url\":\"https://docs.github.com/rest/pulls/pulls\"}"
+  - "Error: Validation Failed: pull request creation is not allowed for this repository"
+root_cause: |
+  GitHub enforces a two-level policy hierarchy for GitHub Actions creating or
+  approving pull requests:
+
+  1. **Organization level** — GitHub organization owners must enable
+     "Allow GitHub Actions to create and approve pull requests" under:
+     Organization Settings → Actions → General → Workflow permissions
+
+  2. **Repository level** — After the org-level setting is enabled, each repository
+     can independently enable or disable the same option. The repo-level option is
+     grayed out and non-interactive until the org-level gate is open.
+
+  3. **Enterprise level** — For GitHub Enterprise accounts, the same setting must
+     also be enabled at the enterprise level (Enterprise Settings → Actions → General)
+     before it can be configured at the org level.
+
+  Adding `permissions: pull-requests: write` (or `permissions: write-all`) to the
+  workflow YAML only controls the GITHUB_TOKEN's OAuth scope. The org/enterprise policy
+  is an additional administrative gate enforced by the GitHub API regardless of what
+  the token is scoped for. The token can have `pull-requests: write` scope but still
+  receive HTTP 403 if the org policy is disabled.
+
+  The repo-level "Read and write permissions" setting in repo Settings → Actions → General
+  is a second distinct control — it sets the token's default permissions but still
+  cannot override a disabled org-level policy.
+fix: |
+  Step 1 — Enable the setting at the **organization level** (requires org owner):
+    https://github.com/organizations/YOUR_ORG/settings/actions
+    Under "Workflow permissions" → check "Allow GitHub Actions to create and approve pull requests"
+
+  Step 2 — Enable the setting at the **repository level** (the option is now clickable):
+    https://github.com/YOUR_ORG/YOUR_REPO/settings/actions
+    Under "Workflow permissions" → check "Allow GitHub Actions to create and approve pull requests"
+
+  Step 3 — Add the permission to the workflow file:
+    permissions: pull-requests: write (plus contents: write if creating commits)
+
+  For GitHub Enterprise: also enable at enterprise level first:
+    https://github.com/enterprises/YOUR_ENTERPRISE/settings/actions
+
+  For personal accounts (no org):
+    Go to Repository Settings → Actions → General → Workflow permissions →
+    set "Read and write permissions".
+fix_code:
+  - language: yaml
+    label: "Add required permissions to the workflow job"
+    code: |
+      jobs:
+        create-pr:
+          runs-on: ubuntu-latest
+          permissions:
+            contents: write       # required to push branches
+            pull-requests: write  # required to create/comment on PRs
+          steps:
+            - uses: actions/checkout@v4
+            - name: Create Pull Request
+              uses: peter-evans/create-pull-request@v6
+              with:
+                title: 'chore: automated update'
+                branch: 'automated/update'
+  - language: yaml
+    label: "Using gh CLI to create a PR (also requires pull-requests: write + org policy enabled)"
+    code: |
+      jobs:
+        open-pr:
+          runs-on: ubuntu-latest
+          permissions:
+            contents: write
+            pull-requests: write
+          steps:
+            - uses: actions/checkout@v4
+            - name: Open PR
+              env:
+                GH_TOKEN: ${{ github.token }}
+              run: |
+                gh pr create \
+                  --title "chore: automated update" \
+                  --body "Created by GitHub Actions" \
+                  --base main \
+                  --head "${{ github.ref_name }}"
+prevention:
+  - "Before building PR-automation workflows, verify the org-level 'Allow GitHub Actions to create and approve pull requests' setting is enabled."
+  - "Check the setting at all applicable levels — enterprise (if applicable) → organization → repository."
+  - "Always declare explicit `permissions:` in workflows that create PRs; do not rely on repository defaults."
+  - "Use `permissions: pull-requests: write` at the job level (not workflow level) to minimize token scope."
+docs:
+  - 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#preventing-github-actions-from-creating-or-approving-pull-requests"
+    label: "GitHub Docs — Preventing GitHub Actions from creating or approving pull requests"
+  - url: "https://docs.github.com/en/organizations/managing-organization-settings/disabling-or-limiting-github-actions-for-your-organization#preventing-github-actions-from-creating-or-approving-pull-requests"
+    label: "GitHub Docs — Org-level: disabling GitHub Actions from creating pull requests"
+  - url: "https://stackoverflow.com/questions/72376229/github-actions-is-not-permitted-to-create-or-approve-pull-requests"
+    label: "SO: GitHub Actions is not permitted to create or approve pull requests (67 votes, 40k views)"

package/errors/runner-environment/bash-set-e-grep-no-matches-exit-1.yml

@@ -0,0 +1,103 @@
+id: runner-environment-137
+title: "bash -eo pipefail Default Causes grep Exit Code 1 (No Matches) to Fail the Step"
+category: runner-environment
+severity: error
+tags:
+  - bash
+  - grep
+  - pipefail
+  - set-e
+  - shell
+  - exit-code
+patterns:
+  - regex: 'Error: Process completed with exit code 1\.'
+    flags: 'i'
+  - regex: 'grep.*exit code 1'
+    flags: 'i'
+root_cause: |
+  GitHub Actions `run:` steps on Linux/macOS use `bash -e {0}` by default when no
+  `shell:` is specified. When `shell: bash` is explicitly set, the shell is invoked
+  as `bash --noprofile --norc -eo pipefail {0}`, adding `-o pipefail`.
+
+  The key behavior:
+  - `-e` (set -e) — any command that exits non-zero immediately aborts the whole step.
+  - `grep` returns exit code 1 when it finds zero matches (not an error in the shell
+    sense, but a non-zero exit). Combined with `-e`, a `grep` that matches nothing
+    kills the step with "Error: Process completed with exit code 1."
+  - The issue is silent — the step log shows the grep command output (or no output)
+    and then suddenly fails. Developers who test locally (where `set -e` is not the
+    default interactive shell setting) never reproduce the failure.
+
+  Common triggers:
+  - `grep -c pattern file` when pattern not found → exits 1
+  - `git log | grep "pattern"` in CI where the pattern is absent
+  - Variable assignment: `COUNT=$(echo "$LIST" | grep -c "value")` — if grep exits 1,
+    the subshell exits 1, and `-e` aborts the parent step
+error_messages:
+  - "Error: Process completed with exit code 1."
+  - "##[error]Process completed with exit code 1."
+fix: |
+  Several options depending on your use case:
+
+  Option 1 — Disable fail-fast for a specific command using `|| true`:
+  Append `|| true` to any grep command where zero matches is acceptable. The `|| true`
+  ensures the overall expression always exits 0.
+
+  Option 2 — Disable `set -e` for the entire step with `shell: bash {0}`:
+  Using `{0}` as the script placeholder removes the `-e` flag. Use this when you need
+  full control over exit codes throughout the step.
+
+  Option 3 — Use `set +e` at the top of the run block to disable fail-fast for all
+  subsequent commands, then selectively handle errors manually.
+
+  Option 4 — Use grep's `--quiet` / `-q` flag and evaluate with an `if` statement,
+  never relying on exit code propagation.
+fix_code:
+  - language: yaml
+    label: "WRONG — grep exit code 1 kills step when no match found"
+    code: |
+      - name: Count matches
+        run: |
+          COUNT=$(echo "$DIFF" | grep -c "src/my_folder")
+          echo "Changed files: $COUNT"
+  - language: yaml
+    label: "CORRECT — append || true to grep commands where zero matches is valid"
+    code: |
+      - name: Count matches
+        run: |
+          COUNT=$(echo "$DIFF" | grep -c "src/my_folder" || true)
+          echo "Changed files: $COUNT"
+  - language: yaml
+    label: "CORRECT — disable set -e for entire step with shell: bash {0}"
+    code: |
+      - name: Count matches
+        shell: bash {0}
+        run: |
+          COUNT=$(echo "$DIFF" | grep -c "src/my_folder")
+          echo "Changed files: $COUNT"
+          # now exit codes must be checked manually
+  - language: yaml
+    label: "CORRECT — use grep -q with explicit if for boolean presence check"
+    code: |
+      - name: Check for changes
+        run: |
+          if echo "$DIFF" | grep -q "src/my_folder"; then
+            echo "Changes detected in src/my_folder"
+          else
+            echo "No changes in src/my_folder"
+          fi
+prevention:
+  - "Append `|| true` to any `grep`, `awk`, or other command where a non-zero exit is not an error."
+  - "Use `shell: bash {0}` (no `-e`) for steps that need fine-grained exit code handling."
+  - "Prefer `grep -q` with `if/else` blocks instead of relying on grep exit codes for flow control."
+  - "Test CI scripts locally with `bash -e script.sh` to reproduce the fail-fast behavior."
+  - "Use `set -o pipefail` explicitly when you need pipeline failures to surface, and document it."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsshell"
+    label: "jobs.<job_id>.steps[*].shell — default shell invocation"
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#exit-codes-and-error-action-preference"
+    label: "Exit codes and error action preference"
+  - url: "https://stackoverflow.com/questions/73066461/github-actions-why-an-intermediate-command-failure-in-shell-script-would-cause"
+    label: "SO: Why an intermediate command failure causes the whole step to fail (17 votes)"
+  - url: "https://stackoverflow.com/questions/75419587/does-a-github-action-step-use-set-e-semantics-by-default"
+    label: "SO: Does a GitHub action step use set -e semantics by default? (13 votes)"

package/errors/runner-environment/npm-ci-cross-platform-optional-native-binary-missing.yml

@@ -0,0 +1,113 @@
+id: runner-environment-138
+title: "npm ci Cross-Platform Lockfile Missing Optional Native Binaries (esbuild, rollup, vite)"
+category: runner-environment
+severity: error
+tags:
+  - npm
+  - npm-ci
+  - esbuild
+  - rollup
+  - vite
+  - optional-dependencies
+  - cross-platform
+  - lockfile
+  - native-binary
+patterns:
+  - regex: 'Cannot find module @rollup/rollup-linux-x64'
+    flags: 'i'
+  - regex: 'You installed esbuild (on|for) another platform'
+    flags: 'i'
+  - regex: 'Cannot find module @esbuild/linux'
+    flags: 'i'
+  - regex: 'npm has a bug related to optional dependencies'
+    flags: 'i'
+error_messages:
+  - "Cannot find module @rollup/rollup-linux-x64-gnu"
+  - "Cannot find module @rollup/rollup-linux-x64-musl"
+  - "You installed esbuild on another platform than the one you're currently using"
+  - "Cannot find module @esbuild/linux-x64"
+  - "npm has a bug related to optional dependencies (https://github.com/npm/cli/issues/4828). Please try `npm i` again after removing both package-lock.json and node_modules directory."
+root_cause: |
+  Modern JavaScript bundlers (rollup, vite, esbuild, SWC, Turbopack) ship platform-
+  specific optional native binaries as separate npm packages — e.g.,
+  `@rollup/rollup-linux-x64-gnu`, `@esbuild/darwin-arm64`, `@esbuild/linux-x64`.
+
+  When a developer runs `npm install` on macOS (darwin-arm64 or darwin-x64), the
+  generated `package-lock.json` records the macOS-specific optional packages but NOT
+  the Linux equivalents. GitHub-hosted runners run on Linux. When `npm ci` uses
+  this macOS-generated lockfile in CI:
+
+  1. `npm ci` correctly installs exactly what's in the lockfile — only the macOS
+     native binary entries are present.
+  2. The Linux-specific optional dependency (`@rollup/rollup-linux-x64-gnu`) is
+     absent from the lockfile, so `npm ci` never installs it.
+  3. The build step then fails because the required native binary is missing.
+
+  This was a long-standing npm bug (npm/cli#4828) that was fixed in npm 11.3.0
+  (shipped with Node.js 24.0.2). On older npm versions the issue must be worked around.
+
+  Note: `npm ci` itself succeeds — the failure occurs downstream during the build/test
+  step that imports the native module.
+fix: |
+  Option 1 (recommended for npm 11.3.0+ / Node.js 24.0.2+):
+  Update Node.js to 24.0.2 or npm to 11.3.0+, then regenerate the lockfile with
+  `npm install` from scratch. The bug is fixed in this version.
+
+  Option 2 — Explicitly list the Linux optional dependencies in `package.json`:
+  Add all required platform-native packages to the `optionalDependencies` section.
+  npm will then include them in the lockfile regardless of the OS where it was generated.
+
+  Option 3 — Regenerate the lockfile in CI using `npm install --package-lock-only`
+  before running `npm ci`. This is slow but guarantees the lockfile matches the runner OS.
+
+  Option 4 — Use a Linux environment locally (Docker, WSL2, or devcontainer) to
+  generate the lockfile so it contains Linux-specific entries.
+fix_code:
+  - language: yaml
+    label: "Option 2 — Add Linux optional native packages to package.json optionalDependencies"
+    code: |
+      # In package.json, add the Linux optional dependency explicitly:
+      # "optionalDependencies": {
+      #   "@rollup/rollup-linux-x64-gnu": "*"
+      # }
+      # Then run npm install locally to regenerate the lockfile.
+      # In your workflow, npm ci will now install it on Linux runners.
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-node@v4
+              with:
+                node-version: '20'
+                cache: 'npm'
+            - run: npm ci
+            - run: npm run build
+  - language: yaml
+    label: "Option 1 — Use Node.js 24+ where the bug is fixed"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-node@v4
+              with:
+                node-version: '24'   # npm 11.3.0+ ships with Node 24.0.2+
+                cache: 'npm'
+            - run: npm ci
+            - run: npm run build
+prevention:
+  - "Pin your team's lockfile generation to Linux (use devcontainers, Docker, or WSL2 on Windows)."
+  - "Upgrade to Node.js 24.0.2+ or npm 11.3.0+ where the optional dependency platform bug is fixed."
+  - "If cross-platform lockfiles are unavoidable, explicitly add platform-specific packages to `optionalDependencies` in `package.json`."
+  - "After adding `optionalDependencies`, regenerate the lockfile from scratch — delete `package-lock.json` and `node_modules`, then run `npm install`."
+docs:
+  - url: "https://stackoverflow.com/questions/79048814/github-action-is-failing-due-to-rollup-rollup-linux-x64-gnu"
+    label: "SO: Github Action failing due to @rollup/rollup-linux-x64-gnu (13 votes, 8k views)"
+  - url: "https://stackoverflow.com/questions/73139649/you-installed-esbuild-on-another-platform-than-the-one-youre-currently-using"
+    label: "SO: You installed esbuild on another platform (36 votes, 51k views)"
+  - url: "https://github.com/npm/cli/issues/4828"
+    label: "npm/cli#4828 — Optional dependencies not installed for different platform"
+  - url: "https://vitejs.dev/guide/troubleshooting#vite-cjs-node-api-deprecated"
+    label: "Vite troubleshooting — esbuild platform mismatch"

package/errors/runner-environment/ubuntu-24-glibc-binary-incompatibility.yml

@@ -0,0 +1,117 @@
+id: runner-environment-139
+title: "Binaries Built on ubuntu-24.04 Require GLIBC 2.39 — Fail to Execute on ubuntu-22.04 Targets"
+category: runner-environment
+severity: error
+tags:
+  - ubuntu-24.04
+  - ubuntu-latest
+  - glibc
+  - binary-compatibility
+  - linker
+  - distribution
+patterns:
+  - regex: 'version ''GLIBC_2\.3[6-9]'' not found'
+    flags: 'i'
+  - regex: 'libc\.so\.[0-9]+: version ''GLIBC_'
+    flags: 'i'
+  - regex: 'GLIBC_2\.3[6-9] not found \(required by'
+    flags: 'i'
+error_messages:
+  - "/lib/x86_64-linux-gnu/libc.so.6: version 'GLIBC_2.38' not found (required by ./myapp)"
+  - "/lib/x86_64-linux-gnu/libc.so.6: version 'GLIBC_2.39' not found (required by ./myapp)"
+  - "GLIBC_2.39 not found (required by /usr/local/bin/app)"
+  - "version 'GLIBC_2.38' not found"
+root_cause: |
+  GitHub Actions ubuntu-24.04 runners ship with GLIBC 2.39 (GNU C Library). When a
+  binary is compiled or dynamically linked on ubuntu-24.04, the resulting ELF binary
+  records minimum GLIBC version requirements based on the newest symbol version used —
+  either directly or via a linked shared library. If any symbol first introduced in
+  GLIBC 2.36–2.39 is referenced, the binary will fail to load on older systems.
+
+  GLIBC versions by runner image:
+  - ubuntu-20.04: GLIBC 2.31
+  - ubuntu-22.04: GLIBC 2.35
+  - ubuntu-24.04: GLIBC 2.39
+
+  This affects workflows that:
+  1. Build release binaries on ubuntu-latest (which resolved to ubuntu-24.04 in mid-2025)
+     and distribute them for Linux users on ubuntu-22.04 or older.
+  2. Produce binaries in one job on ubuntu-24.04 and run them in a matrix job on
+     ubuntu-22.04 — the artifact fails to execute in the older-runner job.
+  3. Build Docker images using ubuntu-24.04 as the build stage but target a
+     FROM ubuntu:22.04 or FROM debian:bookworm base image in the runtime stage.
+
+  The error only surfaces at execution time, not at compile or link time. The
+  binary appears healthy; only when it is actually run on the older system does
+  the dynamic linker report the missing GLIBC version.
+fix: |
+  Option 1 — Pin the build runner to the oldest supported OS:
+    Use ubuntu-22.04 as the build runner to ensure binaries link against GLIBC 2.35,
+    which is compatible with both ubuntu-22.04 and ubuntu-24.04 targets.
+
+  Option 2 — Build inside a container matching the target OS:
+    Use a Docker container (e.g., ubuntu:22.04) in the build job so the compiler
+    links against the correct GLIBC version regardless of the host runner.
+
+  Option 3 — Cross-compile with musl-libc (static, no GLIBC dependency):
+    For Rust, use the x86_64-unknown-linux-musl target. For C/C++, use musl-gcc or
+    musl-cross. The resulting binary has no GLIBC dependency and runs anywhere.
+
+  Option 4 — Verify GLIBC requirement in CI:
+    Add a validation step that runs objdump or readelf to assert the binary's
+    minimum GLIBC requirement before it reaches distribution.
+fix_code:
+  - language: yaml
+    label: "Pin build runner to ubuntu-22.04 for GLIBC 2.35 compatibility"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-22.04   # GLIBC 2.35 — compatible with ubuntu-22.04 targets
+          steps:
+            - uses: actions/checkout@v4
+            - name: Build binary
+              run: cargo build --release
+            - uses: actions/upload-artifact@v4
+              with:
+                name: my-binary
+                path: target/release/myapp
+  - language: yaml
+    label: "Build inside a Docker container targeting ubuntu:22.04"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          container:
+            image: ubuntu:22.04
+          steps:
+            - name: Install build tools
+              run: |
+                apt-get update
+                apt-get install -y build-essential curl
+            - uses: actions/checkout@v4
+            - name: Build binary
+              run: make release
+  - language: yaml
+    label: "Rust: build static binary with musl (no GLIBC dependency)"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - name: Add musl target
+              run: rustup target add x86_64-unknown-linux-musl
+            - name: Build static binary
+              run: cargo build --release --target x86_64-unknown-linux-musl
+prevention:
+  - "Pin the build runner to the oldest Linux OS your users run when distributing compiled binaries."
+  - "Test binary artifacts in a matrix that includes the oldest supported runner (ubuntu-22.04) as a separate job."
+  - "Use `objdump -T myapp | grep -o 'GLIBC_[0-9.]*' | sort -V | tail -1` to check the minimum GLIBC version before release."
+  - "For maximum portability, use musl-libc or static linking to eliminate the GLIBC runtime dependency entirely."
+docs:
+  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners"
+    label: "GitHub-hosted runners: available images"
+  - url: "https://wiki.ubuntu.com/Releases"
+    label: "Ubuntu release versions and GLIBC versions"
+  - url: "https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2404-Readme.md"
+    label: "ubuntu-24.04 runner image readme"

package/errors/silent-failures/inputs-context-empty-on-non-dispatch-event.yml

@@ -0,0 +1,96 @@
+id: silent-failures-072
+title: "inputs Context Empty on Non-Dispatch Events — Multi-Trigger Workflows Leave inputs.* as Empty String"
+category: silent-failures
+severity: silent-failure
+tags:
+  - inputs
+  - workflow-dispatch
+  - push
+  - multi-trigger
+  - context
+  - empty-string
+patterns:
+  - regex: 'inputs\.[a-zA-Z_][a-zA-Z0-9_-]* (?:is empty|not set|undefined|was null)'
+    flags: 'i'
+error_messages:
+  - "Deploy target is empty — expected inputs.environment to be non-empty"
+  - "Error: Input required and not supplied: environment"
+root_cause: |
+  The `inputs` context in GitHub Actions is ONLY populated when a workflow is triggered
+  by a `workflow_dispatch` or `workflow_call` event. When the same workflow is triggered
+  by any other event — push, pull_request, schedule, release, workflow_run, etc. — the
+  entire `inputs` context is empty. Every `${{ inputs.anything }}` expression evaluates
+  to `""` (empty string) without raising an error or printing a warning.
+
+  This commonly affects developers who:
+  1. Add `on: workflow_dispatch` with inputs to an existing push-triggered workflow
+     to enable manual override capability.
+  2. Reference `${{ inputs.environment }}` or `${{ inputs.deploy_target }}` in `run:`
+     steps, `with:` parameters, or `env:` blocks — expecting a sensible default when
+     triggered automatically by push.
+  3. Use `if: inputs.skip_tests == 'true'` — on push events this is effectively
+     `if: '' == 'true'` which evaluates to false silently.
+  4. Pass `${{ inputs.version }}` to an action's `with: version:` parameter — the
+     action receives an empty string and may silently use its own default or fail
+     with an opaque "invalid version" message.
+
+  The `inputs` context is distinct from `github.event.inputs` (legacy alias, same
+  empty behavior on non-dispatch events) and from the `vars` context (org/repo
+  configuration variables which are always populated).
+fix: |
+  Use the `||` fallback operator to provide defaults for all inputs in workflows
+  that support multiple triggers. This guarantees non-dispatch triggers receive
+  a sensible default instead of an empty string.
+
+  Guard dispatch-only logic blocks with `if: github.event_name == 'workflow_dispatch'`
+  to explicitly skip input-dependent steps on automated trigger runs.
+fix_code:
+  - language: yaml
+    label: "Provide fallback defaults for all inputs in multi-event workflows"
+    code: |
+      on:
+        push:
+          branches: [main]
+        workflow_dispatch:
+          inputs:
+            environment:
+              type: choice
+              options: [staging, production]
+              default: staging
+            skip_tests:
+              type: boolean
+              default: false
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          env:
+            # Use || to fall back to defaults when triggered by push
+            DEPLOY_ENV: ${{ inputs.environment || 'staging' }}
+            SKIP_TESTS: ${{ inputs.skip_tests || 'false' }}
+          steps:
+            - name: Deploy
+              run: echo "Deploying to $DEPLOY_ENV (skip_tests=$SKIP_TESTS)"
+  - language: yaml
+    label: "Guard input-dependent logic with event_name check"
+    code: |
+      steps:
+        - name: Apply manual override (dispatch only)
+          if: github.event_name == 'workflow_dispatch'
+          run: echo "Manual dispatch with environment=${{ inputs.environment }}"
+
+        - name: Default automated deploy
+          if: github.event_name != 'workflow_dispatch'
+          run: echo "Automated push deploy to staging"
+prevention:
+  - "Always use `${{ inputs.param || 'default' }}` when a workflow supports more than one trigger — never assume inputs will be populated."
+  - "Log `github.event_name` at the start of the workflow to trace which trigger fired and aid debugging of empty-input behavior."
+  - "Use the 'Context availability' table in GitHub Actions documentation to verify which contexts are populated for each event type before referencing them."
+  - "Consider splitting dispatch workflows (with inputs) from automated trigger workflows — combining both in one file with shared input-referencing code is a common source of subtle bugs."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/contexts#inputs-context"
+    label: "GitHub Actions: inputs context"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_dispatch"
+    label: "workflow_dispatch event"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/contexts#context-availability"
+    label: "Context availability by event type"

package/errors/silent-failures/vars-context-undefined-variable-empty-string.yml

@@ -0,0 +1,84 @@
+id: silent-failures-073
+title: "vars. Context Returns Empty String for Undefined Organization or Repository Variables — No Error Raised"
+category: silent-failures
+severity: silent-failure
+tags:
+  - vars
+  - configuration-variables
+  - context
+  - empty-string
+  - organization
+  - repository
+patterns:
+  - regex: 'vars\.[A-Z_][A-Z0-9_]* (?:is empty|not set|missing|undefined|not defined)'
+    flags: 'i'
+error_messages:
+  - "Error: REGISTRY_URL is empty — check that vars.REGISTRY_URL is defined in repository variables"
+  - "Error: docker tag '' is not valid"
+  - "fatal: repository '' does not exist"
+root_cause: |
+  GitHub Actions configuration variables (the `vars` context, introduced 2023) provide a
+  non-secret key/value store at the organization, repository, or environment level. When
+  a `${{ vars.MY_VARIABLE }}` expression references a variable that has not been defined
+  at any applicable scope, the expression evaluates to `""` (empty string) without
+  raising any error, warning, or annotation in the Actions run UI.
+
+  Unlike missing secrets (which also silently return empty string), `vars` variables are
+  user-visible and frequently forgotten when:
+  1. A workflow is used in a new repository that hasn't had its variables configured.
+  2. A variable is defined at the repository level but the job targets an environment
+     that doesn't inherit repo-level variables (environment-scoped variables override
+     but do not merge with repo-scoped variables of the same name).
+  3. A variable is defined only at the organization level but the repository is
+     a fork — forked repositories cannot access parent org variables.
+  4. The variable name has a typo in the workflow file.
+
+  Silent empty values cascade into confusing downstream errors: Docker tags become `":latest"`
+  instead of `"ghcr.io/org/image:latest"`, API endpoints receive empty base URLs, and
+  notification webhooks silently fail with HTTP 400.
+
+  Environment-scoped variables are ONLY available when the job specifies `environment:`.
+  If a job has no `environment:` key, env-scoped variables are not available even if
+  the env-scoped variable has the same name as a repo-scoped variable.
+fix: |
+  Use the `||` fallback operator to provide safe defaults, and add an explicit
+  validation step for variables that are required for the workflow to succeed.
+fix_code:
+  - language: yaml
+    label: "Use || fallback for optional vars"
+    code: |
+      env:
+        REGISTRY: ${{ vars.REGISTRY_URL || 'ghcr.io' }}
+        LOG_LEVEL: ${{ vars.LOG_LEVEL || 'info' }}
+        API_BASE: ${{ vars.API_BASE_URL || 'https://api.example.com' }}
+  - language: yaml
+    label: "Validate required vars at workflow start with fail-fast"
+    code: |
+      jobs:
+        preflight:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Validate required configuration variables
+              env:
+                REGISTRY_URL: ${{ vars.REGISTRY_URL }}
+                DEPLOY_ENV: ${{ vars.DEPLOY_ENV }}
+              run: |
+                missing=()
+                [ -z "$REGISTRY_URL" ] && missing+=("vars.REGISTRY_URL")
+                [ -z "$DEPLOY_ENV" ]   && missing+=("vars.DEPLOY_ENV")
+                if [ ${#missing[@]} -gt 0 ]; then
+                  echo "::error::Missing required variables: ${missing[*]}"
+                  echo "Set them at: Settings → Secrets and Variables → Variables"
+                  exit 1
+                fi
+prevention:
+  - "Document all required `vars.*` variables in the repository README or CONTRIBUTING guide — unlike required inputs, they have no built-in validation."
+  - "Add a preflight validation job that checks for required variables and fails immediately with a clear error message."
+  - "Use `${{ vars.SETTING || 'sensible-default' }}` consistently to make empty-variable behavior explicit."
+  - "For environment-scoped variables, ensure the job specifies `environment:` — variables defined only on an environment are not available to jobs that omit the environment key."
+  - "Use repository variable naming conventions (UPPER_SNAKE_CASE) and check for typos in workflow YAML against the variables defined in Settings."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables"
+    label: "GitHub Actions: configuration variables (vars context)"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/contexts#vars-context"
+    label: "vars context reference"

package/errors/triggers/required-status-check-not-in-branch-protection-dropdown.yml

@@ -0,0 +1,115 @@
+id: triggers-052
+title: "Required Status Check Not Appearing in Branch Protection Dropdown"
+category: triggers
+severity: limitation
+tags:
+  - branch-protection
+  - required-status-check
+  - check-name
+  - job-name
+  - workflow-name
+  - protected-branch
+patterns:
+  - regex: 'status check.*not found'
+    flags: 'i'
+  - regex: 'waiting for status to be reported'
+    flags: 'i'
+error_messages:
+  - "Waiting for status to be reported"
+  - "Required status check is expected — check name not found in the dropdown"
+root_cause: |
+  Branch protection required status checks have several constraints that cause them
+  to silently not appear in the "Status checks that are required" search dropdown:
+
+  1. **Wrong name searched** — The check name in branch protection is the job's
+     `name:` field (if set) or the job's YAML key (ID) — NOT the workflow's `name:`
+     field. Developers often search for the workflow name and can't find the check.
+     For matrix jobs, the check name includes matrix values:
+     e.g., `build (ubuntu-latest, 20.x)` not just `build`.
+
+  2. **Check must have run recently** — A status check only appears in the dropdown
+     after it has completed successfully at least once on that repository within the
+     past 7 days. Brand-new workflows that have never been triggered won't show up.
+
+  3. **Workflow must target the protected branch** — For PR-triggered checks, the
+     workflow must have `on: pull_request: branches: [main]` (or the target branch).
+     A workflow that only runs on `push` to feature branches never posts a status
+     to main's pull requests.
+
+  4. **Paths filters suppressing the check** — If the workflow has `paths:` filters,
+     PRs that don't change filtered files never trigger the workflow, so the check
+     is absent (causing PRs to be permanently stuck as "Waiting"). This is covered
+     separately in `required-status-check-paths-filter-pr-stuck.yml`.
+
+  All of these issues are silent — no error is shown. The dropdown simply doesn't
+  include the expected check name.
+fix: |
+  Step 1 — Confirm the exact check name:
+  Go to any recently-merged or open PR in the repository. Find the check in the
+  PR's "Checks" tab. Copy the exact displayed name — it is the job's `name:` field
+  or the YAML job key, not the workflow `name:` at the top of the file.
+  For matrix jobs, include the matrix combination: `build (ubuntu-latest, 20.x)`.
+
+  Step 2 — Trigger the workflow at least once on a PR against the protected branch:
+  The check must have a successful run within the past 7 days to appear.
+  Create a test PR or push a temporary commit to get the first run.
+
+  Step 3 — Add a descriptive `name:` to each job that will be a required check.
+  This makes the check name human-readable and stable even if you rename the job key.
+
+  Step 4 — For matrix workflows, consider adding a fanout job (a job that `needs:`
+  all matrix jobs) with a simple pass/fail step, and set THAT as the required check.
+  This avoids needing to list every matrix combination individually in branch protection.
+fix_code:
+  - language: yaml
+    label: "Add explicit job name for a stable, searchable required status check name"
+    code: |
+      jobs:
+        build:
+          name: "CI Build"   # This is the check name in branch protection, NOT 'build'
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm ci && npm test
+  - language: yaml
+    label: "Matrix jobs — add a fanout job to use as the single required check"
+    code: |
+      jobs:
+        test:
+          name: "Test (${{ matrix.os }}, Node ${{ matrix.node }})"
+          runs-on: ${{ matrix.os }}
+          strategy:
+            matrix:
+              os: [ubuntu-latest, windows-latest]
+              node: ['18', '20']
+          steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-node@v4
+              with:
+                node-version: ${{ matrix.node }}
+            - run: npm ci && npm test
+
+        all-tests-pass:
+          name: "All Tests Pass"   # Set THIS as the required status check
+          needs: test
+          runs-on: ubuntu-latest
+          if: always()
+          steps:
+            - name: Verify all matrix jobs passed
+              run: |
+                if [[ "${{ needs.test.result }}" != "success" ]]; then
+                  echo "One or more test matrix jobs failed"
+                  exit 1
+                fi
+prevention:
+  - "Always add a `name:` to jobs that will be required status checks — job IDs change when refactoring."
+  - "Trigger the workflow at least once before setting up branch protection, so the check appears in the dropdown."
+  - "For matrix jobs, add a dedicated fanout job that passes only when all matrix jobs pass; set it as the required check."
+  - "Avoid `paths:` filters on required-check workflows — use them on optional checks only, or use `required-status-check-paths-filter-pr-stuck.yml` workaround."
+docs:
+  - url: "https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/troubleshooting-required-status-checks"
+    label: "GitHub Docs — Troubleshooting required status checks"
+  - url: "https://stackoverflow.com/questions/68554735/github-action-status-check-missing-from-the-list-of-checks-in-protected-branch-s"
+    label: "SO: Github Action Status check missing from Protected branch settings (75 votes, 29k views)"
+  - url: "https://stackoverflow.com/questions/61989951/github-action-workflow-not-running"
+    label: "SO: GitHub Action workflow not running (158 votes, 202k views)"

package/errors/yaml-syntax/env-variable-name-dot-expression-subproperty-access.yml

@@ -0,0 +1,101 @@
+id: yaml-syntax-049
+title: "env Variable Name with Dots — ${{ env.MY.VAR }} Silently Reads Undefined Subproperty"
+category: yaml-syntax
+severity: silent-failure
+tags:
+  - env-context
+  - expression-syntax
+  - dots
+  - property-access
+  - empty-string
+  - naming
+patterns:
+  - regex: '\$\{\{\s*env\.[A-Za-z_][A-Za-z0-9_]*\.[A-Za-z_]'
+    flags: ''
+  - regex: '\$\{\{\s*vars\.[A-Za-z_][A-Za-z0-9_]*\.[A-Za-z_]'
+    flags: ''
+error_messages:
+  - "Error: Expected non-empty value but got '' (env.MY.VAR resolved to empty string)"
+  - "::error::Variable 'app.version' is empty — check expression syntax"
+root_cause: |
+  GitHub Actions expression syntax uses the dot (`.`) character as a property accessor
+  for traversing nested context objects. When an environment variable name contains a
+  dot (e.g., `MY.VAR`, `app.version`, `node.options`), the expression `${{ env.MY.VAR }}`
+  is evaluated by the expression parser as two sequential property dereferences:
+
+  1. `env.MY` — look up the property named exactly `MY` on the env object
+  2. `.VAR`   — look up the property named `VAR` on the result of step 1
+
+  If no environment variable named exactly `MY` exists (only `MY.VAR` does), then
+  `env.MY` returns `""` (empty string), and the entire expression silently evaluates
+  to `""` with no error or warning.
+
+  This is legal YAML — `env: MY.VAR: 'hello'` is valid YAML syntax and DOES set the
+  shell environment variable `MY.VAR` in `run:` steps. Linux and macOS allow dots in
+  env var names. The problem is exclusively in the expression layer: `${{ env.MY.VAR }}`
+  cannot reach the variable because `.` is an operator, not part of the identifier.
+
+  The same issue affects the `vars` context: `${{ vars.app.version }}` attempts to
+  read a sub-property `version` of a variable named `app`, not a variable named
+  `app.version`.
+
+  actionlint does not currently warn on dotted env/vars expressions because the
+  expression syntax is technically valid — it just resolves to empty string at runtime.
+fix: |
+  Option 1 — Rename environment variables to use underscores instead of dots (recommended):
+    Change `MY.VAR` to `MY_VAR`. This is the POSIX-conventional approach and works
+    reliably with all GitHub Actions expression syntax.
+
+  Option 2 — Use bracket property accessor syntax:
+    `${{ env['MY.VAR'] }}` uses the array/bracket notation which treats the entire
+    string `MY.VAR` as a single property key, correctly reading the dotted variable.
+
+  Option 3 — Access the variable via shell syntax in run: steps:
+    In `run:` steps the shell receives the full env var with its dotted name. Use
+    the shell variable reference directly in shell scripts, not in expressions.
+fix_code:
+  - language: yaml
+    label: "Rename to underscores (recommended)"
+    code: |
+      env:
+        MY_VAR: 'hello'        # was MY.VAR — underscore works in expressions
+        APP_VERSION: '1.2.3'   # was app.version
+
+      steps:
+        - name: Read variable
+          run: echo "Version is ${{ env.APP_VERSION }}"
+  - language: yaml
+    label: "Bracket syntax for dotted env var names"
+    code: |
+      env:
+        MY.VAR: 'hello'         # dotted name is set in the shell env
+
+      steps:
+        - name: Read via bracket syntax
+          run: echo "Value is ${{ env['MY.VAR'] }}"
+          # BAD:  ${{ env.MY.VAR }}     → silently reads undefined subproperty
+          # GOOD: ${{ env['MY.VAR'] }}  → reads the full dotted variable name
+  - language: yaml
+    label: "Access dotted env var directly in shell (run: steps only)"
+    code: |
+      env:
+        MY.VAR: 'hello'
+
+      steps:
+        - name: Use shell variable directly
+          run: |
+            # The shell receives the env var with its dotted name
+            # Access it via indirect parameter expansion
+            VAR_NAME='MY.VAR'
+            echo "${!VAR_NAME}"   # bash indirect expansion
+prevention:
+  - "Never use dots in environment variable names in `env:` blocks — always use UPPER_SNAKE_CASE with underscores."
+  - "When consuming third-party tooling that sets dotted env var names, immediately re-export them with underscore names for safe use in expressions."
+  - "Review any expression containing two dots in the same context path (e.g., `env.a.b`) — this almost always indicates a naming mistake."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/contexts#env-context"
+    label: "GitHub Actions: env context"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/evaluate-expressions-in-workflows-and-actions#property-dereference"
+    label: "Property dereference in expressions"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/evaluate-expressions-in-workflows-and-actions"
+    label: "Evaluate expressions in workflows and actions"

package/package.json

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