@htekdev/actions-debugger 1.0.9 → 1.0.10

package/errors/permissions-auth/deploy-pages-missing-permissions.yml

@@ -0,0 +1,144 @@
+id: permissions-auth-009
+title: "actions/deploy-pages Fails 403 — Missing pages: write or id-token: write Permissions"
+category: permissions-auth
+severity: error
+tags:
+  - deploy-pages
+  - pages
+  - permissions
+  - id-token
+  - oidc
+  - github-token
+  - 403
+patterns:
+  - regex: "Failed to create deployment.*status: 403.*pages: write"
+    flags: "i"
+  - regex: "Resource not accessible by integration"
+    flags: "i"
+  - regex: "Fetching artifact metadata failed.*Resource not accessible by integration"
+    flags: "i"
+  - regex: "Error: Error: Failed to create deployment \\(status: 403\\)"
+    flags: "i"
+error_messages:
+  - "Error: Fetching artifact metadata failed. Is githubstatus.com reporting issues with API requests, Pages or Actions? Please re-run the deployment at a later time."
+  - "Error: HttpError: Resource not accessible by integration"
+  - "Error: Error: Failed to create deployment (status: 403) with build version abc123. Ensure GITHUB_TOKEN has permission \"pages: write\"."
+  - "Creating Pages deployment failed"
+root_cause: |
+  `actions/deploy-pages` uses the GitHub Pages REST API, which requires an OIDC-issued
+  JWT token for authentication. This imposes three distinct permissions that must all be
+  present on the **deploy job** (not the build job):
+
+  1. `pages: write` — allows the GITHUB_TOKEN to create and update GitHub Pages deployments.
+  2. `id-token: write` — allows the runner to request an OIDC JWT from GitHub's token
+     endpoint. Without this, `deploy-pages` cannot obtain the token used to authenticate
+     the Pages API call, resulting in the misleading "Resource not accessible by integration"
+     HTTP 403 error.
+  3. `contents: read` — required to read the uploaded artifact. Often already set by
+     inheritance but must be explicit when a workflow-level `permissions:` block restricts
+     all tokens to read-only.
+
+  **Why this is confusing:**
+  - The error message says "Resource not accessible by integration" which looks like a generic
+    API permission problem, not a missing `id-token` scope.
+  - The `pages: write` permission alone is insufficient — `id-token: write` is equally
+    required and its absence produces the exact same error.
+  - Permissions set at the **workflow level** do not automatically apply to jobs that override
+    them. The deploy job must declare its own `permissions:` block.
+  - The artifact upload (via `actions/upload-pages-artifact`) happens in a SEPARATE job from
+    the deploy — permissions for upload and deploy must be set independently.
+
+  **Source:** Confirmed in `actions/deploy-pages` issues #285, #286 (Dec 2023) — over 16
+  reactions and widespread community impact.
+fix: |
+  Add all three required permissions to the deploy job. The build job that runs
+  `upload-pages-artifact` does not need these permissions, but the deploy job does.
+
+  Also verify that GitHub Pages is enabled for the repository under
+  Settings → Pages → Source → "GitHub Actions".
+fix_code:
+  - language: yaml
+    label: "Correct two-job Pages deployment workflow with required permissions"
+    code: |
+      name: Deploy GitHub Pages
+
+      on:
+        push:
+          branches: [main]
+
+      # Deny all permissions at workflow level; grant explicitly per job
+      permissions:
+        contents: read
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Build site
+              run: npm run build   # outputs to ./dist
+
+            - name: Upload Pages artifact
+              uses: actions/upload-pages-artifact@v3
+              with:
+                path: ./dist
+
+        deploy:
+          needs: build
+          runs-on: ubuntu-latest
+          permissions:
+            pages: write        # ← Required: create/update Pages deployment
+            id-token: write     # ← Required: obtain OIDC JWT for Pages API auth
+            contents: read      # ← Required: read the uploaded artifact
+          environment:
+            name: github-pages
+            url: ${{ steps.deployment.outputs.page_url }}
+          steps:
+            - name: Deploy to GitHub Pages
+              id: deployment
+              uses: actions/deploy-pages@v4
+  - language: yaml
+    label: "Single-job variant — all permissions in one job"
+    code: |
+      name: Deploy Pages (single job)
+
+      on:
+        push:
+          branches: [main]
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          permissions:
+            pages: write
+            id-token: write
+            contents: read
+          environment:
+            name: github-pages
+            url: ${{ steps.deployment.outputs.page_url }}
+          steps:
+            - uses: actions/checkout@v4
+            - name: Build
+              run: npm run build
+            - uses: actions/upload-pages-artifact@v3
+              with:
+                path: ./dist
+            - id: deployment
+              uses: actions/deploy-pages@v4
+prevention:
+  - "Always set `pages: write`, `id-token: write`, and `contents: read` on the deploy job — not the build job and not only at the workflow level."
+  - "Confirm GitHub Pages is enabled under repository Settings → Pages → Source → 'GitHub Actions' before running the workflow."
+  - "When using a workflow-level `permissions:` block that restricts defaults, remember job-level permissions do not inherit write scopes — they must be re-declared."
+  - "The `environment: github-pages` block is required for the Pages API to create a deployment — do not omit it."
+docs:
+  - url: "https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow"
+    label: "GitHub Docs: Publishing GitHub Pages with Actions"
+  - url: "https://github.com/actions/deploy-pages"
+    label: "actions/deploy-pages — official action repository"
+  - url: "https://github.com/actions/deploy-pages/issues/285"
+    label: "actions/deploy-pages #285: Failing to fetch artifact metadata since 4.0.0"
+  - url: "https://github.com/actions/deploy-pages/issues/286"
+    label: "actions/deploy-pages #286: Bump to V4 broke the deploy step"
+  - url: "https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/about-security-hardening-with-openid-connect"
+    label: "GitHub Docs: Security hardening with OpenID Connect"

package/errors/permissions-auth/fine-grained-pat-actions-scope-missing.yml

@@ -0,0 +1,128 @@
+id: permissions-auth-010
+title: "Fine-Grained PAT Missing Actions Permission — Workflow Dispatch and API Calls Fail 403"
+category: permissions-auth
+severity: error
+tags:
+  - fine-grained-pat
+  - pat
+  - personal-access-token
+  - actions
+  - workflow-dispatch
+  - 403
+  - api
+patterns:
+  - regex: "HTTP 403.*fine.?grained.*token"
+    flags: "i"
+  - regex: "Resource not accessible by integration"
+    flags: "i"
+  - regex: "Must have admin rights to Repository\\."
+    flags: "i"
+  - regex: "403.*workflow.*dispatch"
+    flags: "i"
+error_messages:
+  - "HTTP 403: {\"message\":\"Resource not accessible by integration\",\"documentation_url\":\"https://docs.github.com/rest/actions/workflows\"}"
+  - "Error: error making HTTP request: 403 Resource not accessible by integration"
+  - "gh: Could not run workflow: HTTP 422 Unprocessable Entity"
+  - "RequestError [HttpError]: Resource not accessible by integration"
+root_cause: |
+  GitHub fine-grained personal access tokens (introduced 2022, GA 2023) do NOT include
+  the "Actions" permission scope by default when created. This is different from classic
+  PATs where the `repo` scope implicitly granted access to Actions APIs.
+
+  When a fine-grained PAT is used to:
+  - Trigger workflows via REST API (`POST /repos/{owner}/{repo}/actions/workflows/{id}/dispatches`)
+  - List or cancel workflow runs
+  - Download workflow run logs
+  - Use `gh workflow run` / `gh run list` with the PAT as `GH_TOKEN`
+
+  ...the API returns HTTP 403 "Resource not accessible by integration" because the
+  fine-grained token lacks the explicit `Actions: read` or `Actions: write` permission.
+
+  **Why this affects more users over time:**
+  - GitHub is progressively deprecating classic PATs in favor of fine-grained PATs.
+  - Organization policies can require fine-grained PATs only, blocking classic PAT usage.
+  - Automation pipelines that worked with classic `repo`-scoped PATs silently break when
+    migrated to fine-grained PATs if the Actions permission is not explicitly added.
+  - The error message "Resource not accessible by integration" is the same as the one
+    shown for missing `GITHUB_TOKEN` scopes, making diagnosis harder.
+
+  **Required permissions on the fine-grained PAT by use case:**
+  | Use case | Required permission |
+  |---|---|
+  | Trigger workflow (`workflow_dispatch`) | Actions: write |
+  | Cancel / re-run workflow run | Actions: write |
+  | List workflow runs / jobs | Actions: read |
+  | Download workflow run logs | Actions: read |
+  | Read workflow YAML definitions | Actions: read |
+fix: |
+  Regenerate or edit the fine-grained PAT and add the **Actions** permission with the
+  appropriate access level:
+
+  - **Read-only** — for listing runs, reading logs, checking run status.
+  - **Read and write** — for dispatching workflows, cancelling runs, re-triggering jobs.
+
+  Navigate to: GitHub → Settings → Developer Settings → Personal access tokens →
+  Fine-grained tokens → (select token) → Permissions → Repository permissions →
+  Actions → set to "Read and write".
+
+  If the repository is in an organization, also ensure the organization has not restricted
+  fine-grained PAT usage to specific resources that exclude this repository.
+fix_code:
+  - language: yaml
+    label: "Using a fine-grained PAT with Actions permission to trigger a workflow"
+    code: |
+      # Store the fine-grained PAT as a repository secret: DEPLOY_PAT
+      # The PAT must have: Actions: write, Contents: read (minimum)
+
+      name: Trigger Deployment
+
+      on:
+        workflow_dispatch:
+
+      jobs:
+        trigger:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Dispatch downstream workflow
+              run: |
+                gh workflow run deploy.yml \
+                  -f environment=production \
+                  --repo org/downstream-repo
+              env:
+                GH_TOKEN: ${{ secrets.DEPLOY_PAT }}   # Fine-grained PAT with Actions: write
+  - language: yaml
+    label: "Required PAT permissions checklist for common Actions API uses"
+    code: |
+      # Fine-grained PAT permission requirements:
+      #
+      # Trigger workflow dispatch      → Actions: Write
+      # Cancel a workflow run          → Actions: Write
+      # Re-run failed jobs             → Actions: Write
+      # List workflow runs             → Actions: Read
+      # Download run logs              → Actions: Read
+      # Get workflow definition        → Actions: Read
+      # Approve environment deployment → Actions: Write + Environments: Write
+      #
+      # Classic PAT 'repo' scope covers all of the above implicitly.
+      # Fine-grained PATs require explicit opt-in per permission category.
+
+      # To check if your PAT has the right permissions:
+      - name: Verify PAT has Actions permission
+        run: |
+          gh api /repos/${{ github.repository }}/actions/workflows \
+            --jq '.total_count'
+        env:
+          GH_TOKEN: ${{ secrets.DEPLOY_PAT }}   # Returns 403 if Actions: read is missing
+prevention:
+  - "When migrating from classic PATs to fine-grained PATs, explicitly audit which permission categories the classic `repo` scope was implicitly covering and add each one."
+  - "Add `Actions: read` at minimum to any fine-grained PAT that will be used in GitHub Actions pipelines, even for read-only operations."
+  - "Store fine-grained PATs as org-level or repository secrets and add a comment documenting which permissions the PAT requires."
+  - "Use a dedicated machine account (bot user) for automation PATs so permissions can be audited independently of individual developer accounts."
+  - "If an organization policy requires fine-grained PATs, update all automation onboarding docs to include the Actions permission explicitly."
+docs:
+  - url: "https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token"
+    label: "GitHub Docs: Creating a fine-grained personal access token"
+  - url: "https://docs.github.com/en/rest/actions/workflows#create-a-workflow-dispatch-event"
+    label: "REST API: Create a workflow dispatch event"
+  - url: "https://docs.github.com/en/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization"
+    label: "GitHub Docs: PAT policy for organizations"

package/errors/triggers/repository-dispatch-event-type-mismatch.yml

@@ -0,0 +1,116 @@
+id: triggers-010
+title: "repository_dispatch Event Type Not in types: Filter — Workflow Silently Skipped"
+category: triggers
+severity: silent-failure
+tags:
+  - repository_dispatch
+  - event-type
+  - types-filter
+  - triggers
+  - api
+  - silent
+patterns:
+  - regex: "repository_dispatch"
+    flags: "i"
+  - regex: "types:\\s*\\[.*\\]"
+    flags: "i"
+  - regex: "client_payload"
+    flags: "i"
+error_messages:
+  - "No runs found for workflow"
+  - "Workflow not triggered by repository_dispatch event"
+root_cause: |
+  A `repository_dispatch` workflow only fires when the dispatched `event_type` value
+  matches one of the values in the `types:` filter. If the event type sent via the API
+  does not match, GitHub silently drops it — no error, no notification, the workflow simply
+  never starts.
+
+  **Common failure scenarios:**
+
+  1. **Typo or case mismatch**: `event_type: "Deploy_Staging"` dispatched but workflow
+     has `types: [deploy_staging]` (underscore vs case sensitivity). Event types are
+     case-sensitive.
+
+  2. **Omitting the types: filter entirely — workflow fires for ALL events** (opposite
+     problem): Without a `types:` filter, the workflow runs for every `repository_dispatch`
+     event, including internal automation events not intended to trigger it.
+
+  3. **API payload uses wrong field name**: The REST API requires the `event_type` field
+     under the JSON body. Some clients accidentally nest it differently or omit it entirely,
+     causing the dispatch to use the default empty event type which matches nothing.
+
+  4. **Cross-workflow automation chain**: Workflow A dispatches event type `build-complete`.
+     Workflow B listens for `build_complete` (underscore). The chain silently breaks with no
+     logs in either workflow.
+
+  **API payload shape:**
+  ```
+  POST /repos/{owner}/{repo}/dispatches
+  {
+    "event_type": "deploy_staging",       ← Must exactly match types: filter
+    "client_payload": { ... }
+  }
+  ```
+fix: |
+  Verify that the `event_type` string in the API POST body matches exactly (case-sensitive)
+  one of the values declared in the workflow's `types:` filter.
+
+  To debug: add a catch-all workflow with no `types:` filter (matches all repository_dispatch
+  events) to confirm the event is arriving at all, then compare the `github.event.action`
+  value to what your workflow expects.
+fix_code:
+  - language: yaml
+    label: "Workflow with correctly declared repository_dispatch types filter"
+    code: |
+      on:
+        repository_dispatch:
+          types:
+            - deploy_staging        # ← Must match event_type exactly (case-sensitive)
+            - deploy_production
+            - run_smoke_tests
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - name: Show dispatched event
+              run: |
+                echo "Event: ${{ github.event.action }}"
+                echo "Payload: ${{ toJSON(github.event.client_payload) }}"
+  - language: yaml
+    label: "Debugging workflow — catch ALL repository_dispatch events"
+    code: |
+      # Temporarily add this workflow to diagnose missing dispatches
+      on:
+        repository_dispatch:    # No types: filter = receives everything
+
+      jobs:
+        debug:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Log event details
+              run: |
+                echo "event_type / action: ${{ github.event.action }}"
+                echo "client_payload: ${{ toJSON(github.event.client_payload) }}"
+  - language: yaml
+    label: "Dispatching via REST API — correct payload structure"
+    code: |
+      # Using gh api to dispatch correctly
+      gh api \
+        --method POST \
+        -H "Accept: application/vnd.github+json" \
+        /repos/ORG/REPO/dispatches \
+        -f event_type="deploy_staging" \      # ← Matches types: [deploy_staging]
+        -F client_payload='{"version":"v1.2.3","env":"staging"}'
+prevention:
+  - "Treat `event_type` values as constants — define them in a shared location (e.g., a constants file or workflow comment) used by both the dispatcher and the listener."
+  - "Add an `echo` step that logs `github.event.action` at the start of every repository_dispatch workflow to confirm the correct event type was received."
+  - "Use a catch-all debug workflow (no `types:` filter) when setting up a new dispatch chain for the first time."
+  - "Avoid changing event type strings in active automation chains — add new types instead of renaming existing ones."
+  - "Event types are case-sensitive — stick to snake_case by convention to avoid case mismatch bugs."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#repository_dispatch"
+    label: "GitHub Actions: repository_dispatch event"
+  - url: "https://docs.github.com/en/rest/repos/repos#create-a-repository-dispatch-event"
+    label: "REST API: Create a repository dispatch event"

package/errors/triggers/workflow-call-required-input-not-supplied.yml

@@ -0,0 +1,115 @@
+id: triggers-009
+title: "Reusable Workflow Required Input Not Supplied — workflow_call Fails at Runtime"
+category: triggers
+severity: error
+tags:
+  - workflow_call
+  - reusable-workflow
+  - inputs
+  - required
+  - validation
+  - caller
+patterns:
+  - regex: "Input required and not supplied:\\s*\\w+"
+    flags: "i"
+  - regex: "Required input '\\w+' not provided"
+    flags: "i"
+  - regex: "Error: Input required and not supplied"
+    flags: "i"
+error_messages:
+  - "Error: Input required and not supplied: deploy_env"
+  - "Input required and not supplied: version"
+  - "Required input 'environment' not provided by caller"
+root_cause: |
+  Unlike `workflow_dispatch` (which treats `required: true` as UI-only), the GitHub Actions
+  runner DOES validate required inputs for `on.workflow_call` reusable workflows. If a caller
+  workflow invokes a reusable workflow without passing a declared required input, the runner
+  emits `Error: Input required and not supplied: {input_name}` and fails the job immediately.
+
+  **Common scenarios:**
+  1. **Adding a required input to an existing reusable workflow** without updating all callers.
+     Callers that worked before immediately break because the new required input is missing.
+
+  2. **Calling a reusable workflow from a matrix job** where one matrix variation doesn't
+     apply the needed input conditionally.
+
+  3. **Caller passes the input only under certain conditions** (via `if:`) — when the condition
+     is false, the input is omitted entirely rather than being passed as an empty string.
+
+  4. **Typo in the input name** — caller passes `deploy-env` but the reusable workflow expects
+     `deploy_env` (hyphens vs underscores). The declared input is not satisfied.
+
+  **Note:** The error fires at job evaluation time, not step execution time, so the entire job
+  is skipped rather than reaching the failing step.
+fix: |
+  Ensure every caller workflow passes all required inputs declared in the reusable workflow's
+  `on.workflow_call.inputs` block.
+
+  When adding a new required input to a reusable workflow, update all callers before merging.
+  Use `required: false` with a default value if backward compatibility must be preserved.
+
+  If the input is only sometimes needed, declare it as `required: false` and check it
+  at runtime inside the reusable workflow using an early-exit validation step.
+fix_code:
+  - language: yaml
+    label: "Reusable workflow with required input declaration"
+    code: |
+      # .github/workflows/deploy-reusable.yml
+      on:
+        workflow_call:
+          inputs:
+            environment:
+              description: "Target environment"
+              required: true    # Runner enforces this for all callers
+              type: string
+            version:
+              description: "Version tag"
+              required: false
+              default: "latest"
+              type: string
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: ./deploy.sh "${{ inputs.environment }}" "${{ inputs.version }}"
+  - language: yaml
+    label: "Caller workflow — always pass all required inputs"
+    code: |
+      # .github/workflows/release.yml
+      on:
+        push:
+          tags: ["v*"]
+
+      jobs:
+        deploy:
+          uses: ./.github/workflows/deploy-reusable.yml
+          with:
+            environment: production   # ✅ Required input provided
+            version: ${{ github.ref_name }}
+  - language: yaml
+    label: "Backward-compatible: change required to optional with default"
+    code: |
+      # When adding new inputs to existing reusable workflows, use required: false
+      # with a default to avoid breaking existing callers.
+      on:
+        workflow_call:
+          inputs:
+            environment:
+              required: true
+              type: string
+            notify_slack:      # New input — safe to add with required: false
+              required: false
+              default: "false"
+              type: string
+prevention:
+  - "When adding a new `required: true` input to a reusable workflow, search all callers with `grep -r 'uses:.*deploy-reusable'` and update them simultaneously."
+  - "Prefer `required: false` with a sensible default when backward compatibility matters — validate the value inside the reusable workflow if needed."
+  - "Use consistent naming conventions (all underscores or all hyphens) for input names to avoid typo-related mismatches between callers and the called workflow."
+  - "Test reusable workflow changes in a draft PR that also updates all callers."
+docs:
+  - url: "https://docs.github.com/en/actions/sharing-automations/reusing-workflows#using-inputs-and-secrets-in-a-reusable-workflow"
+    label: "GitHub Docs: Inputs in reusable workflows"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_call"
+    label: "GitHub Actions: workflow_call event"

package/errors/triggers/workflow-dispatch-required-input-api-bypass.yml

@@ -0,0 +1,114 @@
+id: triggers-008
+title: "workflow_dispatch required: true Silently Bypassed via REST API"
+category: triggers
+severity: silent-failure
+tags:
+  - workflow_dispatch
+  - inputs
+  - required
+  - rest-api
+  - gh-cli
+  - validation
+patterns:
+  - regex: "workflow_dispatch.*inputs.*required.*true"
+    flags: "i"
+  - regex: "inputs\\.\\w+.*==.*''"
+    flags: "i"
+error_messages:
+  - "Input required and not supplied: {input_name}"
+root_cause: |
+  The `required: true` flag on `workflow_dispatch` inputs is enforced **only in the GitHub
+  UI** — it renders the field as mandatory in the "Run workflow" dialog. When a workflow
+  is triggered via the REST API (`POST /repos/{owner}/{repo}/actions/workflows/{id}/dispatches`)
+  or `gh workflow run`, the `required` flag is NOT validated server-side. The workflow is
+  dispatched and runs with the input set to an empty string `""` rather than the declared
+  default or an error.
+
+  This creates a subtle silent failure: developers assume `required: true` prevents invalid
+  automation, but any API caller can trigger the workflow with no inputs at all. Steps that
+  depend on the input receive an empty string without any indication something is wrong.
+
+  **Contrast with `workflow_call` (reusable workflows):** Required inputs on `on.workflow_call`
+  ARE validated by the runner — a missing required input produces `Error: Input required and
+  not supplied: {input_name}` and the job fails immediately. This inconsistency between the
+  two dispatch types frequently surprises developers.
+
+  **GitHub API behavior (documented):** The REST API returns HTTP 204 (success) even when
+  required inputs are omitted. This is by design — GitHub treats `required: true` as a UI
+  hint only.
+fix: |
+  Treat `required: true` as UI-only and add explicit runtime validation at the top of your
+  workflow or job for any input that is truly required.
+
+  Use an `if:` guard or a validation step that fails the workflow immediately with a clear
+  error message when a required input is empty:
+
+  ```yaml
+  - name: Validate required inputs
+    run: |
+      if [ -z "${{ inputs.environment }}" ]; then
+        echo "::error::Input 'environment' is required but was not provided."
+        exit 1
+      fi
+  ```
+
+  For `gh workflow run` dispatch, newer versions of the CLI (v2.40+) will prompt for
+  required inputs interactively, but non-interactive (CI) invocations must pass `-f key=value`
+  explicitly.
+fix_code:
+  - language: yaml
+    label: "Validate required inputs at runtime with an early-exit step"
+    code: |
+      on:
+        workflow_dispatch:
+          inputs:
+            environment:
+              description: "Target environment (required)"
+              required: true
+              type: choice
+              options: [staging, production]
+            version:
+              description: "Semantic version tag to deploy (required)"
+              required: true
+              type: string
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            # Guard against API bypasses — required: true is UI-only
+            - name: Validate required inputs
+              run: |
+                MISSING=""
+                [ -z "${{ inputs.environment }}" ] && MISSING="$MISSING environment"
+                [ -z "${{ inputs.version }}" ]     && MISSING="$MISSING version"
+                if [ -n "$MISSING" ]; then
+                  echo "::error::Missing required inputs:$MISSING"
+                  exit 1
+                fi
+
+            - uses: actions/checkout@v4
+            - name: Deploy
+              run: ./deploy.sh "${{ inputs.environment }}" "${{ inputs.version }}"
+  - language: yaml
+    label: "Triggering with gh workflow run — always pass required inputs explicitly"
+    code: |
+      # ✅ Correct: pass all required inputs
+      gh workflow run deploy.yml \
+        -f environment=staging \
+        -f version=v1.2.3
+
+      # ❌ Wrong: omits required inputs — workflow still runs, inputs are empty strings
+      gh workflow run deploy.yml
+prevention:
+  - "Never rely on `required: true` alone for server-side enforcement — add a runtime validation step."
+  - "Document in your workflow that inputs must be passed explicitly when triggering via API or CI pipelines."
+  - "For security-critical workflows (deploy, release), use a job-level `if:` condition to block the entire job when an input is empty."
+  - "Consider reusable workflow (`workflow_call`) if you need server-enforced required inputs."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_dispatch"
+    label: "GitHub Actions: workflow_dispatch event"
+  - url: "https://docs.github.com/en/rest/actions/workflows#create-a-workflow-dispatch-event"
+    label: "REST API: Create a workflow dispatch event"
+  - url: "https://cli.github.com/manual/gh_workflow_run"
+    label: "gh workflow run — GitHub CLI manual"

package/package.json

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