@htekdev/actions-debugger 1.0.0 → 1.0.1

package/errors/concurrency-timing/cancel-in-progress-deploy-drops.yml

@@ -0,0 +1,97 @@
+id: concurrency-timing-002
+title: "cancel-in-progress Silently Drops In-Flight Deploy Runs"
+category: concurrency-timing
+severity: silent-failure
+tags:
+  - concurrency
+  - cancel-in-progress
+  - deployment
+  - silent-failure
+  - queue
+patterns:
+  - regex: "Run was cancelled"
+    flags: "i"
+  - regex: "Canceling since a higher priority waiting run was found"
+    flags: "i"
+  - regex: "This run was cancelled by a more recent run"
+    flags: "i"
+error_messages:
+  - "Run was cancelled"
+  - "Canceling since a higher priority waiting run was found"
+  - "This run was cancelled by a more recent run"
+root_cause: |
+  When a workflow sets `concurrency.cancel-in-progress: true`, GitHub Actions cancels
+  any currently running workflow in the same concurrency group the moment a new run
+  starts. This is intentional for CI (cancel stale PR checks), but is dangerous for
+  **deploy** workflows where every commit must be deployed in order.
+
+  The silent failure happens because:
+  - The cancelled run is marked "CANCELLED" in the UI — it does not appear as a
+    failure, so PR status checks may still pass.
+  - If the cancelled run was mid-deploy (e.g., partway through Terraform apply or a
+    Kubernetes rollout), the environment is left in a partially-updated state.
+  - Developers see the new run succeed and assume all commits were deployed, when in
+    reality one or more intermediate commits were silently skipped.
+
+  A second failure mode occurs with the concurrency queue: GitHub keeps at most one
+  *pending* run per group. If a third run starts while one is running and one is pending,
+  the older pending run is cancelled to queue the latest one — again silently.
+
+  Both behaviors are documented but frequently misunderstood when the same workflow
+  serves both CI (fast feedback) and CD (reliable delivery) purposes.
+fix: |
+  For deploy workflows, set `cancel-in-progress: false` and use a per-branch concurrency
+  group so only one deploy runs per branch at a time but no run is silently dropped.
+
+  If you need cancel-in-progress for PR CI, split your workflow into separate files:
+  one for CI (cancel-in-progress: true) and one for deploys (cancel-in-progress: false).
+fix_code:
+  - language: yaml
+    label: "Safe deploy workflow — never silently cancel"
+    code: |
+      name: Deploy
+      on:
+        push:
+          branches: [main]
+
+      concurrency:
+        # One deploy at a time per branch, but queue — never cancel
+        group: deploy-${{ github.ref }}
+        cancel-in-progress: false
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: ./scripts/deploy.sh
+  - language: yaml
+    label: "Split CI (cancel ok) vs Deploy (queue, no cancel) in one repo"
+    code: |
+      # .github/workflows/ci.yml — cancel stale PR checks is fine
+      name: CI
+      on: pull_request
+      concurrency:
+        group: ci-${{ github.ref }}
+        cancel-in-progress: true  # OK: PR checks, not deploys
+
+      # .github/workflows/deploy.yml — never drop a deploy
+      name: Deploy
+      on:
+        push:
+          branches: [main, 'release/**']
+      concurrency:
+        group: deploy-${{ github.ref }}
+        cancel-in-progress: false  # Queue; never skip a commit
+prevention:
+  - "Never use `cancel-in-progress: true` on workflows that deploy, apply infrastructure changes, or produce side effects that must run for every commit."
+  - "Monitor the Actions tab for unexpected CANCELLED runs — a CANCELLED deploy job is NOT the same as a skipped/passing check."
+  - "Use separate workflow files for CI and CD to apply different concurrency strategies."
+  - "Set the concurrency group key to include `github.ref` so branches don't cancel each other."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/using-concurrency"
+    label: "Using concurrency"
+  - url: "https://github.com/actions/runner/issues/3722"
+    label: "actions/runner#3722 — Concurrency cancellation behaviors"
+  - url: "https://github.com/orgs/community/discussions/5435"
+    label: "Community discussion: cancel-in-progress semantics"

package/errors/concurrency-timing/jobs-cancelled-unexpectedly.yml

@@ -1,60 +1,60 @@
-id: concurrency-timing-001
-title: "Jobs Cancelled Unexpectedly"
-category: concurrency-timing
-severity: warning
-tags:
-  - concurrency
-  - cancellation
-  - matrix
-  - timing
-  - branch-isolation
-patterns:
-  - regex: "Canceling since a higher priority waiting request for '.+' exists"
-    flags: "i"
-  - regex: "The workflow run was canceled because another workflow run with the same concurrency group was queued"
-    flags: "i"
-  - regex: "Operation was canceled\\."
-    flags: "i"
-error_messages:
-  - "Canceling since a higher priority waiting request for 'deploy' exists"
-  - "Operation was canceled."
-root_cause: |
-  Concurrency groups are global to the repository unless you scope them yourself. If every
-  branch uses the same group name, a push on one branch can cancel a run on a completely
-  different branch. Matrix jobs can make this harder to spot because only some legs appear to
-  vanish, even though the concurrency rule is what canceled them.
-
-  The workflow is behaving exactly as configured, but the group name is too broad.
-fix: |
-  Include branch or ref information in the concurrency group so only related runs cancel one
-  another. Keep `cancel-in-progress: true` only when you truly want a new run to replace the
-  older run for the same ref.
-fix_code:
-  - language: yaml
-    label: "Scope concurrency groups by workflow and ref"
-    code: |
-      concurrency:
-        group: ${{ github.workflow }}-${{ github.ref }}
-        cancel-in-progress: true
-
-      jobs:
-        test:
-          runs-on: ubuntu-latest
-          strategy:
-            matrix:
-              node: [18, 20]
-          steps:
-            - uses: actions/checkout@v4
-            - run: npm test
-prevention:
-  - "Never use a bare group like `deploy` or `ci` unless cross-branch cancellation is intentional."
-  - "Include `${{ github.ref }}` or `${{ github.head_ref || github.ref }}` in concurrency groups."
-  - "Review concurrency settings any time runs are mysteriously disappearing."
-docs:
-  - url: "https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/control-workflow-concurrency"
-    label: "Control the concurrency of workflows and jobs"
-  - 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: "Unexpected cancellations from concurrency"
+id: concurrency-timing-001
+title: "Jobs Cancelled Unexpectedly"
+category: concurrency-timing
+severity: warning
+tags:
+  - concurrency
+  - cancellation
+  - matrix
+  - timing
+  - branch-isolation
+patterns:
+  - regex: "Canceling since a higher priority waiting request for '.+' exists"
+    flags: "i"
+  - regex: "The workflow run was canceled because another workflow run with the same concurrency group was queued"
+    flags: "i"
+  - regex: "Operation was canceled\\."
+    flags: "i"
+error_messages:
+  - "Canceling since a higher priority waiting request for 'deploy' exists"
+  - "Operation was canceled."
+root_cause: |
+  Concurrency groups are global to the repository unless you scope them yourself. If every
+  branch uses the same group name, a push on one branch can cancel a run on a completely
+  different branch. Matrix jobs can make this harder to spot because only some legs appear to
+  vanish, even though the concurrency rule is what canceled them.
+
+  The workflow is behaving exactly as configured, but the group name is too broad.
+fix: |
+  Include branch or ref information in the concurrency group so only related runs cancel one
+  another. Keep `cancel-in-progress: true` only when you truly want a new run to replace the
+  older run for the same ref.
+fix_code:
+  - language: yaml
+    label: "Scope concurrency groups by workflow and ref"
+    code: |
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.ref }}
+        cancel-in-progress: true
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          strategy:
+            matrix:
+              node: [18, 20]
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm test
+prevention:
+  - "Never use a bare group like `deploy` or `ci` unless cross-branch cancellation is intentional."
+  - "Include `${{ github.ref }}` or `${{ github.head_ref || github.ref }}` in concurrency groups."
+  - "Review concurrency settings any time runs are mysteriously disappearing."
+docs:
+  - url: "https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/control-workflow-concurrency"
+    label: "Control the concurrency of workflows and jobs"
+  - 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: "Unexpected cancellations from concurrency"

package/errors/concurrency-timing/skipped-needs-cascade.yml

@@ -0,0 +1,103 @@
+id: concurrency-timing-004
+title: "Skipped needs Job Cascades Skip to All Dependent Jobs"
+category: concurrency-timing
+severity: silent-failure
+tags:
+  - needs
+  - skipped
+  - cascade
+  - conditionals
+  - job-status
+  - always
+  - dependency
+patterns:
+  - regex: "skipped.*needs.*skipped"
+    flags: "i"
+  - regex: "This job was skipped"
+    flags: "i"
+  - regex: "Result: skipped"
+    flags: "i"
+error_messages:
+  - "This job was skipped."
+  - "Skipping this job because a previous job in the chain was skipped."
+root_cause: |
+  When a job is **skipped** (because its `if:` condition evaluated to false), GitHub
+  Actions propagates the skip status to all jobs that `needs` it. Dependent jobs are
+  skipped automatically unless they explicitly handle this with `if: always()` or by
+  checking `needs.<id>.result == 'skipped'`.
+
+  This cascades silently: if `build` is skipped on non-main branches, then `test` (which
+  needs `build`) is also skipped, and `deploy` (which needs `test`) is also skipped —
+  even if `deploy` has no condition of its own and the developer expected it to run.
+
+  The cascade happens regardless of whether the dependency was skipped by an `if:` guard
+  or by the job being cancelled. The default behavior treats a skipped upstream job the
+  same as a failed one from the perspective of downstream jobs.
+fix: |
+  Use `if: always()` or explicit result checks (`needs.<id>.result == 'success' || needs.<id>.result == 'skipped'`)
+  on downstream jobs that should run regardless of whether an upstream job was skipped.
+fix_code:
+  - language: yaml
+    label: "WRONG — notification job silently skipped when build is skipped"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          if: github.ref == 'refs/heads/main'   # only runs on main
+          steps:
+            - run: npm run build
+
+        notify:
+          needs: build             # skipped when build is skipped (non-main branches)
+          runs-on: ubuntu-latest
+          steps:
+            - run: ./notify-slack.sh "Build complete"
+  - language: yaml
+    label: "CORRECT — notify even when build was skipped"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          if: github.ref == 'refs/heads/main'
+          steps:
+            - run: npm run build
+
+        notify:
+          needs: build
+          if: always()             # runs regardless of build's outcome or skip
+          runs-on: ubuntu-latest
+          steps:
+            - run: |
+                RESULT="${{ needs.build.result }}"
+                if [ "$RESULT" = "success" ]; then
+                  ./notify-slack.sh "Build succeeded"
+                elif [ "$RESULT" = "skipped" ]; then
+                  echo "Build was skipped (non-main branch) — no notification needed"
+                else
+                  ./notify-slack.sh "Build $RESULT"
+                fi
+  - language: yaml
+    label: "CORRECT — final job that always runs regardless of upstream"
+    code: |
+      jobs:
+        deploy:
+          needs: [build, test]
+          # Run if upstream succeeded OR if they were skipped (allows partial pipelines)
+          if: |
+            always() &&
+            (needs.build.result == 'success' || needs.build.result == 'skipped') &&
+            (needs.test.result == 'success' || needs.test.result == 'skipped')
+          runs-on: ubuntu-latest
+          steps:
+            - run: ./deploy.sh
+prevention:
+  - "Use `if: always()` on jobs that must run regardless of upstream outcomes (cleanup, notifications, summaries)."
+  - "Check `needs.<id>.result` explicitly when a job should behave differently based on upstream skip vs success vs failure."
+  - "Document which jobs in your pipeline are optional (skippable) vs required to avoid surprises."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idif"
+    label: "jobs.<job_id>.if"
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idneeds"
+    label: "jobs.<job_id>.needs"
+  - url: "https://docs.github.com/en/actions/learn-github-actions/expressions#status-check-functions"
+    label: "Status check functions (always, success, failure, cancelled)"

package/errors/concurrency-timing/workflow-run-conclusion-unchecked.yml

@@ -0,0 +1,100 @@
+id: concurrency-timing-003
+title: "workflow_run Downstream Job Ignores Source Workflow Conclusion"
+category: concurrency-timing
+severity: silent-failure
+tags:
+  - workflow_run
+  - conclusion
+  - downstream
+  - deploy
+  - conditional
+  - completed
+patterns:
+  - regex: "github\\.event\\.workflow_run\\.conclusion"
+    flags: "i"
+  - regex: "workflow_run.*completed.*always"
+    flags: "i"
+error_messages:
+  - "Warning: workflow_run downstream job ran despite source workflow failing."
+root_cause: |
+  The `workflow_run` trigger fires when a specified workflow completes, regardless of
+  whether that workflow **succeeded or failed**. The trigger type is `completed` — there
+  is no built-in `on_success` equivalent. If you do not check
+  `github.event.workflow_run.conclusion`, your downstream workflow runs even when the
+  upstream workflow failed, was cancelled, or was skipped.
+
+  This is a common mistake in CD pipelines where a deploy workflow is triggered by a CI
+  workflow run. Without a conclusion check, a failed test run triggers the deploy — which
+  may deploy broken code, send a notification for a non-event, or waste runner minutes.
+fix: |
+  Always add a job-level `if:` condition checking `github.event.workflow_run.conclusion == 'success'`
+  in any `workflow_run`-triggered workflow that should only run on success.
+fix_code:
+  - language: yaml
+    label: "WRONG — deploy runs regardless of CI conclusion"
+    code: |
+      on:
+        workflow_run:
+          workflows: ["CI"]
+          types: [completed]
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          # Missing conclusion check — deploys even when CI fails!
+          steps:
+            - run: ./deploy.sh
+  - language: yaml
+    label: "CORRECT — gate on success conclusion"
+    code: |
+      on:
+        workflow_run:
+          workflows: ["CI"]
+          types: [completed]
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          if: ${{ github.event.workflow_run.conclusion == 'success' }}
+          steps:
+            - run: ./deploy.sh
+
+        notify-failure:
+          runs-on: ubuntu-latest
+          if: ${{ github.event.workflow_run.conclusion == 'failure' }}
+          steps:
+            - run: ./notify-slack.sh "CI failed — no deploy"
+  - language: yaml
+    label: "CORRECT — handle all outcomes explicitly"
+    code: |
+      on:
+        workflow_run:
+          workflows: ["CI"]
+          types: [completed]
+
+      jobs:
+        gate:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Check conclusion
+              run: |
+                CONCLUSION="${{ github.event.workflow_run.conclusion }}"
+                echo "Source workflow concluded: $CONCLUSION"
+                if [ "$CONCLUSION" != "success" ]; then
+                  echo "::error::Upstream CI did not succeed (conclusion: $CONCLUSION) — aborting deploy"
+                  exit 1
+                fi
+
+        deploy:
+          needs: gate
+          runs-on: ubuntu-latest
+          steps:
+            - run: ./deploy.sh
+prevention:
+  - "Always add `if: github.event.workflow_run.conclusion == 'success'` to any job triggered by `workflow_run: completed`."
+  - "Consider adding a separate job for failure notifications to avoid silently swallowing upstream failures."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_run"
+    label: "workflow_run event — conclusion values"
+  - url: "https://docs.github.com/en/actions/writing-workflows/triggering-a-workflow#triggering-a-workflow-from-a-workflow"
+    label: "Triggering a workflow from a workflow"

package/errors/known-unsolved/composite-input-env-vars-missing.yml

@@ -0,0 +1,91 @@
+id: known-unsolved-003
+title: "Composite Actions Do Not Set INPUT_* Environment Variables"
+category: known-unsolved
+severity: limitation
+tags:
+  - composite-actions
+  - INPUT_
+  - env-vars
+  - shell-scripts
+  - action-migration
+patterns:
+  - regex: "\\$INPUT_[A-Z_]+"
+    flags: ""
+  - regex: "INPUT_[A-Z_]+:\\s*(unbound variable|empty|command not found)"
+    flags: "i"
+error_messages:
+  - "INPUT_MY_PARAM: unbound variable"
+  - "$INPUT_MY_PARAM: empty"
+root_cause: |
+  JavaScript actions and Docker container actions receive their inputs as `INPUT_*` environment
+  variables at runtime (e.g., the input `my-param` becomes `INPUT_MY-PARAM` or `INPUT_MY_PARAM`).
+  Composite actions do NOT follow this convention — they do not set any `INPUT_*` environment
+  variables on the runner.
+
+  Composite actions make inputs available ONLY through the `${{ inputs.name }}` expression context,
+  which is evaluated by the Actions runner before the shell command is invoked. Shell scripts
+  running inside composite `run:` steps cannot access inputs as `$INPUT_*` environment variables.
+
+  This limitation has been reported and discussed since 2020 (actions/runner#665, 66+ reactions).
+  GitHub has not implemented `INPUT_*` for composite actions. The likely reason is that composite
+  actions support multiple shells (bash, powershell, python) and the runner processes inputs as
+  templated expressions rather than environment variables for composites.
+
+  Developers who migrate a shell-script-based action from a JavaScript wrapper (where INPUT_*
+  was available via `core.getInput()` delegating to `process.env.INPUT_*`) to a composite action,
+  or who copy examples from Docker action documentation, will silently get empty values.
+fix: |
+  There is no way to make composite actions set INPUT_* env vars automatically. The workarounds are:
+
+  Option 1 — inline expression (simple, but creates expression injection risk with untrusted input):
+    `run: echo "${{ inputs.my-param }}"`
+
+  Option 2 — explicit env: mapping on the step (recommended — safe for untrusted input):
+    ```yaml
+    - name: Use input
+      env:
+        MY_PARAM: ${{ inputs.my-param }}
+      run: echo "$MY_PARAM"
+    ```
+
+  Option 3 — convert to a JavaScript action if INPUT_* pattern is deeply embedded in scripts.
+fix_code:
+  - language: yaml
+    label: "Map composite action inputs to env vars explicitly on each step"
+    code: |
+      # action.yml (composite action)
+      inputs:
+        deploy-env:
+          description: "Target environment name"
+          required: true
+        dry-run:
+          description: "Whether to perform a dry run"
+          required: false
+          default: "false"
+
+      runs:
+        using: composite
+        steps:
+          # ❌ WRONG — INPUT_DEPLOY_ENV and INPUT_DRY_RUN are not set in composite actions
+          # - run: ./scripts/deploy.sh "$INPUT_DEPLOY_ENV" "$INPUT_DRY_RUN"
+          #   shell: bash
+
+          # ✅ CORRECT — map to env vars in the step's env: block
+          - name: Deploy
+            env:
+              DEPLOY_ENV: ${{ inputs.deploy-env }}
+              DRY_RUN: ${{ inputs.dry-run }}
+            shell: bash
+            run: ./scripts/deploy.sh "$DEPLOY_ENV" "$DRY_RUN"
+prevention:
+  - "Never reference `INPUT_*` env vars in composite action shell scripts — they are not set."
+  - "When converting a JavaScript or Docker action to composite, audit all `INPUT_*` and `process.env.INPUT_*` references."
+  - "Use the `env:` block on each `run:` step to explicitly map inputs to environment variables."
+  - "For untrusted user inputs, always use the `env:` mapping pattern rather than inline `${{ inputs.name }}` in shell commands to prevent injection."
+docs:
+  - url: "https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions#runs-for-composite-actions"
+    label: "Metadata syntax — runs for composite actions"
+  - url: "https://docs.github.com/en/actions/creating-actions/creating-a-composite-action"
+    label: "Creating a composite action"
+  - url: "https://github.com/actions/runner/issues/665"
+    label: "actions/runner#665 — INPUT_* env vars missing in composite actions (open since 2020, 66+ reactions)"

package/errors/known-unsolved/composite-nested-outputs-null.yml

@@ -0,0 +1,101 @@
+id: known-unsolved-004
+title: "Composite Action Nested Step Outputs Evaluate to null in Calling Workflow"
+category: known-unsolved
+severity: limitation
+tags:
+  - composite-actions
+  - nested-actions
+  - step-outputs
+  - actions-runner
+  - known-bug
+patterns:
+  - regex: "##\\[debug\\]Evaluating: steps\\.[^.]+\\.outputs\\.[^\\s]+"
+    flags: "i"
+  - regex: "##\\[debug\\]=> null"
+    flags: "i"
+  - regex: "value: '' is not"
+    flags: "i"
+error_messages:
+  - "##[debug]Evaluating: steps.setter.outputs.some-val"
+  - "##[debug]=> null"
+  - "Error: value: '' is not 'expected-value'"
+root_cause: |
+  When a composite action is nested inside another composite action (A calls B, and B
+  exposes step outputs), the runner loses the `steps` context for the inner composite.
+  References like `steps.<id>.outputs.<name>` inside the nested composite evaluate to
+  `null`, and the outer composite (or the calling workflow) receives an empty string
+  instead of the intended output value.
+
+  The root cause is a context-wiring bug in the Actions runner (documented in
+  actions/runner#2009): the runner does not correctly register and propagate the
+  `steps` context for nested composite actions, particularly in post-steps. Each
+  composite "layer" should maintain its own steps context, but in practice the context
+  from the outer layer bleeds through or is lost entirely.
+
+  A related issue (actions/runner#2030) describes nested composite post-steps inheriting
+  the wrong context from the parent action.
+
+  **This is a known runner limitation.** There is no clean fix — only workarounds.
+  The runner team is aware; check the issue threads for status on any official fix.
+fix: |
+  There is no direct fix. Use one of these workarounds depending on your situation:
+
+  **Workaround 1 — Flatten nested composites**: Avoid nesting composite actions when
+  step outputs must propagate. Move the logic into a single top-level composite that
+  exposes outputs directly to the calling workflow.
+
+  **Workaround 2 — Use a published remote action**: Reference the inner composite as a
+  published action (`uses: owner/repo@ref`) rather than a local nested reference. Some
+  reporters find the context bug is avoided when the inner action runs in its own
+  repository context.
+
+  **Workaround 3 — Pass values via environment files**: Instead of `steps.*.outputs.*`,
+  write values to `$GITHUB_ENV` or `$GITHUB_OUTPUT` at the top-level composite step and
+  read them from there. This sidesteps the `steps` context lookup entirely.
+
+  **Workaround 4 — Use a JavaScript/Docker action**: If output propagation is critical,
+  rewrite the inner composite as a JavaScript or container action, which has correct
+  lifecycle and output semantics.
+fix_code:
+  - language: yaml
+    label: "Flatten: expose output directly from top-level composite"
+    code: |
+      # action.yml (top-level composite — do NOT nest another composite inside)
+      name: My Action
+      outputs:
+        result:
+          description: "The computed result"
+          value: ${{ steps.compute.outputs.result }}
+      runs:
+        using: composite
+        steps:
+          - id: compute
+            shell: bash
+            run: echo "result=hello-world" >> $GITHUB_OUTPUT
+  - language: yaml
+    label: "Workaround: write to GITHUB_OUTPUT from inner step directly"
+    code: |
+      # Instead of relying on steps.*.outputs.* in a nested composite,
+      # write directly to the top-level $GITHUB_OUTPUT from within the step:
+      runs:
+        using: composite
+        steps:
+          - shell: bash
+            run: |
+              COMPUTED=$(./scripts/compute.sh)
+              # Write directly to top-level output file
+              echo "result=${COMPUTED}" >> $GITHUB_OUTPUT
+prevention:
+  - "Avoid nesting composite actions more than one level deep when step outputs must propagate."
+  - "Test output propagation explicitly (assert the output equals the expected value) before relying on it in production workflows."
+  - "Prefer JavaScript actions over composite actions when reliable output propagation is critical."
+  - "Track actions/runner#2009 for an official fix — the limitation may be resolved in a future runner version."
+docs:
+  - url: "https://github.com/actions/runner/issues/2009"
+    label: "actions/runner#2009 — Composite: Step Outputs not available in nested composite actions"
+  - url: "https://github.com/actions/runner/issues/2030"
+    label: "actions/runner#2030 — Composite: Nested actions post steps have wrong context"
+  - url: "https://github.com/actions/runner/issues/646"
+    label: "actions/runner#646 — Composite action feature limitations"
+  - url: "https://docs.github.com/en/actions/sharing-automations/creating-actions/creating-a-composite-action"
+    label: "Creating a composite action"