@htekdev/actions-debugger 1.0.113 → 1.0.114

package/errors/caching-artifacts/cache-corrupt-on-cancel-during-restore-save-always.yml

@@ -0,0 +1,136 @@
+id: caching-artifacts-067
+title: "Cache corrupted when workflow canceled mid-restore and save runs via always()"
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - cache
+  - cancellation
+  - corrupt
+  - restore
+  - always
+  - windows
+  - tar
+patterns:
+  - regex: 'The operation was canceled'
+    flags: 'i'
+  - regex: 'internal error.*InstallPlan.*not in configured state'
+    flags: 'i'
+  - regex: 'Cache restored successfully'
+    flags: 'i'
+  - regex: 'Cache hit for:.*\nReceived.*\nError: The operation was canceled'
+    flags: 'is'
+error_messages:
+  - "Error: The operation was canceled."
+  - "Cache restored successfully"
+  - "internal error in InstallPlan.completed: not in configured state: Installed"
+root_cause: |
+  When a workflow is canceled while `actions/cache/restore` is mid-way through
+  extracting the cache archive (via `tar`), the extraction is interrupted and the
+  working directory is left in a **partially extracted, corrupt state**. The cache
+  hit was registered before extraction began, so the action considers the key
+  matched.
+
+  If a separate `actions/cache/save` step runs with `if: always()` (or the job has
+  `save-state` / explicit save at the end), it executes despite the cancellation.
+  It then compresses and saves the **partial working directory** — including the
+  incomplete files from the aborted tar extraction — under the exact same cache
+  key.
+
+  On subsequent workflow runs:
+  1. `actions/cache/restore` finds the key (exact match), downloads and extracts
+     the archive successfully ("Cache restored successfully").
+  2. The build starts with corrupt or incomplete files from the previous partial
+     extraction and fails with cryptic internal errors, not a caching error.
+
+  The symptom is particularly confusing because the restore step looks perfectly
+  healthy: it shows 100% download progress and "Cache restored successfully", but
+  the build then fails with errors like "not in configured state: Installed" (Cabal
+  Haskell), "invalid content", "module not found" (npm), or similar tool-specific
+  corruption errors.
+
+  This is distinct from `caching-artifacts-007` (cache post-step skipped on cancel
+  — where the cache is NOT saved). This entry covers the opposite scenario: an
+  explicit `always()` save step actively commits a corrupt partial state, poisoning
+  the cache for all future runs until the key expires or is manually deleted.
+fix: |
+  1. **Delete the corrupt cache entry** via the GitHub Actions UI (Settings →
+     Actions → Caches) or the GitHub API:
+       `DELETE /repos/{owner}/{repo}/actions/caches/{cache_id}`
+
+  2. **Guard the save step** so it only runs when restoration AND the build
+     succeeded — not unconditionally:
+
+     ```yaml
+     - name: Save cache
+       uses: actions/cache/save@v4
+       if: success() && steps.restore.outputs.cache-hit != 'true'
+       with:
+         path: ...
+         key: ...
+     ```
+
+  3. **Avoid pairing `always()` with cache save** when the prior restore step
+     may have been interrupted. Use explicit `success()` or a combination
+     `if: success() || steps.restore.conclusion == 'success'`.
+
+  4. On Windows, consider using `actions/cache@v4` with `enableCrossOsArchive: false`
+     and switching to `zstd`-backed archives, which are more resilient to partial
+     extraction (partial frames are detectable by zstd checksums).
+fix_code:
+  - language: yaml
+    label: "WRONG — always() save can commit partial corrupt state after cancellation"
+    code: |
+      - name: Restore cache
+        id: restore
+        uses: actions/cache/restore@v4
+        with:
+          path: ~/.cabal/store
+          key: cabal-${{ runner.os }}-${{ hashFiles('cabal.project.freeze') }}
+
+      # ... build steps ...
+
+      - name: Save cache
+        uses: actions/cache/save@v4
+        if: always()          # ← PROBLEM: runs even if restore was interrupted
+        with:
+          path: ~/.cabal/store
+          key: cabal-${{ runner.os }}-${{ hashFiles('cabal.project.freeze') }}
+  - language: yaml
+    label: "CORRECT — only save when restore and build succeeded"
+    code: |
+      - name: Restore cache
+        id: restore
+        uses: actions/cache/restore@v4
+        with:
+          path: ~/.cabal/store
+          key: cabal-${{ runner.os }}-${{ hashFiles('cabal.project.freeze') }}
+          restore-keys: |
+            cabal-${{ runner.os }}-
+
+      # ... build steps ...
+
+      - name: Save cache
+        uses: actions/cache/save@v4
+        if: success()          # ← SAFE: only runs on clean job success
+        with:
+          path: ~/.cabal/store
+          key: cabal-${{ runner.os }}-${{ hashFiles('cabal.project.freeze') }}
+prevention:
+  - "Never use `if: always()` on a `cache/save` step — use `if: success()` or
+    an explicit condition that confirms the build completed cleanly."
+  - "After any job cancellation that hit a cache restore step, check the GitHub
+    Actions Caches list and delete the affected cache key to prevent future runs
+    from inheriting the corrupt state."
+  - "Use `actions/cache@v4` in the combined save-on-miss pattern with the default
+    post-job hook only (no explicit save step); the post-job hook is automatically
+    skipped on cancellation, avoiding the corrupt save."
+  - "Consider setting a short TTL on Windows caches or using unique keys per run
+    (`key: ...-${{ github.run_id }}`) for artifacts that are sensitive to partial
+    extraction."
+docs:
+  - url: "https://github.com/actions/cache/issues/1729"
+    label: "actions/cache#1729: If a workflow is canceled during cache/restore then cache/save writes a corrupt cache (Windows)"
+  - url: "https://github.com/actions/toolkit/tree/main/packages/cache"
+    label: "@actions/cache package documentation"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows"
+    label: "Caching dependencies to speed up workflows"

package/errors/caching-artifacts/restore-keys-asterisk-literal-not-glob.yml

@@ -0,0 +1,107 @@
+id: caching-artifacts-066
+title: 'restore-keys patterns are literal prefix strings — asterisk is not a glob wildcard'
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - cache
+  - actions/cache
+  - restore-keys
+  - prefix
+  - cache-miss
+  - glob
+patterns:
+  - regex: 'restore-keys:.*\*'
+    flags: 'i'
+  - regex: 'Cache not found for input keys:'
+    flags: 'i'
+  - regex: 'No cache found for key'
+    flags: 'i'
+error_messages:
+  - 'Cache not found for input keys:'
+  - 'No cache found for key'
+  - '(silent cache miss — no error, restore-keys with asterisk simply fails to match any existing cache entry)'
+root_cause: |
+  GitHub Actions cache restore-keys are prefix strings, not glob patterns. The
+  asterisk (*) character has no special meaning — it is treated as a literal
+  character in the prefix match.
+
+  A restore-keys entry of:
+    restore-keys: npm-${{ runner.os }}-*
+
+  does NOT match cache keys like:
+    npm-Ubuntu-abc123hash
+    npm-Ubuntu-lockfile-abcdef
+
+  It only matches keys whose name starts with the literal string
+  "npm-Ubuntu-*" (including the asterisk), which virtually never exist,
+  resulting in a silent cache miss with no error message.
+
+  This mistake is widespread because:
+  1. The actions/cache documentation uses the term "prefix" but does not
+     explicitly state that glob characters are unsupported or treated literally.
+  2. Many other caching tools (Gradle, Maven, Buildkite, CircleCI) accept glob
+     or wildcard patterns in cache key configurations, leading developers to
+     apply the same syntax to GitHub Actions.
+  3. The failure mode is silent — the step reports "Cache not found for input keys"
+     and continues normally. Without inspecting the exact key string printed in the
+     step log, the asterisk in the pattern is invisible as the cause.
+
+  The correct behavior: restore-keys prefix matching finds any cache entry whose
+  key BEGINS WITH the given string. Trailing a prefix with a dash or separator
+  (e.g., npm-Ubuntu-) is all that is needed to match any entry starting with
+  that prefix — no asterisk required or supported.
+fix: |
+  Remove any glob characters from restore-keys entries. A bare prefix string
+  ending in a dash or other separator correctly matches all cache entries whose
+  key starts with that prefix:
+
+    restore-keys: |
+      npm-${{ runner.os }}-      ← correct: prefix without asterisk
+
+  The cache service automatically returns the most recently saved matching entry,
+  so multiple ordered restore-keys fallback entries can be stacked from most
+  specific to broadest.
+fix_code:
+  - language: yaml
+    label: 'Broken: asterisk treated as literal — no cached keys match this pattern'
+    code: |
+      - uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          key: npm-${{ runner.os }}-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: |
+            npm-${{ runner.os }}-*
+  - language: yaml
+    label: 'Fixed: bare prefix (no asterisk) correctly matches all prior cache entries'
+    code: |
+      - uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          key: npm-${{ runner.os }}-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: |
+            npm-${{ runner.os }}-
+  - language: yaml
+    label: 'Multiple fallback tiers from most specific to broadest (no globs needed)'
+    code: |
+      - uses: actions/cache@v4
+        with:
+          path: |
+            ~/.npm
+            ~/.cache/Cypress
+          key: node-${{ runner.os }}-${{ matrix.node-version }}-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: |
+            node-${{ runner.os }}-${{ matrix.node-version }}-
+            node-${{ runner.os }}-
+            node-
+prevention:
+  - 'Never use glob characters (*, ?, []) in restore-keys — they are literal string characters; the cache key service does not interpret them as wildcards'
+  - 'End restore-keys prefix entries with a trailing dash or separator: restore-keys: npm-${{ runner.os }}- not npm-${{ runner.os }}-*'
+  - 'If cache misses persist despite restore-keys being configured, add a debug step that echoes the exact key and restore-keys strings being evaluated (using set -x or explicit echo) to spot literal asterisks in the output'
+  - 'Do not confuse restore-keys with glob support in path: — the path: field DOES support glob patterns; restore-keys does not'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows#matching-a-cache-key'
+    label: 'GitHub Docs: Matching a cache key'
+  - url: 'https://github.com/actions/cache#inputs'
+    label: 'actions/cache README: Inputs — restore-keys'
+  - url: 'https://github.com/actions/cache/blob/main/tips-and-workarounds.md'
+    label: 'actions/cache: Tips and workarounds'

package/errors/concurrency-timing/pull-request-review-shared-concurrency-cancels-ci.yml

@@ -0,0 +1,131 @@
+id: concurrency-timing-052
+title: 'pull_request_review event in shared concurrency group cancels in-progress CI on reviewer submission'
+category: concurrency-timing
+severity: silent-failure
+tags:
+  - concurrency
+  - pull_request_review
+  - pull_request
+  - cancel-in-progress
+  - code-review
+  - ci-cancellation
+patterns:
+  - regex: 'pull_request_review'
+    flags: 'i'
+  - regex: 'Canceling since a higher priority waiting run was found'
+    flags: 'i'
+  - regex: 'This run was automatically cancelled'
+    flags: 'i'
+error_messages:
+  - 'This run was automatically cancelled'
+  - 'Canceling since a higher priority waiting run was found'
+root_cause: |
+  When a workflow responds to both on.pull_request and on.pull_request_review, and
+  uses a concurrency group keyed on github.event.pull_request.number, both event
+  types resolve to the same concurrency group key for a given PR.
+
+  Unlike push events where github.event.pull_request is absent, the
+  pull_request_review event payload DOES include a pull_request object with a number
+  property — so github.event.pull_request.number evaluates identically for both
+  pull_request [synchronize] and pull_request_review [submitted] events on the same PR.
+
+  As a result, every reviewer action — approvals, review comments, change requests,
+  and re-requests — triggers a new workflow run that shares the same concurrency slot
+  as the CI run from the last code push. With cancel-in-progress: true, a reviewer
+  merely submitting an approval silently cancels the running CI checks for that PR,
+  causing the PR to show pending or missing status checks despite no new commit being
+  pushed.
+
+  This catches teams off-guard because the reviewer action is unrelated to the code
+  under test — no new commit arrived — yet the running CI is terminated. The PR
+  may be left with required checks in a "Pending" state even though nothing has
+  changed, and developers must manually re-run CI to restore a passing state.
+fix: |
+  Include github.event_name in the concurrency group key so that pull_request CI
+  runs and pull_request_review-triggered runs occupy separate, independent slots:
+
+    group: ${{ github.workflow }}-${{ github.event_name }}-${{ github.event.pull_request.number }}
+
+  Alternatively, split the pull_request_review trigger into a separate workflow file
+  that handles review-gated tasks (labeling, auto-approve, notifications) while
+  keeping CI in a dedicated pull_request-only workflow with its own concurrency group.
+fix_code:
+  - language: yaml
+    label: 'Broken: reviewer approval cancels in-progress CI run'
+    code: |
+      on:
+        pull_request:
+        pull_request_review:
+          types: [submitted]
+
+      concurrency:
+        group: ci-${{ github.event.pull_request.number }}
+        cancel-in-progress: true
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: make test
+  - language: yaml
+    label: 'Fixed: include event_name to give each event type its own concurrency slot'
+    code: |
+      on:
+        pull_request:
+        pull_request_review:
+          types: [submitted]
+
+      concurrency:
+        # pull_request pushes: ci-pull_request-42
+        # pull_request_review submissions: ci-pull_request_review-42 (independent)
+        group: ci-${{ github.event_name }}-${{ github.event.pull_request.number }}
+        cancel-in-progress: true
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: make test
+  - language: yaml
+    label: 'Alternative: split CI and review automation into separate workflow files'
+    code: |
+      # .github/workflows/ci.yml — triggered by code changes only
+      on:
+        pull_request:
+
+      concurrency:
+        group: ci-${{ github.event.pull_request.number }}
+        cancel-in-progress: true
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: make test
+
+      # .github/workflows/review-automation.yml — review gating only
+      on:
+        pull_request_review:
+          types: [submitted]
+
+      jobs:
+        label-approved:
+          if: github.event.review.state == 'approved'
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "PR approved — add label or trigger deploy"
+prevention:
+  - 'Audit any workflow with multiple on: event triggers for cross-event concurrency group collisions — confirm that each event type resolves to a unique group key unless intentional sharing is desired'
+  - 'Include ${{ github.event_name }} in concurrency group keys for workflows triggered by more than one event type to prevent unintended cross-event cancellation'
+  - 'Use separate workflow files for CI checks (on.pull_request) and review-automation tasks (on.pull_request_review) to avoid shared concurrency group interference'
+  - 'When debugging unexpectedly cancelled CI runs, check the Actions tab for runs with "Cancelled" status — filter by trigger event to identify whether a pull_request_review submission was the cancelling run'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#pull_request_review'
+    label: 'GitHub Docs: pull_request_review event'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-concurrency'
+    label: 'GitHub Docs: Using concurrency'
+  - url: 'https://github.com/orgs/community/discussions/26336'
+    label: 'GitHub Community: Concurrency cancel-in-progress cancels CI on review submission'

package/errors/known-unsolved/github-script-esm-not-supported.yml

@@ -0,0 +1,111 @@
+id: known-unsolved-061
+title: 'actions/github-script does not support ESM — import statements and ESM-only packages fail'
+category: known-unsolved
+severity: error
+tags:
+  - github-script
+  - esm
+  - commonjs
+  - import
+  - ERR_REQUIRE_ESM
+  - octokit
+  - javascript
+patterns:
+  - regex: 'SyntaxError: Cannot use import statement in a module'
+    flags: 'i'
+  - regex: 'ERR_REQUIRE_ESM'
+    flags: 'i'
+  - regex: 'require\(\) of ES Module.*is not supported'
+    flags: 'i'
+  - regex: 'must use import to load ES Module'
+    flags: 'i'
+error_messages:
+  - "SyntaxError: Cannot use import statement in a module"
+  - "Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/node_modules/pkg/index.mjs is not supported."
+  - "Instead change the require of ... to a dynamic import() which is available in all CommonJS modules."
+  - "Error: Must use import to load ES Module: /path/to/node_modules/pkg/index.js"
+root_cause: |
+  actions/github-script evaluates the inline `script:` input using Node.js vm.Script in a
+  CommonJS (CJS) module context. ECMAScript Module (ESM) syntax is fundamentally incompatible
+  with this execution model:
+
+  1. Top-level `import ... from` statements → SyntaxError: "Cannot use import statement in a module"
+     because vm.Script runs in CJS mode and the `import` keyword is a syntax error at parse time.
+
+  2. require() of an ESM-only package (e.g., modern @octokit/rest ≥ 5.x, chalk ≥ 5.x,
+     node-fetch ≥ 3.x, got ≥ 12.x, axios ≥ 2.x) → ERR_REQUIRE_ESM because those packages
+     publish only .mjs or set "type": "module" in package.json, making them incompatible
+     with require().
+
+  3. External scripts loaded via `const fn = require('./my-script.js')` also run in a CJS
+     context — ESM syntax inside those files also fails.
+
+  The github-script action has no current plan to migrate to ESM execution, and supporting
+  both modes simultaneously in vm.Script is architecturally complex. This is a long-standing
+  limitation open since 2024 with 30+ reactions and no scheduled resolution.
+
+  The GitHub Actions toolkit itself (github-script's own dependencies) also pins to
+  CJS-compatible versions of @octokit packages for this reason.
+fix: |
+  There is no built-in fix — actions/github-script does not support ESM. Use these workarounds:
+
+  WORKAROUND 1 (recommended): Use dynamic import() inside an async function
+  Dynamic import() IS supported inside github-script because it is a CJS-compatible
+  expression (not top-level ESM syntax). Wrap the entire script in an async IIFE or
+  use the top-level await that github-script already provides:
+
+    const { Octokit } = await import('@octokit/rest')
+
+  WORKAROUND 2: Use a CJS-compatible version of the package
+  Many packages (chalk, got, axios, node-fetch) have a last CJS-compatible version.
+  Pin to that in your workflow step using node or npm:
+
+    chalk: ^4.1.2 (last CJS version; chalk 5.x is ESM-only)
+    node-fetch: ^2.7.0 (last CJS version; 3.x is ESM-only)
+    got: ^11.8.6 (last CJS version; 12.x is ESM-only)
+
+  WORKAROUND 3: Create a composite or JavaScript action with a proper ESM Node runtime
+  For complex scripts that heavily use ESM packages, extract them into a standalone
+  composite or JavaScript action that declares "main": "./dist/index.mjs" in action.yml.
+fix_code:
+  - language: yaml
+    label: 'Use dynamic import() for ESM-only packages in github-script'
+    code: |
+      - name: Use ESM package via dynamic import()
+        uses: actions/github-script@v7
+        with:
+          script: |
+            // Dynamic import() works in github-script even though top-level import does not
+            const { Octokit } = await import('@octokit/rest')
+            const { default: chalk } = await import('chalk')
+            // github, context, core are still available as usual
+            const result = await github.rest.repos.get({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+            })
+            core.info(chalk.green(`Repo: ${result.data.full_name}`))
+  - language: yaml
+    label: 'Pin to last CJS-compatible version of common packages'
+    code: |
+      - name: Install CJS-compatible package versions
+        run: npm install chalk@4 node-fetch@2 got@11
+
+      - name: Use CJS packages in github-script
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const chalk = require('chalk')   // chalk@4 is CJS — works fine
+            const fetch = require('node-fetch')  // node-fetch@2 is CJS
+            core.info(chalk.blue('Using CJS-compatible packages'))
+prevention:
+  - 'Check whether a package is ESM-only before using it in github-script — look for "type": "module" in its package.json'
+  - 'Use dynamic import() as the default pattern for any external package in github-script'
+  - 'For scripts that require heavy ESM ecosystem usage, consider a dedicated JavaScript action instead of github-script'
+  - 'Stay on chalk@4, node-fetch@2, got@11, axios@1 in github-script workflows — these are the last CJS-compatible majors'
+docs:
+  - url: 'https://github.com/actions/github-script/issues/457'
+    label: 'actions/github-script#457: Feature request — ESM support (open, 30+ reactions)'
+  - url: 'https://nodejs.org/api/esm.html#interoperability-with-commonjs'
+    label: 'Node.js Docs — ESM and CommonJS interoperability'
+  - url: 'https://github.com/actions/github-script#use-scripts-with-jsdoc-support'
+    label: 'actions/github-script — README: use scripts with JSDoc support'

package/errors/known-unsolved/job-outputs-string-only-no-array-object.yml

@@ -0,0 +1,142 @@
+id: known-unsolved-060
+title: 'Job outputs are strings only — arrays, objects, and booleans must be manually JSON-serialized'
+category: known-unsolved
+severity: limitation
+tags:
+  - job-outputs
+  - outputs
+  - string
+  - fromJSON
+  - array
+  - known-limitation
+  - GITHUB_OUTPUT
+patterns:
+  - regex: 'GITHUB_OUTPUT'
+    flags: 'i'
+  - regex: 'needs\.[a-z_-]+\.outputs\.'
+    flags: 'i'
+  - regex: 'fromJSON\s*\('
+    flags: 'i'
+error_messages:
+  - '(no runtime error — arrays or objects written to GITHUB_OUTPUT are silently converted to strings like "Array" or "[object Object]" if not JSON-serialized before writing)'
+root_cause: |
+  GitHub Actions job outputs use the GITHUB_OUTPUT file protocol which only supports
+  string key-value pairs. There is no native type system for job outputs — every
+  value passed through GITHUB_OUTPUT is stored and transmitted as a plain string,
+  regardless of the producing language or shell.
+
+  This becomes a problem in several common scenarios:
+
+  1. Passing arrays: A bash array or newline-separated list written to GITHUB_OUTPUT
+     becomes a space-separated string or a literal "[array]" — not a JSON array.
+     Downstream matrix.include: fromJSON() fails or produces a single-element matrix.
+
+  2. Passing objects: A JSON object must be written as a compact single-line string.
+     Multi-line JSON written to GITHUB_OUTPUT breaks the key=value line format and
+     corrupts the output, causing a parse error or silently reading only the first
+     line as the value.
+
+  3. Boolean comparisons: Outputs written as "true" or "false" are strings, not
+     booleans. Comparing ${{ needs.x.outputs.flag == true }} (boolean literal)
+     silently evaluates to false; only ${{ needs.x.outputs.flag == 'true' }} (string)
+     or ${{ fromJSON(needs.x.outputs.flag) }} works correctly.
+
+  This is a known platform limitation. The GitHub Actions team has acknowledged the
+  string-only constraint in multiple community discussions. There is no native typed
+  output support on the public roadmap as of mid-2026, and no timeline has been given
+  for adding array or object output types.
+fix: |
+  Serialize arrays and objects to compact single-line JSON before writing to
+  GITHUB_OUTPUT, then deserialize with fromJSON() in consuming jobs.
+
+  Key rule: use jq -c to produce compact (one-line) JSON — multi-line JSON
+  embedded in GITHUB_OUTPUT silently truncates at the first newline.
+
+  For booleans: write the literal string "true"/"false" and compare with == 'true'
+  in if: conditions, or wrap with fromJSON() to get a native boolean for contexts
+  that require one (e.g., matrix include).
+fix_code:
+  - language: yaml
+    label: 'Write and consume a JSON array as a job output'
+    code: |
+      jobs:
+        generate-matrix:
+          runs-on: ubuntu-latest
+          outputs:
+            targets: ${{ steps.set-matrix.outputs.targets }}
+          steps:
+            - id: set-matrix
+              run: |
+                # Use jq -c for compact single-line JSON — multi-line breaks GITHUB_OUTPUT
+                TARGETS=$(echo '[{"env":"staging"},{"env":"prod"}]' | jq -c .)
+                echo "targets=$TARGETS" >> "$GITHUB_OUTPUT"
+
+        deploy:
+          needs: generate-matrix
+          strategy:
+            matrix:
+              target: ${{ fromJSON(needs.generate-matrix.outputs.targets) }}
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Deploying to ${{ matrix.target.env }}"
+  - language: yaml
+    label: 'Boolean output — write as string, compare correctly downstream'
+    code: |
+      jobs:
+        check-changes:
+          runs-on: ubuntu-latest
+          outputs:
+            has_changes: ${{ steps.diff.outputs.has_changes }}
+          steps:
+            - id: diff
+              run: |
+                if git diff --quiet HEAD~1; then
+                  echo "has_changes=false" >> "$GITHUB_OUTPUT"
+                else
+                  echo "has_changes=true" >> "$GITHUB_OUTPUT"
+                fi
+
+        build:
+          needs: check-changes
+          # Compare as string literal — NOT: == true (boolean comparison silently fails)
+          if: needs.check-changes.outputs.has_changes == 'true'
+          runs-on: ubuntu-latest
+          steps:
+            - run: make build
+  - language: yaml
+    label: 'Multi-line JSON — always compact with jq -c before writing'
+    code: |
+      jobs:
+        gather-config:
+          runs-on: ubuntu-latest
+          outputs:
+            config: ${{ steps.read-config.outputs.config }}
+          steps:
+            - uses: actions/checkout@v4
+            - id: read-config
+              run: |
+                # jq -c converts any JSON (even pretty-printed) to a single compact line
+                CONFIG=$(cat deploy-config.json | jq -c .)
+                echo "config=$CONFIG" >> "$GITHUB_OUTPUT"
+
+        deploy:
+          needs: gather-config
+          runs-on: ubuntu-latest
+          steps:
+            - run: |
+                CONFIG='${{ needs.gather-config.outputs.config }}'
+                echo "Region: $(echo "$CONFIG" | jq -r .region)"
+prevention:
+  - 'Always pipe JSON values through jq -c before writing to GITHUB_OUTPUT — compact single-line format prevents silent value truncation at embedded newlines'
+  - 'Compare boolean-string outputs with == ''true'' (string) not == true (boolean) in if: conditions; or use fromJSON() to convert to a native boolean'
+  - 'Never write a raw bash array to GITHUB_OUTPUT — it expands to a space-separated string; always serialize through jq -c first'
+  - 'Add a debug step that prints the raw output value using cat $GITHUB_OUTPUT before a consuming job runs, to confirm the serialized form looks correct'
+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/choosing-what-your-workflow-does/workflow-commands-for-github-actions#setting-an-output-parameter'
+    label: 'GitHub Docs: Setting an output parameter (GITHUB_OUTPUT)'
+  - url: 'https://github.com/orgs/community/discussions/17245'
+    label: 'GitHub Community: Job outputs only support strings — feature request for typed outputs'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/evaluate-expressions-in-workflows-and-actions#fromjson'
+    label: 'GitHub Docs: fromJSON expression function'