@htekdev/actions-debugger 1.0.23 → 1.0.24

package/errors/silent-failures/reusable-workflow-output-skipped-contains-secret.yml

@@ -0,0 +1,115 @@
+id: silent-failures-030
+title: "Reusable Workflow Output Silently Dropped When Value Contains a Secret Substring"
+category: silent-failures
+severity: silent-failure
+tags:
+  - reusable-workflows
+  - secrets-masking
+  - workflow-outputs
+  - workflow-call
+  - secret-substring
+  - output-propagation
+patterns:
+  - regex: "Skip output '\\w+' since it may contain secret"
+    flags: "i"
+  - regex: "Skip output.*may contain secret"
+    flags: "i"
+error_messages:
+  - "Skip output 'file-url' since it may contain secret."
+  - "Skip output 'artifact-path' since it may contain secret."
+  - "Skip output 'deploy-url' since it may contain secret."
+root_cause: |
+  When a reusable workflow (called via `workflow_call`) propagates a workflow-level `output`
+  whose value contains a substring matching any registered secret, the runner **silently drops
+  the entire output** and logs "Skip output 'X' since it may contain secret." in the callee
+  workflow's log. The calling workflow's `needs.<job>.outputs.X` resolves to an empty string
+  with no error or warning in the caller's logs.
+
+  The runner performs substring matching — if ANY registered secret appears anywhere within the
+  output string (even as a short substring), the runner refuses to propagate the output. Common
+  triggers:
+  - S3 URLs where part of the bucket path matches an AWS access key fragment
+  - File paths with directory components that happen to match a short registered secret
+  - Outputs containing account IDs, port numbers, or other short secrets that appear in
+    longer strings by coincidence
+  - Base64-encoded outputs whose encoding coincidentally contains a secret substring
+
+  This is distinct from `job-output-masked-as-secret-empty` (regular job step outputs masked
+  by actions/runner#1498). The "Skip output" message only appears in reusable workflow output
+  propagation and is ONLY visible in the callee's log — the caller shows no warning, making
+  diagnosis extremely difficult.
+fix: |
+  Avoid including values that contain (or match substrings of) registered secrets in reusable
+  workflow outputs. Structural approaches:
+
+  1. **Return only the non-secret portion** of a path or URL, and reconstruct the full value
+     in the calling workflow using `vars` context or a known prefix.
+  2. **Use artifacts** (`actions/upload-artifact` / `actions/download-artifact`) to pass files
+     or large data payloads between the callee and caller instead of workflow outputs.
+  3. **Check callee logs** for "Skip output" messages — they are invisible from the caller side.
+  4. **Review short secrets**: secrets shorter than ~8 characters risk false-positive substring
+     matches. Consider rotating short secrets to longer values.
+fix_code:
+  - language: yaml
+    label: "Return non-secret path portion; reconstruct in caller"
+    code: |
+      # ❌ BROKEN: output contains secret substring (S3 bucket name matches a secret)
+      on:
+        workflow_call:
+          outputs:
+            artifact-url:
+              value: ${{ jobs.build.outputs.url }}   # silently skipped if URL contains secret
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          outputs:
+            url: ${{ steps.upload.outputs.file-url }}
+          steps:
+            - id: upload
+              run: |
+                echo "file-url=https://s3.amazonaws.com/${{ secrets.BUCKET_NAME }}/build-${{ github.run_id }}.zip" \
+                  >> "$GITHUB_OUTPUT"
+
+      ---
+
+      # ✅ WORKAROUND: return only the non-secret key; caller prepends known S3 prefix
+      on:
+        workflow_call:
+          outputs:
+            artifact-key:
+              value: ${{ jobs.build.outputs.key }}   # just "build-12345678.zip" — no secret
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          outputs:
+            key: ${{ steps.upload.outputs.key }}
+          steps:
+            - id: upload
+              run: echo "key=build-${{ github.run_id }}.zip" >> "$GITHUB_OUTPUT"
+  - language: yaml
+    label: "Use artifacts to pass files between reusable workflow and caller"
+    code: |
+      # In the reusable workflow job:
+      - uses: actions/upload-artifact@v4
+        with:
+          name: build-output-${{ github.run_id }}
+          path: dist/
+
+      # In the calling workflow job (after the reusable workflow completes):
+      - uses: actions/download-artifact@v4
+        with:
+          name: build-output-${{ github.run_id }}
+          path: dist/
+prevention:
+  - "Never include secret-containing values (URLs, paths, credentials) as reusable workflow outputs."
+  - "Reserve workflow outputs for short, non-sensitive metadata: version strings, boolean flags, run IDs."
+  - "Use artifacts for any data payload that might contain a value related to a registered secret."
+  - "Always check callee workflow logs — not just caller logs — for 'Skip output' messages."
+  - "Register secrets that are long and unique enough not to appear as substrings in build output values."
+docs:
+  - url: "https://stackoverflow.com/questions/72536256/output-in-reusable-workflow-is-incorrectly-recognized-as-secret-github-actions"
+    label: "SO#72536256 — Output incorrectly recognized as secret in reusable workflow (5,709 views)"
+  - url: "https://stackoverflow.com/questions/75061897/github-actions-incorrectly-thinks-variable-is-a-secret-and-so-does-not-set-outpu"
+    label: "SO#75061897 — Actions incorrectly thinks variable is a secret (2,780 views)"
+  - url: "https://docs.github.com/en/actions/sharing-automations/reusing-workflows#using-outputs-from-a-reusable-workflow"
+    label: "GitHub Docs: Using outputs from a reusable workflow"

package/errors/silent-failures/setup-node-silent-download-exit-zero.yml

@@ -0,0 +1,105 @@
+id: silent-failures-028
+title: "setup-node Silently Exits 0 Without Installing Node.js on Self-Hosted Runners"
+category: silent-failures
+severity: silent-failure
+tags:
+  - setup-node
+  - self-hosted
+  - download-failure
+  - silent-exit
+  - node-not-found
+patterns:
+  - regex: 'Attempting to download [0-9]+\.[0-9]+\.[0-9]+\.\.\.'
+    flags: "i"
+  - regex: "exec: node: not found"
+    flags: "i"
+  - regex: "node: not found"
+    flags: "i"
+error_messages:
+  - "Attempting to download 24.15.0..."
+  - "exec: node: not found"
+  - "node: not found"
+  - "/usr/bin/bash: node: not found"
+root_cause: |
+  On self-hosted runners (particularly those using `gha-runner-scale-set` or ephemeral
+  ARC runners), `actions/setup-node` can sporadically print
+  "Attempting to download <version>..." and then silently exit 0 without completing
+  the download or install.
+
+  The step outcome is `success` and the runner logs show no error — the action
+  simply returns without installing Node.js. Subsequent steps that invoke `node`,
+  `npm`, `pnpm`, or other Node-dependent tools then fail with "exec: node: not found"
+  or equivalent errors, which are far from the actual root cause.
+
+  This is a transient network or HTTP client failure in the `@actions/tool-cache`
+  download path. When the initial download attempt encounters a non-fatal HTTP error
+  (connection reset, early EOF, or interrupted read), the action sometimes swallows
+  the error and exits cleanly rather than retrying or calling `core.setFailed()`.
+  The issue is more common on self-hosted runners where network conditions are more
+  variable than on GitHub-hosted runners.
+
+  The action version affected is v6.x on self-hosted runners with `gha-runner-scale-set`
+  0.13.x and runner 2.334.x. Retrying the job almost always succeeds.
+fix: |
+  Add an explicit Node version verification step after setup-node to catch silent
+  failures before they cause confusing downstream errors:
+
+    - run: node --version
+
+  If this step fails, the issue is with setup-node — not the downstream tool.
+
+  For persistent failures, add a retry wrapper around setup-node, or use the
+  runner's pre-installed Node.js version as a fallback by pinning node-version
+  to the runner's system Node.
+
+  Long-term: upgrade to the latest setup-node patch release — several network
+  resilience improvements have been made to the download path. File an issue at
+  actions/setup-node with runner version, scale-set version, and the relevant
+  log section.
+fix_code:
+  - language: yaml
+    label: "Add immediate verification to catch silent download failure"
+    code: |
+      steps:
+        - uses: actions/checkout@v4
+        - uses: actions/setup-node@v6
+          with:
+            node-version-file: .nvmrc
+            cache: pnpm
+
+        # Catch silent exit-0 failures immediately
+        - name: Verify Node.js installed
+          run: |
+            node --version || (echo "::error::setup-node silently failed — Node.js not installed" && exit 1)
+            npm --version
+
+        - run: pnpm install --frozen-lockfile
+  - language: yaml
+    label: "Retry wrapper using nick-invision/retry"
+    code: |
+      steps:
+        - uses: actions/checkout@v4
+        - name: Setup Node.js with retry
+          uses: nick-invision/retry@v3
+          with:
+            timeout_minutes: 5
+            max_attempts: 3
+            command: |
+              # Re-run setup-node inline
+              echo "Attempt ${{ github.run_attempt }}"
+        - uses: actions/setup-node@v6
+          with:
+            node-version: 24
+prevention:
+  - "Always add a node --version step after setup-node on self-hosted runners to catch silent failures."
+  - "Use check-latest: true to ensure the action validates the installed version before proceeding."
+  - "Report sporadic failures with full runner version, scale-set version, and log output to actions/setup-node."
+  - "Consider using the runner's pre-cached Node.js version (omit node-version) to avoid downloads on self-hosted runners."
+  - "Monitor for setup-node step outcome === 'success' followed by downstream node-not-found — this pattern indicates silent download failure."
+docs:
+  - url: "https://github.com/actions/setup-node/issues/1555"
+    label: "actions/setup-node#1555: Sporadic silent failure when downloading Node.js (12 reactions)"
+  - url: "https://github.com/actions/download-artifact/issues/454"
+    label: "actions/download-artifact#454: Related silent download failure pattern"
+  - url: "https://github.com/actions/toolkit/tree/main/packages/tool-cache"
+    label: "actions/toolkit: tool-cache package (download internals)"

package/errors/silent-failures/setup-python-truncated-manifest-silent-exit.yml

@@ -0,0 +1,111 @@
+id: silent-failures-029
+title: "setup-python Silently Exits 0 Without Installing Python When versions-manifest.json Is Truncated"
+category: silent-failures
+severity: silent-failure
+tags:
+  - setup-python
+  - versions-manifest
+  - silent-exit
+  - truncated-response
+  - python-not-installed
+patterns:
+  - regex: "evaluating 0 versions"
+    flags: "i"
+  - regex: "Version .+ was not found in the local cache"
+    flags: "i"
+  - regex: "Node Action run completed with exit code 0"
+    flags: "i"
+error_messages:
+  - "evaluating 0 versions"
+  - "Version 3.11 - 3.13 was not found in the local cache"
+  - "Getting manifest from actions/python-versions@main"
+  - "##[debug]Node Action run completed with exit code 0"
+  - "##[debug]Finishing: Setup python"
+root_cause: |
+  `actions/setup-python` fetches `versions-manifest.json` from the
+  `actions/python-versions` repository via two GitHub API calls:
+
+  1. A git tree request to locate the blob URL.
+  2. A raw blob fetch with `Accept: application/vnd.github.VERSION.raw`.
+
+  Sporadically, the second call returns HTTP 200 with a **truncated body** — the
+  JSON is cut off mid-object and unparseable. The action catches the JSON parse
+  error silently, treats the result as an empty release list, logs
+  "evaluating 0 versions", and exits with code 0 **without installing Python**.
+
+  The truncated response has two consistent symptoms:
+  - A ~30-second server-side delay before any bytes arrive.
+  - Only affects authenticated requests (5,000 req/hour tier); anonymous requests
+    return the full manifest, but the 60 req/hour limit is too low for real CI.
+
+  After the step exits 0, subsequent steps that call `python`, `pip`, or `python3`
+  either use the system Python (which may differ in version) or fail with
+  "python: not found" — neither of which points back to the manifest fetch failure.
+fix: |
+  Add an explicit Python version check immediately after setup-python to catch the
+  silent exit before it causes confusing downstream errors:
+
+    - run: python --version
+
+  For a more robust workaround, set `python-version` to an exact version string
+  (e.g., "3.11.9") rather than a range — exact versions can fall back to the
+  runner's pre-cached toolcache without requiring a manifest fetch.
+
+  If you must use a version range, add a shell-level retry loop around the Python
+  invocation, or use the `setup-python` `check-latest: false` option with a pinned
+  version to reduce manifest fetches.
+
+  File the issue with captured truncated manifest bodies at actions/setup-python
+  to help maintainers add retry-with-backoff logic to the manifest fetch path.
+fix_code:
+  - language: yaml
+    label: "Catch silent exit immediately after setup-python"
+    code: |
+      steps:
+        - uses: actions/setup-python@v5
+          with:
+            python-version: "3.11 - 3.13"
+            cache: pip
+
+        # Catch silent manifest-fetch failure before downstream confusion
+        - name: Verify Python installed
+          run: |
+            python --version || (echo "::error::setup-python silently failed — Python not installed" && exit 1)
+            pip --version
+
+        - run: pip install -r requirements.txt
+  - language: yaml
+    label: "Use exact version to avoid manifest fetch entirely (uses toolcache)"
+    code: |
+      steps:
+        - uses: actions/setup-python@v5
+          with:
+            python-version: "3.11.9"   # exact version — uses pre-cached toolcache
+            cache: pip                  # no manifest fetch needed for exact match
+        - run: python --version
+        - run: pip install -r requirements.txt
+  - language: yaml
+    label: "Use .python-version file for explicit pinning"
+    code: |
+      # .python-version file: 3.12.7
+      steps:
+        - uses: actions/setup-python@v5
+          with:
+            python-version-file: .python-version  # exact pin, no manifest range fetch
+            cache: pip
+        - run: python --version
+prevention:
+  - "Always add a python --version verification step after setup-python to surface silent failures immediately."
+  - "Pin to an exact Python version (e.g., '3.11.9') rather than a range to use the pre-cached toolcache and avoid manifest fetches."
+  - "Use a .python-version file for reproducible, exact pinning that also works with pyenv locally."
+  - "Monitor for the symptom pattern: setup-python exits 0 + 'evaluating 0 versions' + downstream python-not-found."
+  - "If using version ranges, run setup-python with cache: false first in a debug context to isolate manifest vs. cache failures."
+docs:
+  - url: "https://github.com/actions/setup-python/issues/1318"
+    label: "actions/setup-python#1318: setup-python silently exits 0 on truncated versions-manifest.json"
+  - url: "https://github.com/actions/python-versions"
+    label: "actions/python-versions: Source of versions-manifest.json"
+  - url: "https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#specifying-a-python-version"
+    label: "GitHub Docs: Specifying a Python version"
+  - url: "https://github.com/actions/setup-python/blob/main/docs/advanced-usage.md"
+    label: "setup-python: Advanced Usage"

package/errors/silent-failures/undefined-env-expression-empty-string-silent.yml

@@ -0,0 +1,115 @@
+id: silent-failures-032
+title: "Undefined env/context Variable Silently Evaluates to Empty String"
+category: silent-failures
+severity: silent-failure
+tags:
+  - env-context
+  - expression
+  - undefined-variable
+  - empty-string
+  - silent-failure
+  - jenkins-migration
+patterns:
+  - regex: '\$\{\{\s*env\.[A-Za-z_][A-Za-z0-9_]*\s*\}\}'
+    flags: "i"
+  - regex: "expression.*evaluates.*empty.*string|undefined.*variable.*no.*error"
+    flags: "i"
+error_messages:
+  - "(no error shown -- undefined env/context variables produce empty strings silently)"
+  - "(step proceeds with empty value, downstream steps receive blank input)"
+root_cause: |
+  GitHub Actions expression evaluation does not throw errors when referencing
+  variables that do not exist. An expression like ${{ env.SOME_VAR }} where
+  SOME_VAR is not defined in any env: block evaluates silently to an empty string.
+
+  This behavior affects all expression contexts:
+  - ${{ env.VAR_NAME }} -- undefined env variable evaluates to empty string
+  - ${{ inputs.param }} -- undefined workflow input evaluates to empty string
+  - ${{ vars.CONFIG }} -- undefined repository variable evaluates to empty string
+  - ${{ needs.job.outputs.value }} -- missing job output evaluates to empty string
+
+  Common causes:
+  1. Jenkins migration: GitHub Actions Importer generates env references for all
+     Jenkins variables, but not all are defined in the converted workflow env block.
+  2. Variable renaming: renamed in one place but old reference still used elsewhere.
+  3. Conditional env blocks: variable only set for certain trigger events.
+  4. Copy-paste across repos where the env block differs.
+
+  Silent empty values cause cascading failures:
+  - Docker image tags resolve to empty, pushing to wrong registry path silently
+  - Build version strings empty, artifacts built without version identifier
+  - Path variables empty, steps act on current directory unexpectedly
+  - Conditional checks always false because gating variable is always empty
+  - Upload artifact path empty, upload succeeds with zero files
+fix: |
+  Add explicit variable validation using shell parameter expansion to fail fast
+  with a clear error message when required variables are empty or unset.
+
+  The POSIX ${VAR:?message} syntax causes the step to exit non-zero with a clear
+  error immediately when VAR is empty or unset.
+
+  For non-shell contexts, use the GitHub Actions || operator to provide fallback
+  values or error markers.
+fix_code:
+  - language: yaml
+    label: "Shell validation with POSIX parameter expansion -- fail fast on empty"
+    code: |
+      jobs:
+        deploy:
+          env:
+            DEPLOY_TARGET: ${{ env.DEPLOY_TARGET }}
+            IMAGE_TAG: ${{ env.IMAGE_TAG }}
+          steps:
+            - name: Validate required environment variables
+              shell: bash
+              run: |
+                : "${DEPLOY_TARGET:?DEPLOY_TARGET is required but not set}"
+                : "${IMAGE_TAG:?IMAGE_TAG is required -- check the env: block}"
+                echo "All required variables validated"
+            - name: Deploy
+              run: ./deploy.sh "$DEPLOY_TARGET" "$IMAGE_TAG"
+  - language: yaml
+    label: "Expression fallback to make undefined variables visible in logs"
+    code: |
+      steps:
+        - name: Resolve configuration
+          env:
+            DEPLOY_TARGET: ${{ env.DEPLOY_TARGET || 'MISSING_DEPLOY_TARGET' }}
+          run: |
+            if [[ "$DEPLOY_TARGET" == "MISSING_DEPLOY_TARGET" ]]; then
+              echo "::error::DEPLOY_TARGET is not set -- add it to the env: block"
+              exit 1
+            fi
+            echo "Deploying to: $DEPLOY_TARGET"
+  - language: yaml
+    label: "Bulk audit for Jenkins-migrated workflows"
+    code: |
+      steps:
+        - name: Audit required environment variables
+          shell: bash
+          run: |
+            REQUIRED=(APP_VERSION DEPLOY_ENV BUILD_TARGET REGISTRY_URL)
+            MISSING=()
+            for VAR in "${REQUIRED[@]}"; do
+              [[ -z "${!VAR}" ]] && MISSING+=("$VAR")
+            done
+            if [[ ${#MISSING[@]} -gt 0 ]]; then
+              echo "::error::Missing env vars: ${MISSING[*]} -- add them to env: block"
+              exit 1
+            fi
+            echo "All required variables are set"
+prevention:
+  - "After Jenkins migration, audit all env expression references against the workflow env: block."
+  - "Add a validation step at job start using shell parameter expansion for all required variables."
+  - "Use repository variables (vars.X) instead of env for shared config -- gaps are visible in UI."
+  - "Use the || operator to make undefined variables visible: ${{ env.X || 'MISSING' }}."
+  - "Set required: true on workflow_dispatch inputs to prevent the undefined-input variant."
+docs:
+  - url: "https://stackoverflow.com/questions/76611427/how-to-verify-if-the-github-syntax-variables-actually-exist-in-github-actions-wo"
+    label: "Stack Overflow: Verify GitHub syntax variables exist in workflow YAML"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/evaluate-expressions-in-workflows-and-actions"
+    label: "GitHub Docs: Evaluate expressions -- operators including || for defaults"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables"
+    label: "GitHub Docs: Store information in variables -- env, vars, inputs contexts"
+  - url: "https://pubs.opengroup.org/onlinepubs/009604499/utilities/xcu_chap02.html#tag_02_06_02"
+    label: "POSIX Shell: Parameter expansion with :? for unset/empty detection"

package/errors/silent-failures/windows-powershell-github-output-bash-syntax.yml

@@ -0,0 +1,118 @@
+id: silent-failures-034
+title: "Windows PowerShell GITHUB_OUTPUT and GITHUB_ENV Require $env: Prefix, Not Bash-Style $VARIABLE Syntax"
+category: silent-failures
+severity: silent-failure
+tags:
+  - windows
+  - powershell
+  - GITHUB_OUTPUT
+  - GITHUB_ENV
+  - environment-variables
+  - shell-syntax
+patterns:
+  - regex: "echo\\s+[\"']?[A-Z_]+=.*>>\\s+\\$GITHUB_OUTPUT"
+    flags: "i"
+  - regex: "echo\\s+[\"']?[A-Z_]+=.*>>\\s+\\$GITHUB_ENV"
+    flags: "i"
+  - regex: "shell:\\s*(pwsh|powershell)"
+    flags: "i"
+error_messages:
+  - "echo \"KEY=value\" >> $GITHUB_OUTPUT"
+  - "echo \"KEY=value\" >> $GITHUB_ENV"
+  - "Val1: "
+  - "Val2: "
+root_cause: |
+  When a workflow step uses shell: pwsh (PowerShell Core, the default on Windows
+  runners) or shell: powershell (legacy Windows PowerShell), the bash-style
+  variable syntax $GITHUB_OUTPUT and $GITHUB_ENV does NOT work.
+
+  In PowerShell, $GITHUB_OUTPUT is treated as a PowerShell variable (undefined
+  and therefore null). The >> append operator writes nothing to a null path.
+  The step exits 0 (success) with no error or warning. All downstream jobs
+  that reference step outputs or environment variables receive empty strings.
+
+  The correct PowerShell syntax uses $env:GITHUB_OUTPUT to access the OS
+  environment variable, not $GITHUB_OUTPUT (a PS variable).
+
+  Shell-specific syntax comparison:
+  - bash / sh:     echo "KEY=val" >> $GITHUB_OUTPUT
+  - pwsh (PS 7+):  "KEY=val" >> $env:GITHUB_OUTPUT
+  - powershell:    "KEY=val" | Out-File -FilePath $env:GITHUB_OUTPUT -Encoding utf8 -Append
+  - cmd:           echo KEY=val >> %GITHUB_OUTPUT%
+
+  This is a common mistake when:
+  - Migrating workflows from Linux to Windows runners
+  - Copying bash examples from documentation into PowerShell steps
+  - Writing cross-platform workflows without specifying shell: per step
+fix: |
+  Replace $GITHUB_OUTPUT with $env:GITHUB_OUTPUT and $GITHUB_ENV with
+  $env:GITHUB_ENV in all PowerShell steps.
+
+  Alternatively, add shell: bash to every run: step that uses bash-style
+  syntax — Git Bash is available on all Windows GitHub-hosted runners and
+  supports the standard $GITHUB_OUTPUT syntax.
+
+  For old Windows PowerShell (shell: powershell), use Out-File with
+  explicit UTF-8 encoding to avoid BOM issues.
+fix_code:
+  - language: yaml
+    label: "Broken — bash syntax in PowerShell step silently produces no output"
+    code: |
+      - name: Set output (broken on PowerShell)
+        shell: pwsh
+        run: |
+          # WRONG: $GITHUB_OUTPUT is a null PS variable — no output is set
+          echo "BUILD_VERSION=1.2.3" >> $GITHUB_OUTPUT
+
+  - language: yaml
+    label: "Fixed — correct $env: prefix for PowerShell Core (pwsh)"
+    code: |
+      - name: Set output (PowerShell Core)
+        id: version
+        shell: pwsh
+        run: |
+          # CORRECT: $env:GITHUB_OUTPUT accesses the OS environment variable
+          "BUILD_VERSION=1.2.3" >> $env:GITHUB_OUTPUT
+
+      - name: Use output
+        run: echo "Version is ${{ steps.version.outputs.BUILD_VERSION }}"
+        shell: pwsh
+
+  - language: yaml
+    label: "Old Windows PowerShell (shell: powershell) — explicit UTF-8 required"
+    code: |
+      - name: Set output (legacy Windows PowerShell)
+        shell: powershell
+        run: |
+          "BUILD_VERSION=1.2.3" | Out-File -FilePath $env:GITHUB_OUTPUT -Encoding utf8 -Append
+
+  - language: yaml
+    label: "Cross-platform — use shell: bash to keep bash-style syntax on Windows"
+    code: |
+      - name: Set output (bash on Windows runner)
+        shell: bash
+        run: |
+          # shell: bash uses Git Bash on Windows — $GITHUB_OUTPUT works fine
+          echo "BUILD_VERSION=1.2.3" >> $GITHUB_OUTPUT
+
+  - language: yaml
+    label: "CMD shell syntax"
+    code: |
+      - name: Set output (CMD)
+        shell: cmd
+        run: echo BUILD_VERSION=1.2.3 >> %GITHUB_OUTPUT%
+prevention:
+  - "Use shell: bash for all run: steps that use bash-style $GITHUB_OUTPUT or $GITHUB_ENV syntax, even on Windows runners."
+  - "In team workflow templates, document the shell-specific syntax for GITHUB_OUTPUT and GITHUB_ENV."
+  - "Add actionlint to CI — it can detect shell/syntax mismatches in workflow files."
+  - "Add an explicit post-step validation that reads back expected outputs to confirm they were written correctly."
+  - "Prefer shell: bash globally (via defaults: run: shell: bash) when your workflows target cross-platform and use bash syntax."
+docs:
+  - url: "https://stackoverflow.com/questions/74443940/value-not-set-using-github-output"
+    label: "Stack Overflow: Value not set using $GITHUB_OUTPUT on Windows PowerShell (Score: 22, 17K views)"
+  - url: "https://stackoverflow.com/questions/66733076/github-actions-set-environment-variable-for-windows-build-with-powershell"
+    label: "Stack Overflow: Set environment variable for Windows build with PowerShell (Score: 16, 11K views)"
+  - url: "https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#setting-an-output-parameter"
+    label: "GitHub Docs: Setting an output parameter (includes PowerShell examples)"
+  - url: "https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#defaultsrun"
+    label: "GitHub Docs: defaults.run.shell — set default shell for all run steps"