@htekdev/actions-debugger 1.0.1 → 1.0.2

package/errors/known-unsolved/workflow-rerun-limit.yml

@@ -0,0 +1,101 @@
+id: known-unsolved-007
+title: "Workflow Rerun Limit: 50 Reruns Maximum Per Workflow Run"
+category: known-unsolved
+severity: limitation
+tags:
+  - rerun
+  - retry
+  - automation
+  - limits
+  - check-suite
+patterns:
+  - regex: "exceeded.*maximum.*rerun.*limit"
+    flags: "i"
+  - regex: "rerun limit.*50"
+    flags: "i"
+  - regex: "This workflow has been rerun too many times"
+    flags: "i"
+  - regex: "maximum rerun limit.*exceeded"
+    flags: "i"
+error_messages:
+  - "This workflow has exceeded the maximum rerun limit of 50."
+  - "You have exceeded the maximum rerun limit for this workflow run."
+  - "Failed check suite: exceeded maximum rerun limit."
+root_cause: |
+  In April 2026 GitHub introduced a hard cap of 50 reruns per workflow run (combining
+  full re-runs and partial job re-runs). When the limit is hit, any subsequent rerun
+  attempt results in a failed check suite with an annotation — no partial or full rerun
+  is permitted on that run ever again.
+
+  The limit was introduced because some automation scripts were issuing hundreds of retry
+  attempts on a single workflow run, adding significant load to GitHub's infrastructure.
+
+  Common triggers of this limit:
+  - Automated retry bots (e.g. flaky-test detection scripts) that loop on `gh run rerun`
+  - CI platforms that aggressively requeue failed runs
+  - Scheduled maintenance pipelines that retry indefinitely on runner-level transient failures
+  - GitHub Apps polling and re-triggering stale check suites on long-lived PRs
+fix: |
+  There is no way to raise the 50-rerun cap — it is a hard platform limit with no bypass.
+
+  Recommended approaches:
+  1. **Fix the root cause instead of retrying** — identify and address flaky tests, network
+     timeouts, or runner instability rather than masking them with reruns.
+  2. **Create a new workflow run instead of rerunning** — close and reopen the PR, push a
+     no-op commit, or trigger `workflow_dispatch` to start a fresh run with its own 50-run
+     budget.
+  3. **Implement retry logic inside the step** — use a step-level retry loop (`for i in 1 2 3`)
+     rather than whole-workflow reruns so flakiness is contained within a single run.
+  4. **Limit automation rerun budgets** — if you operate a retry bot, add a counter check
+     (`gh run view --json runAttempt`) and stop retrying once `runAttempt >= 40` to leave
+     headroom before the limit hits.
+fix_code:
+  - language: yaml
+    label: "Step-level retry instead of whole-workflow rerun"
+    code: |
+      steps:
+        - name: Run flaky integration test (with built-in retry)
+          shell: bash
+          run: |
+            for attempt in 1 2 3; do
+              echo "Attempt $attempt of 3"
+              if npm run test:integration; then
+                echo "Tests passed on attempt $attempt"
+                exit 0
+              fi
+              echo "Attempt $attempt failed, retrying..."
+              sleep 10
+            done
+            echo "All 3 attempts failed"
+            exit 1
+  - language: yaml
+    label: "Check rerun count before auto-retrying in a workflow automation"
+    code: |
+      steps:
+        - name: Guard against rerun limit
+          shell: bash
+          run: |
+            RUN_ATTEMPT="${{ github.run_attempt }}"
+            if [ "$RUN_ATTEMPT" -ge 40 ]; then
+              echo "::error::Run attempt $RUN_ATTEMPT is near the 50-rerun limit. Stopping auto-retry."
+              exit 1
+            fi
+            echo "Run attempt $RUN_ATTEMPT — within safe retry budget"
+  - language: yaml
+    label: "Trigger a fresh run instead of rerunning (workflow_dispatch)"
+    code: |
+      # Instead of gh run rerun <run-id>, dispatch a fresh run:
+      # gh workflow run my-workflow.yml --ref main
+      # This creates a new run ID with its own 50-rerun budget.
+prevention:
+  - "Build retry logic inside steps using shell loops rather than whole-workflow reruns."
+  - "Monitor `github.run_attempt` context value; alert or stop automation at 40+ attempts."
+  - "Fix flaky tests rather than relying on reruns as the primary reliability mechanism."
+  - "If a run regularly hits >10 reruns, treat it as a reliability incident, not a normal CI pattern."
+docs:
+  - url: "https://github.blog/changelog/2026-04-10-actions-workflows-are-limited-to-50-reruns/"
+    label: "GitHub Changelog: Actions workflows are limited to 50 reruns"
+  - url: "https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/re-running-workflows-and-jobs"
+    label: "Re-running workflows and jobs"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions"
+    label: "Workflow commands for GitHub Actions"

package/errors/permissions-auth/gcp-oidc-workload-identity-misconfigured.yml

@@ -0,0 +1,130 @@
+id: permissions-auth-008
+title: "GCP OIDC Workload Identity: Pool Path vs Provider Path / Project ID vs Number"
+category: permissions-auth
+severity: error
+tags:
+  - oidc
+  - gcp
+  - google-cloud
+  - workload-identity
+  - auth
+patterns:
+  - regex: "Invalid value for [\"']?audience[\"']?"
+    flags: "i"
+  - regex: "Error code invalid_request.*Invalid value for.*audience"
+    flags: "i"
+  - regex: "workloadIdentityPools.*not.*providers"
+    flags: "i"
+  - regex: "project.*number.*not.*project.*id"
+    flags: "i"
+  - regex: "OAuthError.*Invalid value for.*audience"
+    flags: "i"
+  - regex: "Error parsing credentials.*workload_identity_provider"
+    flags: "i"
+error_messages:
+  - "ERROR: gcloud crashed (OAuthError): Error code invalid_request: Invalid value for \"audience\"."
+  - "Error: google-github-actions/auth failed with: Error code invalid_request: Invalid value for \"audience\"."
+  - "The workload_identity_provider must be the full provider resource name, not the pool resource name."
+root_cause: |
+  `google-github-actions/auth` OIDC authentication fails with "Invalid value for audience"
+  when either of two common misconfiguration patterns is present:
+
+  **Mistake 1 — Pool path instead of Provider path**
+  The `workload_identity_provider` input requires the full *Provider* resource name:
+    `projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID`
+
+  Many developers mistakenly supply only the *Pool* path (omitting `/providers/PROVIDER_ID`):
+    `projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID`
+
+  GCP's STS token endpoint rejects the audience because it expects the provider URI, not the pool URI.
+
+  **Mistake 2 — Project ID (string) instead of Project Number (integer)**
+  The path requires the numeric GCP project number (e.g. `123456789012`), NOT the human-readable
+  project ID (e.g. `my-gcp-project`). Workload Identity Federation does not accept project IDs.
+  Using a project ID causes the STS endpoint to return "Invalid value for audience" because the
+  resource path does not resolve to a valid identity provider.
+
+  **Mistake 3 — Missing `id-token: write` permission**
+  If `permissions.id-token` is not explicitly set to `write` at the job or workflow level,
+  GitHub will not mint an OIDC token and the auth step fails with a permissions error rather
+  than a token exchange error.
+fix: |
+  Verify the `workload_identity_provider` value against the exact format required:
+    `projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL/providers/PROVIDER`
+
+  Retrieve the correct value:
+    gcloud iam workload-identity-pools providers describe PROVIDER_ID \
+      --project=PROJECT_ID \
+      --location=global \
+      --workload-identity-pool=POOL_ID \
+      --format='value(name)'
+
+  Ensure `id-token: write` is set in the job permissions block.
+
+  Wait at least 5 minutes after changes to Workload Identity Pool / Provider / IAM bindings
+  before testing — these resources are eventually consistent.
+fix_code:
+  - language: yaml
+    label: "Correct workload_identity_provider format (provider path + project number)"
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          permissions:
+            id-token: write    # REQUIRED — grants GitHub the right to mint an OIDC token
+            contents: read
+
+          steps:
+            - uses: actions/checkout@v4
+
+            - id: auth
+              uses: google-github-actions/auth@v2
+              with:
+                # CORRECT: full provider path with numeric project number
+                workload_identity_provider: >-
+                  projects/123456789012/locations/global/workloadIdentityPools/my-pool/providers/my-provider
+                service_account: my-service-account@my-project.iam.gserviceaccount.com
+  - language: yaml
+    label: "Common mistake — pool path (missing /providers/...) causes audience error"
+    code: |
+      # WRONG: pool path only — gcloud crashes with "Invalid value for audience"
+      # workload_identity_provider: >-
+      #   projects/123456789012/locations/global/workloadIdentityPools/my-pool
+
+      # ALSO WRONG: project ID string instead of project number
+      # workload_identity_provider: >-
+      #   projects/my-gcp-project/locations/global/workloadIdentityPools/my-pool/providers/my-provider
+
+      # CORRECT:
+      # workload_identity_provider: >-
+      #   projects/123456789012/locations/global/workloadIdentityPools/my-pool/providers/my-provider
+  - language: yaml
+    label: "Store provider path in a repository variable to avoid typos"
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          permissions:
+            id-token: write
+            contents: read
+          steps:
+            - uses: google-github-actions/auth@v2
+              with:
+                # Store full provider path as a repository variable to avoid typos
+                workload_identity_provider: ${{ vars.GCP_WIF_PROVIDER }}
+                service_account: ${{ vars.GCP_SERVICE_ACCOUNT }}
+prevention:
+  - "Always use `gcloud iam workload-identity-pools providers describe` to copy the exact provider path."
+  - "Store the full provider path in a GitHub Actions variable (`vars.GCP_WIF_PROVIDER`) to prevent manual typos."
+  - "Use numeric project number — retrieve it with `gcloud projects describe PROJECT_ID --format='value(projectNumber)'`."
+  - "After changing Workload Identity Pool config, wait 5 minutes before testing (eventual consistency)."
+  - "Confirm `id-token: write` permission is present at job (not just workflow) level."
+docs:
+  - url: "https://github.com/google-github-actions/auth#setup"
+    label: "google-github-actions/auth: Setup and configuration"
+  - url: "https://github.com/google-github-actions/auth/blob/main/docs/TROUBLESHOOTING.md"
+    label: "google-github-actions/auth: Troubleshooting guide"
+  - url: "https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/configuring-openid-connect-in-google-cloud-platform"
+    label: "Configuring OIDC in Google Cloud Platform"
+  - url: "https://cloud.google.com/iam/docs/workload-identity-federation-with-deployment-pipelines"
+    label: "GCP: Workload Identity Federation with deployment pipelines"

package/errors/runner-environment/node20-to-node24-migration.yml

@@ -0,0 +1,118 @@
+id: runner-environment-016
+title: "Node 20 → Node 24 Forced Migration Breaks Actions and macOS 13 Runners"
+category: runner-environment
+severity: error
+tags:
+  - node
+  - node24
+  - deprecation
+  - macos
+  - arm32
+  - runtime-migration
+patterns:
+  - regex: "Node\\.?20 actions are deprecated"
+    flags: "i"
+  - regex: "Please update the following actions to use Node\\.?24"
+    flags: "i"
+  - regex: "node20 is deprecated"
+    flags: "i"
+  - regex: "macOS 13.*not supported.*Node 24"
+    flags: "i"
+  - regex: "ARM32.*no longer supported"
+    flags: "i"
+error_messages:
+  - "Node.js 20 actions are deprecated. Please update the following actions to use Node.js 24."
+  - "node20 is deprecated and will be disabled in a future runner release."
+  - "Error: This action requires Node.js 24 or higher. Current version: 20."
+root_cause: |
+  GitHub announced deprecation of Node 20 on Actions runners on September 19, 2025
+  (editor updated May 19, 2026: migration date confirmed June 16, 2026). Starting
+  June 16, 2026, all GitHub-hosted runners default to Node 24.
+
+  Three distinct breakage scenarios exist:
+
+  1. **Marketplace actions using `runs.using: 'node20'`** — any third-party or custom
+     action that declares `runs.using: node20` in its `action.yml` will emit deprecation
+     warnings and eventually fail when GitHub removes Node 20 from runners later in 2026.
+
+  2. **macOS 13 (and older) runners are incompatible with Node 24** — Node 24 dropped
+     support for macOS 13.4 and lower. Workflows specifying `runs-on: macos-13` (or older
+     images) fail at the runner startup phase or produce unexpected errors from the
+     Node-based runner bootstrapper.
+
+  3. **ARM32 self-hosted runners** — Node 24 has no official ARM32 support. Self-hosted
+     runners on ARM32 hardware silently lose the ability to execute Node-based actions
+     after the Node 20 removal milestone.
+fix: |
+  **For action authors:** Update `action.yml` to declare `runs.using: 'node24'` and
+  test locally with Node 24. Publish a new release so downstream consumers pick it up.
+
+  **For workflow authors:**
+  - Upgrade all `uses:` pins to the latest major version that ships with Node 24 support
+    (e.g. `actions/checkout@v4 → @v4` already Node-24-ready; `actions/setup-node@v4`
+    already Node-24-ready).
+  - Replace `runs-on: macos-13` with `runs-on: macos-latest` or `macos-14+`.
+  - For ARM32 self-hosted runners: migrate to ARM64 hardware or use container-based
+    execution that bundles its own Node runtime.
+
+  **Temporary escape hatch (not for production long-term):**
+  Set `ACTIONS_ALLOW_USE_UNSECURE_NODE_VERSION=true` in the workflow `env` block to
+  continue using Node 20 until GitHub removes it from runners later in 2026.
+fix_code:
+  - language: yaml
+    label: "Upgrade pinned action versions to Node 24-compatible releases"
+    code: |
+      steps:
+        # Pin to latest major — all official actions already ship Node 24 builds
+        - uses: actions/checkout@v4
+        - uses: actions/setup-node@v4
+          with:
+            node-version: '20'
+        - uses: actions/upload-artifact@v4
+          with:
+            name: dist
+            path: dist/
+  - language: yaml
+    label: "Migrate macOS runner from macos-13 to macos-latest"
+    code: |
+      jobs:
+        build:
+          # macos-13 is incompatible with Node 24 — use macos-latest (14+)
+          runs-on: macos-latest
+          steps:
+            - uses: actions/checkout@v4
+  - language: yaml
+    label: "Temporary escape hatch — keep Node 20 until explicit removal"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          env:
+            # WARNING: temporary only — Node 20 will be fully removed later in 2026
+            ACTIONS_ALLOW_USE_UNSECURE_NODE_VERSION: 'true'
+          steps:
+            - uses: actions/checkout@v4
+  - language: yaml
+    label: "Test Node 24 compatibility before the mandatory cutover"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          env:
+            # Force Node 24 to test compatibility ahead of the June 16 cutover
+            FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: 'true'
+          steps:
+            - uses: actions/checkout@v4
+prevention:
+  - "Subscribe to GitHub changelog https://github.blog/changelog/label/actions/ for deprecation notices."
+  - "Run `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24=true` in CI to catch Node 24 incompatibilities early."
+  - "Avoid pinning to old major versions of `actions/*` — use floating major tags (e.g. @v4)."
+  - "Audit custom/internal actions for `runs.using: node20` declarations before the June 16, 2026 migration date."
+  - "Migrate macOS CI to macos-14 or macos-latest to ensure Node 24 compatibility."
+docs:
+  - url: "https://github.blog/changelog/2025-09-19-deprecation-of-node-20-on-github-actions-runners/"
+    label: "GitHub Changelog: Deprecation of Node 20 on GitHub Actions runners"
+  - url: "https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions#runs-for-javascript-actions"
+    label: "Metadata syntax: runs.using for JavaScript actions"
+  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources"
+    label: "Supported runners and hardware resources"

package/errors/silent-failures/sparse-checkout-sticky-cone-mode.yml

@@ -0,0 +1,120 @@
+id: silent-failures-008
+title: "Sparse Checkout Persists to Subsequent Checkout Steps (Sticky Cone Mode)"
+category: silent-failures
+severity: silent-failure
+tags:
+  - checkout
+  - sparse-checkout
+  - cone-mode
+  - composite-actions
+  - file-missing
+patterns:
+  - regex: "sparse.*checkout.*persist"
+    flags: "i"
+  - regex: "core\\.sparseCheckout.*true"
+    flags: "i"
+  - regex: "sparse-checkout.*not disabled"
+    flags: "i"
+error_messages:
+  - "Run actions/checkout@v4"
+  - "Expected full checkout but only sparse tree present"
+root_cause: |
+  When `actions/checkout` is called with `sparse-checkout:` options, it sets the git
+  repository's `core.sparseCheckout = true` config. A subsequent call to `actions/checkout`
+  in the same job — even WITHOUT specifying sparse-checkout — re-uses the existing git
+  repository and inherits the sticky `core.sparseCheckout = true` setting.
+
+  Result: the second checkout appears to succeed (no error), but the working directory
+  still contains only the sparse subset from the first checkout. Files outside the
+  original sparse pattern are silently absent.
+
+  This most commonly occurs in two scenarios:
+  1. A workflow calls `actions/checkout` with sparse-checkout for a fast initial clone,
+     then calls `actions/checkout` again (different ref, different path spec) expecting
+     a full checkout.
+  2. A workflow uses sparse-checkout, then calls a composite action that internally runs
+     its own `actions/checkout`. The composite action's checkout inherits the sparse
+     setting from the parent workflow's checkout.
+
+  Root cause: a bug in `actions/checkout` — the `disableSparseCheckout()` method does not
+  explicitly set `core.sparseCheckout false` when `sparse-checkout` input is absent. A
+  fix PR (#2034) exists in the repo but has not been merged as of 2026.
+fix: |
+  **Option 1 (recommended): Explicitly reset sparse-checkout between checkouts**
+  Add a `git sparse-checkout disable` step between the sparse and full checkouts. This
+  clears the sticky `core.sparseCheckout` flag and ensures subsequent checkouts are full.
+
+  **Option 2: Use separate `path:` directories**
+  Checkout into a unique subdirectory with the `path:` input to prevent git config
+  sharing. Each `path:` gets its own `.git` config.
+
+  **Option 3: Use `sparse-checkout-cone-mode: false` carefully**
+  When in non-cone mode, review that patterns don't accidentally match more or fewer
+  files than expected. Non-cone mode with incorrect patterns is its own source of
+  silent failures.
+fix_code:
+  - language: yaml
+    label: "Reset sparse-checkout before a subsequent full checkout"
+    code: |
+      steps:
+        # First checkout: sparse (fast clone for config files only)
+        - uses: actions/checkout@v4
+          with:
+            sparse-checkout: |
+              .github
+              config/
+
+        - name: Reset sparse-checkout so next checkout is full
+          shell: bash
+          run: git sparse-checkout disable
+
+        # Second checkout (in composite action or next step): now gets full tree
+        - uses: actions/checkout@v4
+          with:
+            ref: ${{ github.sha }}
+  - language: yaml
+    label: "Use separate path: directories to avoid shared git config"
+    code: |
+      steps:
+        # Sparse checkout into 'config-only/' subdirectory
+        - uses: actions/checkout@v4
+          with:
+            path: config-only
+            sparse-checkout: |
+              config/
+
+        # Full checkout into 'full-repo/' — completely separate git repo config
+        - uses: actions/checkout@v4
+          with:
+            path: full-repo
+  - language: yaml
+    label: "Composite action defensive reset (add to composite action's beginning)"
+    code: |
+      # In your composite action's action.yml — reset sparse before own checkout
+      runs:
+        using: composite
+        steps:
+          - name: Reset any inherited sparse-checkout
+            shell: bash
+            run: |
+              if git rev-parse --git-dir > /dev/null 2>&1; then
+                git sparse-checkout disable 2>/dev/null || true
+              fi
+
+          - uses: actions/checkout@v4
+            with:
+              ref: ${{ inputs.ref }}
+prevention:
+  - "Never assume a subsequent `actions/checkout` step gets a full tree if any earlier step used sparse-checkout."
+  - "Add `git sparse-checkout disable` as an explicit step between sparse and full checkouts in the same job."
+  - "When writing composite actions that call `actions/checkout`, add a defensive `git sparse-checkout disable` before your checkout step."
+  - "Use the `path:` input to isolate checkouts that need different content into separate directories."
+docs:
+  - url: "https://github.com/actions/checkout/issues/1498"
+    label: "actions/checkout#1498: Sparse checkout persists in composite action"
+  - url: "https://github.com/actions/checkout/pull/2034"
+    label: "actions/checkout#2034: Fix — disable sparse-checkout on subsequent checkout (open PR)"
+  - url: "https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsuses"
+    label: "Workflow syntax: steps.uses"
+  - url: "https://github.com/actions/checkout#usage"
+    label: "actions/checkout: Usage and sparse-checkout options"

package/errors/yaml-syntax/reusable-workflow-missing-output-declaration.yml

@@ -0,0 +1,140 @@
+id: yaml-syntax-013
+title: "Reusable Workflow Output Missing on.workflow_call.outputs Declaration"
+category: yaml-syntax
+severity: silent-failure
+tags:
+  - reusable-workflow
+  - workflow-call
+  - outputs
+  - silent-failure
+  - job-outputs
+patterns:
+  - regex: "needs\\.[a-zA-Z0-9_-]+\\.outputs\\.[a-zA-Z0-9_-]+"
+    flags: "i"
+  - regex: "on\\.workflow_call\\.outputs.*not defined"
+    flags: "i"
+  - regex: "output.*reusable.*workflow.*empty"
+    flags: "i"
+error_messages:
+  - "The output variable was not found in the called workflow's on.workflow_call.outputs map."
+  - "Output 'version' not found in called workflow."
+root_cause: |
+  A called (reusable) workflow exposes job-level outputs but forgets to declare them at
+  the `workflow_call` trigger level. As a result the caller workflow's
+  `needs.<called-job>.outputs.<name>` expression evaluates to an empty string with NO
+  error message — a silent failure.
+
+  GitHub Actions requires a two-layer output declaration for reusable workflows:
+  1. The job inside the called workflow declares step outputs via `outputs:` on the job.
+  2. The called workflow's `on.workflow_call.outputs:` section explicitly maps workflow-
+     level output names to job-level output expressions.
+
+  If layer 2 is missing, the caller never receives the value even though layer 1 exists.
+  Because the expression resolves to an empty string (not an error), downstream steps may
+  silently receive wrong values — version tags become empty strings, Docker image names
+  become malformed, deploy environment names become blank.
+
+  A second variant occurs when accessing outputs from a called workflow that uses a matrix:
+  matrix job outputs cannot be aggregated automatically at the workflow level, so outputs
+  from individual matrix legs are inaccessible to the caller.
+fix: |
+  Add the `on.workflow_call.outputs:` section to the called workflow, mapping each
+  desired output name to the corresponding job output expression.
+
+  For matrix jobs: aggregate outputs into a single job (e.g. using `toJSON`) or use a
+  final non-matrix aggregator job inside the called workflow that reads matrix outputs
+  and re-exposes them as a single value.
+fix_code:
+  - language: yaml
+    label: "Called workflow — correct two-layer output declaration"
+    code: |
+      # .github/workflows/build-and-version.yml (CALLED workflow)
+      on:
+        workflow_call:
+          # Layer 2: workflow-level outputs (REQUIRED for caller to receive values)
+          outputs:
+            version:
+              description: "The computed version string"
+              value: ${{ jobs.build.outputs.version }}
+            artifact-name:
+              description: "Name of the uploaded artifact"
+              value: ${{ jobs.build.outputs.artifact-name }}
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          # Layer 1: job-level outputs
+          outputs:
+            version: ${{ steps.compute-version.outputs.version }}
+            artifact-name: ${{ steps.upload.outputs.artifact-name }}
+          steps:
+            - id: compute-version
+              run: echo "version=1.2.3-${{ github.sha }}" >> $GITHUB_OUTPUT
+
+            - id: upload
+              uses: actions/upload-artifact@v4
+              with:
+                name: build-output
+                path: dist/
+  - language: yaml
+    label: "Caller workflow — consuming outputs from called workflow"
+    code: |
+      # .github/workflows/deploy.yml (CALLER workflow)
+      jobs:
+        build:
+          uses: ./.github/workflows/build-and-version.yml
+          secrets: inherit
+
+        deploy:
+          needs: build
+          runs-on: ubuntu-latest
+          steps:
+            - name: Deploy version
+              # This only works if the called workflow has on.workflow_call.outputs declared
+              run: |
+                echo "Deploying version: ${{ needs.build.outputs.version }}"
+                echo "Using artifact: ${{ needs.build.outputs.artifact-name }}"
+  - language: yaml
+    label: "Aggregate matrix outputs in a final job for caller consumption"
+    code: |
+      # Called workflow with matrix — aggregate results before exposing as outputs
+      on:
+        workflow_call:
+          outputs:
+            all-results:
+              value: ${{ jobs.aggregate.outputs.results }}
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          strategy:
+            matrix:
+              suite: [unit, integration, e2e]
+          outputs:
+            result-${{ matrix.suite }}: ${{ steps.run.outputs.result }}
+          steps:
+            - id: run
+              run: echo "result=passed" >> $GITHUB_OUTPUT
+
+        # Aggregator job: collects matrix outputs and re-exposes as single value
+        aggregate:
+          needs: test
+          runs-on: ubuntu-latest
+          outputs:
+            results: ${{ steps.collect.outputs.results }}
+          steps:
+            - id: collect
+              run: |
+                echo "results=${{ toJSON(needs.test.outputs) }}" >> $GITHUB_OUTPUT
+prevention:
+  - "Always declare `on.workflow_call.outputs:` in a reusable workflow if any caller needs its outputs."
+  - "Test output propagation by printing `${{ needs.<job>.outputs.<name> }}` in a debug step on the caller side."
+  - "Treat empty string outputs from called workflows as a sign of missing `on.workflow_call.outputs:` mapping."
+  - "Matrix jobs inside called workflows require an aggregator job — matrix outputs cannot be directly mapped."
+docs:
+  - url: "https://docs.github.com/en/actions/sharing-automations/reusing-workflows#using-outputs-from-a-reusable-workflow"
+    label: "Reusable workflows: using outputs"
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#onworkflow_calloutputs"
+    label: "Workflow syntax: on.workflow_call.outputs"
+  - url: "https://stackoverflow.com/questions/73702333/github-actions-reuse-outputs-from-other-reusable-workflows"
+    label: "Stack Overflow: Reuse outputs from reusable workflows (82 upvotes)"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@htekdev/actions-debugger",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "65+ real GitHub Actions errors, queryable by agents. MCP server + Copilot skills + error database.",
   "type": "module",
   "main": "./dist/index.js",