@htekdev/actions-debugger 1.0.80 → 1.0.82

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/if-failure-not-triggered-on-cancellation.yml

@@ -0,0 +1,96 @@
+id: silent-failures-075
+title: "if: failure() notification job is skipped when workflow is manually cancelled"
+category: silent-failures
+severity: silent-failure
+tags:
+  - if-condition
+  - failure
+  - cancelled
+  - always
+  - notification
+  - cleanup
+patterns:
+  - regex: 'if:\s*failure\(\)'
+    flags: 'i'
+  - regex: 'Skipping.*cancelled'
+    flags: 'i'
+error_messages:
+  - "Skipping: The job was skipped because one or more of its needs jobs was cancelled."
+root_cause: |
+  When a workflow is manually cancelled (via the GitHub UI "Cancel run" button or
+  the REST API), in-progress jobs receive a cancellation signal. Jobs that have not
+  yet started are given the conclusion "cancelled". Jobs with if: failure() are
+  only evaluated against the "failure" conclusion — "cancelled" is a distinct
+  conclusion value. Because cancelled != failure, the condition evaluates to false
+  and the notification or cleanup job is silently skipped.
+
+  This catches teams by surprise when they add an alerting job intended to fire
+  whenever CI does not succeed:
+
+    notify-on-failure:
+      needs: build
+      if: failure()
+      runs-on: ubuntu-latest
+      steps:
+        - name: Send Slack alert
+          ...
+
+  When an operator cancels a run mid-flight, the build job is marked cancelled,
+  not failed. The notify job evaluates if: failure() → false and is skipped with
+  no Slack message. The on-call team receives no signal that a run was interrupted.
+
+  The failure() function returns true only when at least one needed job has a
+  "failure" conclusion. It does NOT return true for "cancelled" conclusions.
+fix: |
+  Use if: failure() || cancelled() to catch both failure and cancellation, or use
+  if: always() combined with a conditional check on the job's outcome inside the
+  step if you only want to act on non-success outcomes.
+fix_code:
+  - language: yaml
+    label: "Catch both failure and cancellation in a notification job"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - run: make build
+
+        notify-on-failure:
+          needs: build
+          # failure() catches job failures; cancelled() catches manual cancellation
+          if: failure() || cancelled()
+          runs-on: ubuntu-latest
+          steps:
+            - name: Send failure or cancellation alert
+              run: |
+                echo "Build concluded: ${{ needs.build.result }}"
+                # Send Slack/PagerDuty notification here
+  - language: yaml
+    label: "Use always() and gate on outcome inside the step for fine-grained control"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - run: make build
+
+        notify:
+          needs: build
+          if: always()
+          runs-on: ubuntu-latest
+          steps:
+            - name: Notify only on non-success outcomes
+              if: needs.build.result != 'success'
+              run: |
+                echo "Build result: ${{ needs.build.result }}"
+                # Handles: failure, cancelled, skipped
+prevention:
+  - "Use if: failure() || cancelled() instead of if: failure() for any alert, notification, or cleanup job that must run whenever CI does not succeed."
+  - "Prefer if: always() when the downstream job should run regardless of upstream outcome (e.g., always upload test reports)."
+  - "Audit all notification and cleanup jobs after cancellation to confirm they fired as expected — cancelled runs don't generate failure alerts by default."
+  - "The cancelled() function returns true when the workflow or job has been cancelled; combine with failure() using || for comprehensive coverage."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-conditions-to-control-job-execution"
+    label: "GitHub Actions: Using conditions to control job execution"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-conditions-to-control-job-execution#available-status-check-functions"
+    label: "GitHub Actions: Available status check functions — failure(), cancelled(), always()"

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/triggers/workflow-dispatch-choice-input-api-no-validation.yml

@@ -0,0 +1,98 @@
+id: triggers-054
+title: "workflow_dispatch choice input not validated when triggered via REST API — invalid values silently accepted"
+category: triggers
+severity: silent-failure
+tags:
+  - workflow-dispatch
+  - choice-input
+  - rest-api
+  - inputs
+  - validation
+  - gh-cli
+patterns:
+  - regex: 'type:\s*choice'
+    flags: 'i'
+  - regex: 'inputs\.\w+.*choice'
+    flags: 'i'
+error_messages:
+  - "Workflow ran with input value not in declared choices list"
+root_cause: |
+  The type: choice input in on.workflow_dispatch.inputs renders a dropdown
+  selector in the GitHub Actions UI and prevents users from submitting values
+  outside the declared options list. This validation is enforced entirely
+  client-side in the browser.
+
+  When a workflow is triggered via the GitHub REST API
+  (POST /repos/{owner}/{repo}/actions/workflows/{id}/dispatches) or the GitHub
+  CLI (gh workflow run --field key=value), GitHub does NOT validate that the
+  supplied value matches any of the declared choices. Any arbitrary string is
+  accepted and forwarded as-is to the workflow.
+
+  A workflow dispatched with inputs: { environment: "PROD" } when the declared
+  choices are ["prod", "staging", "dev"] will run with inputs.environment == "PROD".
+  Every if: condition that compares against the lower-case variants evaluates to
+  false, all deployment branches are skipped, and the workflow exits successfully
+  with no indication that the value was invalid. The mistyped run is invisible
+  unless logs are inspected manually.
+fix: |
+  Add an explicit allowlist validation step at the top of the workflow that checks
+  the input value and exits with a non-zero status and a descriptive error message
+  if the value is not in the expected set. This makes API-triggered runs fail fast
+  with a clear error rather than silently no-oping.
+fix_code:
+  - language: yaml
+    label: "Validate choice input with an allowlist check"
+    code: |
+      on:
+        workflow_dispatch:
+          inputs:
+            environment:
+              type: choice
+              description: Target deployment environment
+              options:
+                - prod
+                - staging
+                - dev
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Validate environment input
+              run: |
+                allowed="prod staging dev"
+                input="${{ inputs.environment }}"
+                if [[ ! " $allowed " =~ " ${input} " ]]; then
+                  echo "::error::Invalid environment '${input}'. Allowed values: $allowed"
+                  exit 1
+                fi
+
+            - name: Deploy to ${{ inputs.environment }}
+              run: echo "Deploying to ${{ inputs.environment }}"
+  - language: yaml
+    label: "Case-insensitive validation with normalisation"
+    code: |
+      - name: Validate and normalise environment input
+        id: validate
+        run: |
+          input=$(echo "${{ inputs.environment }}" | tr '[:upper:]' '[:lower:]')
+          allowed=("prod" "staging" "dev")
+          valid=false
+          for v in "${allowed[@]}"; do
+            [[ "$input" == "$v" ]] && valid=true && break
+          done
+          if [[ "$valid" != "true" ]]; then
+            echo "::error::Unrecognised environment '${{ inputs.environment }}' (normalised: '$input'). Allowed: ${allowed[*]}"
+            exit 1
+          fi
+          echo "environment=$input" >> "$GITHUB_OUTPUT"
+prevention:
+  - "Treat type: choice as a UI hint only — always validate inputs programmatically inside the workflow."
+  - "Add an allowlist guard as the first step of any job that branches on a choice input."
+  - "Document valid values and casing rules in the input description field so API callers know the expected format."
+  - "Use actionlint to detect misspelled choices at authoring time before they reach production."
+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 — inputs"
+  - url: "https://docs.github.com/en/rest/actions/workflows#create-a-workflow-dispatch-event"
+    label: "GitHub REST API: Create a workflow dispatch event"