@htekdev/actions-debugger 1.0.14 → 1.0.15

package/errors/runner-environment/windows-latest-d-drive-removed.yml

@@ -0,0 +1,104 @@
+id: runner-environment-043
+title: "windows-latest Windows Server 2025 Runner Removed D: Drive — Paths Fail"
+category: runner-environment
+severity: error
+tags:
+  - windows
+  - runner-image
+  - d-drive
+  - path
+  - windows-server-2025
+  - breaking-change
+patterns:
+  - regex: "The system cannot find the path specified.*D:\\\\"
+    flags: "i"
+  - regex: "D:\\\\.*No such file or directory"
+    flags: "i"
+  - regex: "Path.*D:\\\\.*does not exist"
+    flags: "i"
+  - regex: "cannot find.*'D:\\\\|D:\\\\.*not found"
+    flags: "i"
+error_messages:
+  - "The system cannot find the path specified: 'D:\\a\\'"
+  - "D:\\a\\ : No such file or directory"
+  - "Cannot find path 'D:\\build' because it does not exist."
+  - "Error: ENOENT: no such file or directory, open 'D:\\tools\\...'"
+root_cause: |
+  The Windows Server 2025 runner image, which became the target of `windows-latest`
+  and `windows-2025` starting mid-2026, **removed the D: drive** that was present
+  on earlier Windows runner images (Windows Server 2019 and 2022).
+
+  On Windows Server 2019/2022 runners, the D: drive was a separate disk used for
+  temporary build storage and tools. Some workflows hardcoded paths like
+  `D:\a\`, `D:\tools\`, `D:\hostedtoolcache\`, or `D:\temp\` instead of using
+  environment variables like `${{ runner.tool_cache }}`, `$RUNNER_TOOL_CACHE`,
+  or workspace-relative paths.
+
+  On Windows Server 2025 runners, only the C: drive is available. Any workflow
+  step that writes to or reads from an absolute `D:\` path will immediately fail
+  with a path-not-found error, often as a confusing "system cannot find path" error
+  rather than a clear "D: drive missing" message.
+
+  Root issue thread: actions/runner-images#12416 (D: drive removal discussion)
+  and runner-images#12677 (windows-latest → Windows Server 2025 migration).
+fix: |
+  Replace all hardcoded `D:\` paths with environment variable references or
+  workspace-relative paths:
+
+  | Old (hardcoded D:) | New (portable)                          |
+  |--------------------|----------------------------------------|
+  | `D:\hostedtoolcache` | `${{ runner.tool_cache }}`          |
+  | `D:\a\${{ github.repository }}` | `${{ github.workspace }}`  |
+  | `D:\temp\`         | `${{ runner.temp }}`                   |
+  | `D:\tools\`        | Explicit installation to `C:\tools\`   |
+
+  For existing scripts that reference `D:\` directly, either:
+  1. Update all references to use RUNNER_TEMP, RUNNER_TOOL_CACHE, or GITHUB_WORKSPACE
+  2. Temporarily pin `runs-on: windows-2022` while you migrate
+fix_code:
+  - language: yaml
+    label: "Replace D:\\ paths with portable runner environment variables"
+    code: |
+      jobs:
+        build:
+          runs-on: windows-latest  # Works on Server 2025 (no D: drive)
+          steps:
+            - uses: actions/checkout@v4
+
+            # ❌ Broken: hardcoded D: path
+            # - run: Copy-Item -Path "D:\hostedtoolcache\node\20.0.0\x64\bin\node.exe" -Destination "${{ github.workspace }}"
+
+            # ✅ Fixed: use runner context variables
+            - name: Use portable paths
+              run: |
+                echo "Workspace: ${{ github.workspace }}"
+                echo "Tool cache: ${{ runner.tool_cache }}"
+                echo "Temp dir: ${{ runner.temp }}"
+                # C: drive is always available on all Windows runner images
+                $toolsDir = "C:\tools"
+                New-Item -ItemType Directory -Force -Path $toolsDir
+  - language: yaml
+    label: "Temporary rollback — pin to windows-2022 while migrating"
+    code: |
+      jobs:
+        build:
+          # Pin to windows-2022 (D: drive still present) while fixing hardcoded paths
+          runs-on: windows-2022
+          steps:
+            - uses: actions/checkout@v4
+            - run: msbuild MyProject.sln
+prevention:
+  - "Never hardcode `D:\\` paths in workflows or scripts — always use `${{ runner.tool_cache }}`, `${{ runner.temp }}`, `${{ github.workspace }}`, or `C:\\`-relative paths."
+  - "Audit workflows and called scripts for `D:\\` references before migrating to `windows-latest` (Windows Server 2025)."
+  - "Subscribe to actions/runner-images release announcements so runner image migrations do not catch you off-guard."
+  - "Use `windows-2022` as a temporary pin if immediate migration is not feasible; note that Server 2022 images have a defined EOL."
+  - "Test Windows workflows in a `windows-2025` matrix slot before the `windows-latest` migration window completes."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/12416"
+    label: "runner-images#12416 — D: drive removal discussion"
+  - url: "https://github.com/actions/runner-images/issues/12677"
+    label: "runner-images#12677 — windows-latest migration to Windows Server 2025"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables#default-environment-variables"
+    label: "GitHub Docs: Default environment variables (runner.tool_cache, runner.temp)"
+  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners#standard-github-hosted-runners-for-public-repositories"
+    label: "About GitHub-hosted runners — Windows Server 2025 specs"

package/errors/runner-environment/windows-vs2026-cuda-host-compiler-unsupported.yml

@@ -0,0 +1,145 @@
+id: runner-environment-046
+title: "CUDA nvcc Rejects Visual Studio 2026 Host Compiler on windows-latest"
+category: runner-environment
+severity: error
+tags:
+  - windows
+  - windows-latest
+  - cuda
+  - nvcc
+  - visual-studio-2026
+  - vs2026
+  - runner-image
+  - breaking-change
+  - gpu
+patterns:
+  - regex: "unsupported Microsoft Visual Studio version.*Only the versions between 2019 and 2022"
+    flags: "i"
+  - regex: "fatal error C1189.*unsupported Microsoft Visual Studio version"
+    flags: "i"
+  - regex: "nvcc.*error.*host_config\\.h.*C1189"
+    flags: "i"
+  - regex: "CUDA.*requires Visual Studio.*2022|nvcc.*does not support.*Visual Studio 18"
+    flags: "i"
+  - regex: "error:\\s+--\\s+unsupported Microsoft Visual Studio version"
+    flags: "i"
+error_messages:
+  - "fatal error C1189: #error:  -- unsupported Microsoft Visual Studio version! Only the versions between 2019 and 2022 (inclusive) are supported!"
+  - "Error in C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\v13.1\\include\\crt/host_config.h(164)"
+  - "nvcc fatal   : Host compiler targets unsupported OS."
+  - "nvcc error  : Failed to preprocess the host compiler properties."
+root_cause: |
+  GitHub Actions migrated `windows-latest` (and `windows-2025`) from Visual Studio 2022 to
+  Visual Studio 2026 (version 18.x) beginning June 8, 2026, completing by June 15, 2026.
+  Additionally, some users saw the switch as early as May 5, 2026 when `windows-2025`
+  started serving the `windows-2025-vs2026` image label prematurely (runner-images#14004).
+
+  CUDA toolkits up to and including CUDA 13.x hard-code supported Visual Studio version
+  ranges inside `<CUDA_ROOT>/include/crt/host_config.h`. The file checks the `_MSC_VER`
+  compiler macro and rejects any version outside the explicitly listed range. Visual Studio
+  2022 (MSVC 19.3x) is the last version supported by all CUDA releases through CUDA 13.x.
+  Visual Studio 2026 (MSVC 19.4x / VS version 18.x) falls outside these ranges and triggers
+  an immediate hard compiler error:
+
+    fatal error C1189: #error:  -- unsupported Microsoft Visual Studio version! Only the
+    versions between 2019 and 2022 (inclusive) are supported! The nvcc flag
+    '-allow-unsupported-compiler' can be used to override this version check; however,
+    using an unsupported host compiler may cause compilation failure or incorrect run time
+    execution. Use at your own risk.
+
+  The error fires at the preprocessing stage — before any CUDA code is compiled — so it
+  affects any project that invokes `nvcc`, regardless of the CUDA source code content.
+
+  Source: actions/runner-images#14017, runner-images#14004, NVIDIA CUDA Installation Guide
+fix: |
+  **Option 1 — Use `-allow-unsupported-compiler` flag** (quick unblock, use at own risk):
+  Adds a flag to nvcc that bypasses the version check. Works for many projects but NVIDIA
+  does not guarantee correctness with unsupported compilers.
+
+  **Option 2 — Pin to windows-2022** (safest immediate fix):
+  `windows-2022` still ships Visual Studio 2022. It is not yet deprecated.
+
+  **Option 3 — Upgrade to a CUDA version that supports VS 2026** (best long-term):
+  NVIDIA releases new CUDA toolkits that list VS 2026 in their supported compiler matrix.
+  Check the CUDA Toolkit Release Notes for the current supported VS version table.
+
+  **Option 4 — Use CMake's `CUDAARCHS` + VS2022 generator explicitly**:
+  If using CMake, pin the generator to `Visual Studio 17 2022` even on windows-latest by
+  specifying `-G "Visual Studio 17 2022"` in your cmake configure step. This forces CMake
+  to use the VS 2022 tools even if VS 2026 is the default.
+fix_code:
+  - language: yaml
+    label: "Pin to windows-2022 to avoid VS 2026 entirely"
+    code: |
+      jobs:
+        build-cuda:
+          runs-on: windows-2022   # VS 2022 — supported by CUDA up to 13.x
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Build with CUDA
+              run: cmake --build . --config Release
+  - language: yaml
+    label: "Pass -allow-unsupported-compiler to nvcc (quick unblock)"
+    code: |
+      jobs:
+        build-cuda:
+          runs-on: windows-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            # Pass flag via CMake CUDA_NVCC_FLAGS
+            - name: Configure CMake
+              run: |
+                cmake -B build -DCMAKE_CUDA_FLAGS="-allow-unsupported-compiler"
+
+            - name: Build
+              run: cmake --build build --config Release
+  - language: yaml
+    label: "Force VS 2022 CMake generator on windows-latest (VS 2026 image)"
+    code: |
+      jobs:
+        build-cuda:
+          runs-on: windows-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            # Explicitly select VS 2022 generator even when VS 2026 is default
+            - name: Configure with VS 2022 generator
+              run: |
+                cmake -B build `
+                  -G "Visual Studio 17 2022" `
+                  -A x64
+
+            - name: Build
+              run: cmake --build build --config Release
+  - language: yaml
+    label: "Upgrade CUDA toolkit version that supports VS 2026"
+    code: |
+      jobs:
+        build-cuda:
+          runs-on: windows-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            # Install a CUDA version that explicitly supports VS 2026
+            # (check NVIDIA release notes for the current minimum supported version)
+            - name: Install CUDA Toolkit
+              uses: Jimver/cuda-toolkit@v0.2.21
+              with:
+                cuda: '12.8.0'   # Check if this version lists VS 2026 in its support matrix
+
+            - name: Build
+              run: cmake --build build --config Release
+prevention:
+  - "Never assume CUDA is forward-compatible with new Visual Studio versions — CUDA hard-codes supported MSVC version ranges."
+  - "Pin `runs-on: windows-2022` for CUDA workflows until the CUDA version you use explicitly lists VS 2026 as supported."
+  - "Subscribe to runner-images#14017 and similar announcements before the windows-latest label migration date."
+  - "Check the CUDA Toolkit Release Notes for your version's supported host compiler table before upgrading either Visual Studio or CUDA."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/14017"
+    label: "runner-images#14017: windows-latest will use VS 2026 image in June 2026"
+  - url: "https://github.com/actions/runner-images/issues/14004"
+    label: "runner-images#14004: windows-2025 serving VS 2026 image prematurely (May 2026)"
+  - url: "https://docs.nvidia.com/cuda/cuda-installation-guide-microsoft-windows/"
+    label: "NVIDIA CUDA Installation Guide — supported Visual Studio versions"

package/errors/silent-failures/event-commits-empty-on-workflow-dispatch.yml

@@ -0,0 +1,110 @@
+id: silent-failures-018
+title: "github.event.commits and github.event.head_commit Are Null/Empty on Non-Push Triggers"
+category: silent-failures
+severity: silent-failure
+tags:
+  - github-context
+  - workflow-dispatch
+  - schedule
+  - commits
+  - null-access
+  - push-event
+  - expression
+patterns:
+  - regex: "github\\.event\\.commits\\[0\\]"
+    flags: "i"
+  - regex: "github\\.event\\.head_commit\\.(message|id|author)"
+    flags: "i"
+  - regex: "github\\.event\\.commits is not iterable|Cannot read.*commits"
+    flags: "i"
+error_messages:
+  - "Error: Cannot read properties of undefined (reading 'message')"
+  - "Error: github.event.commits[0] is undefined"
+root_cause: |
+  The `github.event.commits` array and `github.event.head_commit` object are ONLY populated
+  for `push` webhook events. They are absent (null / empty array) for all other trigger types:
+
+  - `workflow_dispatch` — manual UI or API trigger, no commit context
+  - `schedule` — cron-triggered run, no specific push associated
+  - `pull_request` / `pull_request_target` — uses github.event.pull_request instead
+  - `workflow_call` — reusable workflow invocation, no commit array
+  - `repository_dispatch` — uses github.event.client_payload, no commits key
+  - `release` — uses github.event.release, no commits array
+
+  When a workflow is triggered on both `push` and `workflow_dispatch` (a common pattern),
+  expressions like:
+    ${{ github.event.commits[0].message }}
+    ${{ github.event.head_commit.id }}
+
+  silently evaluate to empty string ('') on non-push triggers rather than raising an error.
+  GitHub Actions treats missing context properties as empty string, so the step runs but
+  with blank or wrong data — the workflow shows green while producing incorrect output.
+
+  This is a silent failure because there is no error in the logs when the empty string is
+  used in a step (e.g., an echo, a tag, a release title). The problem only becomes visible
+  when the downstream artifact or message is inspected.
+fix: |
+  Use git directly to extract commit information — it works reliably across all trigger types
+  (as long as fetch-depth is not 1 / uses default full clone or depth >= 2):
+
+    git log --format=%s -1      # subject line
+    git log --format=%H -1      # full SHA
+    git log --format=%ae -1     # author email
+
+  Alternatively, guard commit-context access with an event_name check, or use the
+  github.sha context (which IS available on all triggers) when a commit SHA is needed.
+fix_code:
+  - language: yaml
+    label: "Portable commit message extraction via git (works on all triggers)"
+    code: |
+      jobs:
+        release:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                fetch-depth: 2  # depth >= 2 required for git log on non-push
+
+            - name: Get commit message (safe for push, workflow_dispatch, schedule)
+              id: meta
+              run: |
+                echo "sha=${{ github.sha }}" >> $GITHUB_OUTPUT
+                echo "message=$(git log --format=%s -1 ${{ github.sha }})" >> $GITHUB_OUTPUT
+                echo "author=$(git log --format=%ae -1 ${{ github.sha }})" >> $GITHUB_OUTPUT
+
+            - name: Use commit metadata
+              run: |
+                echo "SHA: ${{ steps.meta.outputs.sha }}"
+                echo "Message: ${{ steps.meta.outputs.message }}"
+  - language: yaml
+    label: "Guard push-only context with event_name check"
+    code: |
+      - name: Get commit message (push only)
+        if: github.event_name == 'push' && github.event.commits[0] != null
+        run: |
+          echo "COMMIT_MSG=${{ github.event.commits[0].message }}" >> $GITHUB_ENV
+
+      - name: Fallback for non-push triggers
+        if: github.event_name != 'push'
+        run: |
+          echo "COMMIT_MSG=$(git log --format=%s -1)" >> $GITHUB_ENV
+  - language: yaml
+    label: "Debug: dump full event payload to understand what is available"
+    code: |
+      - name: Debug — dump event context
+        run: echo '${{ toJSON(github.event) }}'
+prevention:
+  - "Never access github.event.commits or github.event.head_commit without first checking github.event_name == 'push'."
+  - "Use `git log --format=%s -1 ${{ github.sha }}` for commit message extraction — it works on all trigger types."
+  - "Note that github.sha IS available on all triggers and points to the relevant commit; use it as a portable substitute for github.event.head_commit.id."
+  - "Add a debug step early in development to dump `${{ toJSON(github.event) }}` so you can see exactly what context is available for each trigger type."
+  - "Test workflows by triggering them manually via workflow_dispatch to catch push-only context assumptions before they hit production."
+docs:
+  - url: "https://docs.github.com/en/webhooks/webhook-events-and-payloads#push"
+    label: "GitHub docs — push event payload (includes commits array)"
+  - url: "https://docs.github.com/en/webhooks/webhook-events-and-payloads#workflow_dispatch"
+    label: "GitHub docs — workflow_dispatch event payload (no commits array)"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/accessing-contextual-information-about-workflow-runs#github-context"
+    label: "GitHub docs — github context reference"
+  - url: "https://github.com/orgs/community/discussions/27058"
+    label: "Community discussion — github.event.commits undefined on workflow_dispatch"

package/errors/silent-failures/fetch-tags-depth-one-silent-no-op.yml

@@ -0,0 +1,77 @@
+id: silent-failures-022
+title: "fetch-tags: true Silently Fetches No Tags When fetch-depth Is 1"
+category: silent-failures
+severity: silent-failure
+tags:
+  - checkout
+  - fetch-tags
+  - shallow-clone
+  - fetch-depth
+  - git-tags
+  - versioning
+patterns:
+  - regex: "No tags found|no tags found"
+    flags: "i"
+  - regex: "fatal: No names found, cannot describe anything"
+    flags: "i"
+  - regex: "CHANGELOG.*No tag found"
+    flags: "i"
+error_messages:
+  - "fatal: No names found, cannot describe anything"
+  - "No tags found. Try unshallowing the repository"
+  - "CHANGELOG ERROR: No tag found on HEAD"
+  - "Error: No tags matching '*' found, exiting"
+root_cause: |
+  The `fetch-tags: true` option in `actions/checkout` was introduced in v3.6.0 to restore tag
+  fetching after `--no-tags` was made the default for shallow clones. However, when `fetch-depth`
+  remains at its default value of `1` (shallow clone), the tag fetch silently produces no results.
+
+  With a shallow clone, git only downloads a single commit. Tags are only present if they point
+  directly to that one commit — i.e., the workflow was triggered by a tag push. In all other
+  cases, `fetch-tags: true` appears to succeed (no error, no warning) but `git tag -l` returns
+  empty results.
+
+  This silently breaks tools that depend on git tags for versioning: semantic-release,
+  commitizen, standard-version, cargo-smart-release, setuptools-scm, and any script using
+  `git describe --tags`. Builds succeed but produce wrong version numbers (often 0.0.0 or
+  commit-hash-only versions).
+fix: |
+  Pair `fetch-tags: true` with `fetch-depth: 0` to fetch the full history including all tags.
+  On very large repositories, use `filter: tree:0` for a blobless partial clone that still
+  includes complete tag history. As a targeted workaround, add a second step to fetch only
+  tags after a shallow checkout.
+fix_code:
+  - language: yaml
+    label: "Recommended: full history with all tags"
+    code: |
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0     # full history required for tags
+          fetch-tags: true   # fetch all tags
+  - language: yaml
+    label: "Large repos: blobless filter (faster, still includes tags)"
+    code: |
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          filter: tree:0     # blobless clone — avoids downloading file blobs
+          fetch-tags: true
+  - language: yaml
+    label: "Workaround: shallow checkout + separate tag fetch step"
+    code: |
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+      - name: Fetch all tags
+        run: git fetch --prune --unshallow --tags
+prevention:
+  - "Always pair `fetch-tags: true` with `fetch-depth: 0` unless the workflow is only triggered by tag pushes"
+  - "Add `git tag -l` as a debug step in release workflows to verify tags are present after checkout"
+  - "If using semantic-release or similar, test your version script locally with a shallow clone to catch this early"
+docs:
+  - url: "https://github.com/actions/checkout/issues/1471"
+    label: "actions/checkout#1471 — fetch-tags: true doesn't actually fetch any tags (126 reactions)"
+  - url: "https://github.com/actions/checkout/issues/1467"
+    label: "actions/checkout#1467 — related: no-tags default behavior"
+  - url: "https://github.com/actions/checkout#usage"
+    label: "actions/checkout — fetch-tags and fetch-depth inputs documentation"

package/errors/silent-failures/github-env-multiline-value-truncated.yml

@@ -0,0 +1,127 @@
+id: silent-failures-019
+title: "GITHUB_ENV Multiline Values Silently Truncate Without Heredoc Delimiter Format"
+category: silent-failures
+severity: silent-failure
+tags:
+  - GITHUB_ENV
+  - environment-variable
+  - multiline
+  - heredoc
+  - truncation
+  - env-file
+patterns:
+  - regex: "GITHUB_ENV.*multiline|multiline.*GITHUB_ENV"
+    flags: "i"
+  - regex: "Invalid format '.*\\n'"
+    flags: "i"
+  - regex: "Error: Failed to parse environment file"
+    flags: "i"
+error_messages:
+  - "Error: Failed to parse environment file"
+  - "Invalid format 'MY_VAR=line1\nline2'"
+  - "Warning: Environment file exporting failed"
+root_cause: |
+  When setting an environment variable with `$GITHUB_ENV` that contains **newline
+  characters**, naïvely echoing the value produces an invalid environment file entry
+  that is silently truncated or causes a parse error.
+
+  The environment file format used by GitHub Actions expects single-line `KEY=VALUE`
+  entries. If a value contains a literal newline, the runner cannot parse it and
+  typically:
+  - Silently truncates the value at the first newline (the variable gets only the
+    first line)
+  - In strict runner versions: fails with "Error: Failed to parse environment file"
+
+  **Common incorrect pattern:**
+  ```yaml
+  run: echo "MY_CERT=${{ secrets.CERT }}" >> $GITHUB_ENV
+  # If CERT contains newlines, the env file entry is broken
+  ```
+
+  **Why it's a silent failure:**
+  - The step succeeds with exit code 0
+  - No obvious error message appears in the logs
+  - Downstream steps see a truncated, incomplete variable value
+  - Certificate/JSON/SSH key values are commonly multi-line and hit this silently
+
+  This is separate from the `$GITHUB_OUTPUT` multiline issue (which uses the same
+  heredoc syntax fix) — the root cause and pattern are identical but the environment
+  file (`GITHUB_ENV`) is a distinct file from the output file (`GITHUB_OUTPUT`).
+
+  Sources: GitHub Community #160171, GitHub Docs workflow commands
+fix: |
+  Use the **heredoc delimiter format** for multiline values in `$GITHUB_ENV`:
+
+  ```
+  KEY<<DELIMITER
+  value-line-1
+  value-line-2
+  DELIMITER
+  ```
+
+  The delimiter can be any string that does not appear in the value. `EOF` is the
+  conventional choice. The delimiter must appear on its own line both as the opening
+  marker and the closing marker.
+
+  This same pattern applies to `$GITHUB_OUTPUT` for multiline step outputs.
+fix_code:
+  - language: yaml
+    label: "Broken — newline in value breaks the env file silently"
+    code: |
+      # ❌ BROKEN: Secret or cert value with newlines truncates silently
+      - name: Set multiline env var
+        run: echo "MY_CERT=${{ secrets.TLS_CERT }}" >> $GITHUB_ENV
+        # Result: MY_CERT contains only the first line of the certificate
+  - language: yaml
+    label: "Fixed — heredoc delimiter format for multiline GITHUB_ENV values"
+    code: |
+      # ✅ FIXED: Use heredoc delimiter syntax
+      - name: Set multiline env var
+        run: |
+          echo "MY_CERT<<EOF" >> $GITHUB_ENV
+          echo "${{ secrets.TLS_CERT }}" >> $GITHUB_ENV
+          echo "EOF" >> $GITHUB_ENV
+  - language: yaml
+    label: "Fixed — multiline JSON body in GITHUB_ENV"
+    code: |
+      # ✅ FIXED: Multi-line JSON stored as env var using heredoc format
+      - name: Set JSON config variable
+        run: |
+          echo "APP_CONFIG<<EOF" >> $GITHUB_ENV
+          cat config/settings.json >> $GITHUB_ENV
+          echo "EOF" >> $GITHUB_ENV
+  - language: yaml
+    label: "Fixed — same pattern applies to GITHUB_OUTPUT for multiline outputs"
+    code: |
+      # ✅ SAME PATTERN for step outputs (GITHUB_OUTPUT)
+      - name: Set multiline output
+        id: generate
+        run: |
+          echo "report<<EOF" >> $GITHUB_OUTPUT
+          cat test-results.txt >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
+  - language: yaml
+    label: "Fixed — PowerShell equivalent for Windows runners"
+    code: |
+      # ✅ FIXED (Windows/PowerShell): Use Out-File -Append with heredoc-style writes
+      - name: Set multiline env var on Windows
+        shell: pwsh
+        run: |
+          @"
+          MY_CERT<<EOF
+          ${{ secrets.TLS_CERT }}
+          EOF
+          "@ | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
+prevention:
+  - "Always use the `KEY<<DELIMITER ... DELIMITER` heredoc format for any env var value that may contain newlines (certs, JWTs, JSON, SSH keys)."
+  - "Never use a single `echo KEY=VALUE >> $GITHUB_ENV` for values sourced from secrets or file contents — they are likely to contain newlines."
+  - "The same heredoc pattern applies to `$GITHUB_OUTPUT` — treat them identically for multiline values."
+  - "Validate that downstream steps receive the full value: `run: echo \"MY_CERT=$MY_CERT\"` — a truncated cert will be obviously short."
+  - "Use `echo 'key<<EOF' >> $GITHUB_ENV` (single quotes around key<<EOF) to avoid accidental shell expansion of the delimiter line."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#multiline-strings"
+    label: "GitHub Docs: Workflow commands — Multiline strings in environment files"
+  - url: "https://github.com/orgs/community/discussions/160171"
+    label: "GitHub Community #160171 — GITHUB_ENV multiline values"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#setting-an-environment-variable"
+    label: "GitHub Docs: Setting an environment variable (GITHUB_ENV format)"