@htekdev/actions-debugger 1.0.0 → 1.0.1

package/errors/triggers/cron-schedule-late.yml

@@ -1,59 +1,59 @@
-id: triggers-003
-title: "Cron Schedule Running Late or Not Running"
-category: triggers
-severity: warning
-tags:
-  - cron
-  - schedule
-  - delay
-  - forks
-  - best-effort
-patterns:
-  - regex: "schedule"
-    flags: "i"
-  - regex: "Delayed"
-    flags: "i"
-  - regex: "This event will only trigger a workflow run if the workflow file exists on the default branch"
-    flags: "i"
-error_messages:
-  - "Scheduled workflows can be delayed during periods of high loads of GitHub Actions workflow runs."
-root_cause: |
-  GitHub Actions cron is best-effort, not real-time scheduling. During peak usage windows,
-  scheduled workflows can start 15 to 45 minutes late. In forks, scheduled workflows are also
-  disabled by default, so a copied workflow may never run until someone explicitly enables it.
-
-  The YAML can be correct and the repository can still see timing drift because the platform
-  does not guarantee precise minute-by-minute execution.
-fix: |
-  Treat cron timing as approximate. Schedule important automations away from the top of the
-  hour, add tolerance for startup drift, and provide a `workflow_dispatch` fallback for jobs
-  that sometimes need manual recovery.
-fix_code:
-  - language: yaml
-    label: "Add jitter-friendly scheduling and manual fallback"
-    code: |
-      name: Nightly maintenance
-
-      on:
-        schedule:
-          - cron: '17 3 * * *'
-        workflow_dispatch:
-
-      jobs:
-        maintain:
-          runs-on: ubuntu-latest
-          steps:
-            - uses: actions/checkout@v4
-            - run: ./scripts/maintenance.sh
-prevention:
-  - "Avoid scheduling critical jobs exactly at minute 0 because that is a common contention window."
-  - "Use external monitoring if a schedule must be near-real-time."
-  - "Enable scheduled workflows manually after creating a fork or after long inactivity."
-docs:
-  - url: "https://docs.github.com/en/actions/reference/events-that-trigger-workflows#schedule"
-    label: "schedule event"
-  - url: "https://docs.github.com/en/actions/managing-workflow-runs/disabling-and-enabling-a-workflow"
-    label: "Disable and enable a workflow"
-source:
-  article: "https://htek.dev/articles/github-actions-debugging-guide"
-  section: "Cron schedules running late"
+id: triggers-003
+title: "Cron Schedule Running Late or Not Running"
+category: triggers
+severity: warning
+tags:
+  - cron
+  - schedule
+  - delay
+  - forks
+  - best-effort
+patterns:
+  - regex: "schedule"
+    flags: "i"
+  - regex: "Delayed"
+    flags: "i"
+  - regex: "This event will only trigger a workflow run if the workflow file exists on the default branch"
+    flags: "i"
+error_messages:
+  - "Scheduled workflows can be delayed during periods of high loads of GitHub Actions workflow runs."
+root_cause: |
+  GitHub Actions cron is best-effort, not real-time scheduling. During peak usage windows,
+  scheduled workflows can start 15 to 45 minutes late. In forks, scheduled workflows are also
+  disabled by default, so a copied workflow may never run until someone explicitly enables it.
+
+  The YAML can be correct and the repository can still see timing drift because the platform
+  does not guarantee precise minute-by-minute execution.
+fix: |
+  Treat cron timing as approximate. Schedule important automations away from the top of the
+  hour, add tolerance for startup drift, and provide a `workflow_dispatch` fallback for jobs
+  that sometimes need manual recovery.
+fix_code:
+  - language: yaml
+    label: "Add jitter-friendly scheduling and manual fallback"
+    code: |
+      name: Nightly maintenance
+
+      on:
+        schedule:
+          - cron: '17 3 * * *'
+        workflow_dispatch:
+
+      jobs:
+        maintain:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: ./scripts/maintenance.sh
+prevention:
+  - "Avoid scheduling critical jobs exactly at minute 0 because that is a common contention window."
+  - "Use external monitoring if a schedule must be near-real-time."
+  - "Enable scheduled workflows manually after creating a fork or after long inactivity."
+docs:
+  - url: "https://docs.github.com/en/actions/reference/events-that-trigger-workflows#schedule"
+    label: "schedule event"
+  - url: "https://docs.github.com/en/actions/managing-workflow-runs/disabling-and-enabling-a-workflow"
+    label: "Disable and enable a workflow"
+source:
+  article: "https://htek.dev/articles/github-actions-debugging-guide"
+  section: "Cron schedules running late"

package/errors/triggers/pull-request-target-rce-risk.yml

@@ -0,0 +1,117 @@
+id: triggers-005
+title: "pull_request_target Runs Fork Code with Base Branch Secrets — RCE Risk"
+category: triggers
+severity: error
+tags:
+  - pull_request_target
+  - security
+  - fork
+  - secrets
+  - code-injection
+  - pwn-request
+  - base-branch
+patterns:
+  - regex: "pull_request_target"
+    flags: "i"
+  - regex: "github\\.event\\.pull_request\\.head\\.sha"
+    flags: "i"
+error_messages:
+  - "Warning: Workflow uses pull_request_target with actions/checkout on PR head — potential code injection vulnerability."
+root_cause: |
+  `pull_request_target` was designed to give workflows triggered by fork PRs access to
+  **base branch secrets and write permissions**. Unlike `pull_request`, it runs in the
+  context of the **base repository**, not the fork — so `secrets.*` is available and
+  `GITHUB_TOKEN` has write permissions.
+
+  The danger: many developers combine `pull_request_target` with
+  `actions/checkout@v4 ref: ${{ github.event.pull_request.head.sha }}` to check out the
+  **fork's code** for testing. Running untrusted fork code with full secret access is a
+  critical Remote Code Execution (RCE) vulnerability — the contributor can exfiltrate
+  all repository secrets simply by adding malicious code to their PR.
+
+  This class of vulnerability is known as "pwn request" and has been exploited against
+  major open-source projects.
+fix: |
+  When using `pull_request_target`, ALWAYS check out the base branch (not the PR head).
+  If you need to run the PR author's code AND have secret access, use a two-workflow pattern:
+  an unprivileged `pull_request` workflow builds and uploads artifacts, then a privileged
+  `workflow_run` workflow (with no access to fork code) deploys them.
+fix_code:
+  - language: yaml
+    label: "CRITICAL VULNERABILITY — checkout of fork code with secret access"
+    code: |
+      on: pull_request_target    # has secret access
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            # DANGEROUS: checking out untrusted PR code with base repo secrets
+            - uses: actions/checkout@v4
+              with:
+                ref: ${{ github.event.pull_request.head.sha }}   # NEVER DO THIS
+            - run: npm test   # attacker's code runs with your secrets
+  - language: yaml
+    label: "SAFE — pull_request_target checking out base only (for labels/comments)"
+    code: |
+      on:
+        pull_request_target:
+          types: [opened, labeled]
+
+      jobs:
+        label:
+          runs-on: ubuntu-latest
+          permissions:
+            pull-requests: write
+          steps:
+            # SAFE: checking out base repo code only (not the PR branch)
+            - uses: actions/checkout@v4
+              # No 'ref:' — defaults to base branch
+            - name: Add label
+              uses: actions-ecosystem/action-add-labels@v1
+              with:
+                github_token: ${{ secrets.GITHUB_TOKEN }}
+                labels: needs-review
+  - language: yaml
+    label: "SAFE — two-workflow pattern: build unprivileged, deploy privileged"
+    code: |
+      # Workflow 1: ci.yml — triggered by pull_request (no secrets, untrusted code OK)
+      on: pull_request
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4   # fork code, but no secrets
+            - run: npm ci && npm run build
+            - uses: actions/upload-artifact@v4
+              with:
+                name: build-output
+                path: dist/
+
+      # Workflow 2: deploy-pr-preview.yml — triggered by workflow_run (has secrets, no fork code)
+      on:
+        workflow_run:
+          workflows: [CI]
+          types: [completed]
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          if: github.event.workflow_run.conclusion == 'success'
+          steps:
+            - uses: actions/download-artifact@v4   # downloads artifact, not fork code
+              with:
+                github-token: ${{ secrets.GITHUB_TOKEN }}
+                run-id: ${{ github.event.workflow_run.id }}
+                name: build-output
+            - run: ./deploy-preview.sh   # safe: runs base repo script with downloaded artifact
+prevention:
+  - "NEVER use `actions/checkout ref: github.event.pull_request.head.sha` inside a `pull_request_target` workflow."
+  - "Use the two-workflow pattern (unprivileged `pull_request` + privileged `workflow_run`) for PR preview deployments."
+  - "Restrict `pull_request_target` to safe operations: labeling, commenting, and running base repo scripts only."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#pull_request_target"
+    label: "pull_request_target event"
+  - url: "https://securitylab.github.com/resources/github-actions-preventing-pwn-requests/"
+    label: "Preventing pwn requests (GitHub Security Lab)"
+  - url: "https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions#understanding-the-risk-of-script-injections"
+    label: "Security hardening — script injection"

package/errors/triggers/workflow-not-triggering.yml

@@ -1,60 +1,60 @@
-id: triggers-001
-title: "Workflow Not Triggering At All"
-category: triggers
-severity: error
-tags:
-  - triggers
-  - workflow-file
-  - default-branch
-  - on
-  - events
-patterns:
-  - regex: "This event will only trigger a workflow run if the workflow file exists on the default branch"
-    flags: "i"
-  - regex: "Workflow file .* not found on the default branch"
-    flags: "i"
-  - regex: "No runs found for this workflow"
-    flags: "i"
-error_messages:
-  - "This event will only trigger a workflow run if the workflow file exists on the default branch"
-root_cause: |
-  Some events only trigger if the workflow file itself exists on the repository's default
-  branch. A workflow can look perfectly valid in a feature branch, but GitHub will ignore it
-  for certain event types until the file is present on the default branch with correct `on:`
-  syntax and placement under `.github/workflows/`.
-
-  A wrong indentation level under `on:`, a typo in the event name, or putting the file in the
-  wrong directory can create the same symptom: nothing runs.
-fix: |
-  Confirm the workflow file lives in `.github/workflows/`, validate the `on:` block, and make
-  sure the workflow file already exists on the default branch for the event you expect to fire.
-fix_code:
-  - language: yaml
-    label: "Use valid workflow location and trigger syntax"
-    code: |
-      name: CI
-
-      on:
-        push:
-          branches:
-            - main
-        pull_request:
-
-      jobs:
-        test:
-          runs-on: ubuntu-latest
-          steps:
-            - uses: actions/checkout@v4
-            - run: npm test
-prevention:
-  - "Keep workflow files only under `.github/workflows/`."
-  - "Merge new workflow files to the default branch before relying on events like `schedule` or `workflow_dispatch`."
-  - "Validate event names and indentation in every `on:` block."
-docs:
-  - url: "https://docs.github.com/en/actions/reference/events-that-trigger-workflows"
-    label: "Events that trigger workflows"
-  - url: "https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions"
-    label: "Workflow syntax for GitHub Actions"
-source:
-  article: "https://htek.dev/articles/github-actions-debugging-guide"
-  section: "Workflow not triggering"
+id: triggers-001
+title: "Workflow Not Triggering At All"
+category: triggers
+severity: error
+tags:
+  - triggers
+  - workflow-file
+  - default-branch
+  - on
+  - events
+patterns:
+  - regex: "This event will only trigger a workflow run if the workflow file exists on the default branch"
+    flags: "i"
+  - regex: "Workflow file .* not found on the default branch"
+    flags: "i"
+  - regex: "No runs found for this workflow"
+    flags: "i"
+error_messages:
+  - "This event will only trigger a workflow run if the workflow file exists on the default branch"
+root_cause: |
+  Some events only trigger if the workflow file itself exists on the repository's default
+  branch. A workflow can look perfectly valid in a feature branch, but GitHub will ignore it
+  for certain event types until the file is present on the default branch with correct `on:`
+  syntax and placement under `.github/workflows/`.
+
+  A wrong indentation level under `on:`, a typo in the event name, or putting the file in the
+  wrong directory can create the same symptom: nothing runs.
+fix: |
+  Confirm the workflow file lives in `.github/workflows/`, validate the `on:` block, and make
+  sure the workflow file already exists on the default branch for the event you expect to fire.
+fix_code:
+  - language: yaml
+    label: "Use valid workflow location and trigger syntax"
+    code: |
+      name: CI
+
+      on:
+        push:
+          branches:
+            - main
+        pull_request:
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm test
+prevention:
+  - "Keep workflow files only under `.github/workflows/`."
+  - "Merge new workflow files to the default branch before relying on events like `schedule` or `workflow_dispatch`."
+  - "Validate event names and indentation in every `on:` block."
+docs:
+  - url: "https://docs.github.com/en/actions/reference/events-that-trigger-workflows"
+    label: "Events that trigger workflows"
+  - url: "https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions"
+    label: "Workflow syntax for GitHub Actions"
+source:
+  article: "https://htek.dev/articles/github-actions-debugging-guide"
+  section: "Workflow not triggering"

package/errors/triggers/workflow-run-default-branch-requirement.yml

@@ -0,0 +1,78 @@
+id: triggers-004
+title: "workflow_run Trigger Fires Only When Source Workflow Exists on Default Branch"
+category: triggers
+severity: error
+tags:
+  - workflow_run
+  - triggers
+  - default-branch
+  - main
+  - workflow-file
+  - not-triggering
+patterns:
+  - regex: "workflow_run.*not triggering"
+    flags: "i"
+  - regex: "workflow_run.*workflow.*not found"
+    flags: "i"
+error_messages:
+  - "The workflow 'CI' referenced by workflow_run trigger was not found or does not exist on the default branch."
+root_cause: |
+  GitHub resolves `workflow_run` triggers by looking up the **source workflow's file name
+  on the repository's default branch** at trigger time. This has two important implications:
+
+  1. **The source workflow file must exist on the default branch** — a `workflow_run` trigger
+     in a PR branch will not fire when the referenced workflow runs on that branch, if the
+     source workflow file doesn't exist on `main`/`master` yet.
+
+  2. **The trigger workflow itself must also be on the default branch** — the `workflow_run`
+     trigger in `on:` is only read from the default branch, regardless of which branch
+     the triggering push happened on.
+
+  This is a common blocker during initial feature development: a developer adds both the
+  source workflow and the `workflow_run` consumer in the same PR branch. Neither fires
+  correctly until both files are merged to the default branch.
+fix: |
+  Ensure both the source workflow and the `workflow_run` consumer exist on the default
+  branch before testing. When adding new CI workflows, merge to main/master first, then
+  test from a feature branch.
+fix_code:
+  - language: yaml
+    label: "Example workflow_run trigger — source must be on default branch"
+    code: |
+      # .github/workflows/deploy.yml  (must be on default branch to work)
+      on:
+        workflow_run:
+          workflows: ["CI"]       # "CI" must match the 'name:' field in ci.yml
+          types: [completed]      # fires when CI workflow completes (any branch)
+          branches: [main]        # optional: only when CI ran on these branches
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          if: ${{ github.event.workflow_run.conclusion == 'success' }}
+          steps:
+            - run: ./deploy.sh
+  - language: yaml
+    label: "Check workflow name matches exactly (case-sensitive)"
+    code: |
+      # .github/workflows/ci.yml
+      name: CI                    # this exact string must match workflow_run trigger
+
+      on:
+        push:
+          branches: [main, 'feature/**']
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - run: npm test
+prevention:
+  - "Merge the source workflow to the default branch before adding a `workflow_run` consumer — test with both files on `main`."
+  - "The `workflows:` list matches on the workflow's `name:` field (the YAML `name:` key), not the filename."
+  - "Use `branches:` filter in `workflow_run` to prevent deploy from triggering on every feature branch run."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_run"
+    label: "workflow_run trigger"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/triggering-a-workflow#triggering-a-workflow-from-a-workflow"
+    label: "Triggering a workflow from a workflow"

package/errors/yaml-syntax/anchors-not-supported.yml

@@ -0,0 +1,95 @@
+id: yaml-syntax-009
+title: "YAML Anchors and Aliases Rejected by Workflow Parser"
+category: yaml-syntax
+severity: error
+tags:
+  - yaml
+  - anchors
+  - aliases
+  - dry
+  - reuse
+  - syntax
+patterns:
+  - regex: "Anchors are not supported"
+    flags: "i"
+  - regex: "could not parse the yaml file"
+    flags: "i"
+  - regex: "mapping values are not allowed in this context"
+    flags: "i"
+error_messages:
+  - "The workflow is not valid. .github/workflows/ci.yml: Anchors are not supported."
+  - "could not parse the yaml file '.github/workflows/ci.yml'"
+root_cause: |
+  GitHub Actions' workflow parser explicitly rejects YAML anchors (`&`) and aliases (`*`)
+  even though they are valid YAML 1.2 constructs. Developers familiar with Docker Compose
+  or Kubernetes manifests commonly attempt to DRY up repetitive step blocks using anchors
+  and merge keys (`<<: *defaults`), but the GitHub-hosted workflow validator rejects the
+  file on parse rather than silently ignoring the constructs.
+
+  The restriction is documented and intentional — GitHub's parser does not implement the
+  full YAML 1.2 merge-key extension.
+fix: |
+  Remove all YAML anchors and aliases from workflow files. Use one of GitHub Actions'
+  native reuse mechanisms instead: composite actions for shared step sequences, reusable
+  workflows (`workflow_call`) for sharing entire job graphs, or a matrix strategy for
+  parameterized repetition.
+fix_code:
+  - language: yaml
+    label: "WRONG — YAML anchor and merge key (rejected)"
+    code: |
+      .defaults: &defaults
+        runs-on: ubuntu-latest
+        timeout-minutes: 10
+
+      jobs:
+        build:
+          <<: *defaults
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm ci && npm run build
+
+        test:
+          <<: *defaults
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm test
+  - language: yaml
+    label: "CORRECT — composite action for shared steps"
+    code: |
+      # .github/actions/setup/action.yml
+      name: Setup
+      runs:
+        using: composite
+        steps:
+          - uses: actions/checkout@v4
+          - uses: actions/setup-node@v4
+            with:
+              node-version: 20
+              cache: npm
+
+      # .github/workflows/ci.yml
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          timeout-minutes: 10
+          steps:
+            - uses: ./.github/actions/setup
+            - run: npm run build
+
+        test:
+          runs-on: ubuntu-latest
+          timeout-minutes: 10
+          steps:
+            - uses: ./.github/actions/setup
+            - run: npm test
+prevention:
+  - "Use composite actions (`.github/actions/`) to share step sequences across jobs."
+  - "Use reusable workflows (`workflow_call`) to share entire job structures."
+  - "Lint workflow files with `actionlint` locally — it reports anchor usage before pushing."
+docs:
+  - url: "https://docs.github.com/en/actions/sharing-automations/reusing-workflows"
+    label: "Reusing workflows"
+  - url: "https://docs.github.com/en/actions/sharing-automations/creating-actions/creating-a-composite-action"
+    label: "Creating a composite action"
+  - url: "https://rhysd.github.io/actionlint/"
+    label: "actionlint — static checker for GitHub Actions"

package/errors/yaml-syntax/dynamic-matrix-fromjson-failure.yml

@@ -0,0 +1,99 @@
+id: yaml-syntax-008
+title: "Dynamic Matrix fromJSON Fails on Empty or Malformed JSON"
+category: yaml-syntax
+severity: error
+tags:
+  - matrix
+  - fromJSON
+  - dynamic-matrix
+  - strategy
+  - expressions
+patterns:
+  - regex: "Error when evaluating 'strategy' for job"
+    flags: "i"
+  - regex: "Error parsing fromJson"
+    flags: "i"
+  - regex: "Error reading JToken from JsonReader"
+    flags: "i"
+  - regex: "matrix contains zero elements"
+    flags: "i"
+  - regex: "Unexpected type of value '', expected type: Sequence"
+    flags: "i"
+error_messages:
+  - "Error when evaluating 'strategy' for job 'build'. .github/workflows/ci.yml (Line: 12, Col: 14): Error parsing fromJson"
+  - "Error reading JToken from JsonReader. Path '', line 0, position 0."
+  - "Unexpected type of value '', expected type: Sequence."
+  - "Error when evaluating 'strategy' for job 'test'. matrix contains zero elements"
+root_cause: |
+  When using `fromJSON()` in a matrix strategy to build a dynamic matrix from a previous
+  job's output, three common failure modes occur:
+
+  1. **Empty string**: The upstream step produced no output (empty stdout or unset output
+     variable), so `fromJSON('')` receives an empty string and the JSON parser fails with
+     "Error reading JToken from JsonReader."
+
+  2. **Zero-element array**: The upstream step produces a valid JSON array but it is empty
+     (`[]`). GitHub Actions evaluates the strategy and then immediately fails the job
+     because it has nothing to schedule — "matrix contains zero elements."
+
+  3. **Malformed JSON**: Newlines, unescaped quotes, or shell word-splitting corrupts the
+     JSON string before it reaches fromJSON, producing parse errors such as
+     "Unexpected type of value '', expected type: Sequence."
+
+  All three root causes trace back to the step that generates the matrix JSON, not to
+  fromJSON itself. Using `jq` without `-c` (compact output) can embed literal newlines
+  that break the output variable; similarly, forgetting to set the output with
+  `echo "matrix=..." >> $GITHUB_OUTPUT` leaves the variable empty.
+fix: |
+  1. Always produce compact, single-line JSON with `jq -c` and write it to
+     `$GITHUB_OUTPUT` (not `$GITHUB_ENV`) in the generator step.
+  2. Guard against an empty matrix by providing a fallback single-element array, or add
+     an `if` condition to skip the matrix job when the generator output is empty.
+  3. Echo and verify the generated JSON in a debug step before the matrix job runs.
+fix_code:
+  - language: yaml
+    label: "Correct dynamic matrix pattern with empty-guard"
+    code: |
+      jobs:
+        generate:
+          runs-on: ubuntu-latest
+          outputs:
+            matrix: ${{ steps.set-matrix.outputs.matrix }}
+          steps:
+            - id: set-matrix
+              run: |
+                # Produce compact JSON; default to ["none"] if list is empty
+                ITEMS=$(cat targets.txt | jq -Rc '[.]' | jq -sc 'add // ["none"]')
+                echo "matrix=${ITEMS}" >> $GITHUB_OUTPUT
+
+        build:
+          needs: generate
+          # Skip if only the fallback placeholder is present
+          if: ${{ needs.generate.outputs.matrix != '["none"]' }}
+          strategy:
+            matrix:
+              target: ${{ fromJSON(needs.generate.outputs.matrix) }}
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Building ${{ matrix.target }}"
+  - language: yaml
+    label: "Debug step to verify JSON before matrix job"
+    code: |
+      - name: Verify matrix JSON
+        run: |
+          echo "Matrix value: ${{ needs.generate.outputs.matrix }}"
+          echo '${{ needs.generate.outputs.matrix }}' | jq .
+prevention:
+  - "Always use `jq -c` (compact output) when producing JSON for matrix outputs to avoid embedded newlines."
+  - "Write matrix JSON to `$GITHUB_OUTPUT`, not `$GITHUB_ENV` — environment variables are not available as job outputs."
+  - "Add an empty-matrix guard (`if` condition or fallback value) so a zero-element array does not silently break your pipeline."
+  - "Add a debug step after the generator to echo and validate the JSON before the dependent job runs."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/running-variations-of-jobs-in-a-workflow"
+    label: "Running variations of jobs in a workflow (matrix)"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/evaluate-expressions-in-workflows-and-actions#fromjson"
+    label: "fromJSON expression function"
+  - url: "https://github.com/actions/runner/issues/2424"
+    label: "actions/runner#2424 — fromJSON parsing failures in nested workflows"
+  - url: "https://github.com/orgs/community/discussions/27096"
+    label: "Community: matrix contains zero elements"