@htekdev/actions-debugger 1.0.2 → 1.0.4

package/errors/caching-artifacts/artifact-download-no-artifacts-found.yml

@@ -0,0 +1,118 @@
+id: caching-artifacts-010
+title: "Artifact Download Fails — Unable to Find Any Artifacts for Run"
+category: caching-artifacts
+severity: error
+tags:
+  - artifact
+  - download
+  - run-id
+  - cross-workflow
+  - upload-artifact
+  - download-artifact
+patterns:
+  - regex: "Unable to find any artifacts for the associated workflow"
+    flags: "i"
+  - regex: "No artifacts found for run"
+    flags: "i"
+  - regex: "Error: Unable to find any artifacts"
+    flags: "i"
+error_messages:
+  - "Unable to find any artifacts for the associated workflow"
+  - "Error: Unable to find any artifacts for the associated workflow"
+  - "No artifacts were found with the provided name and filters."
+root_cause: |
+  GitHub Actions artifacts are scoped to a specific workflow run. The
+  `actions/download-artifact@v4` action (and v3 with `run-id:`) will fail with
+  "Unable to find any artifacts" when:
+
+  1. **Wrong or stale run-id** — The run ID is hard-coded or fetched from a
+     prior run that no longer has the expected artifact (artifacts expire after
+     the configured retention period, default 90 days).
+
+  2. **Upload step never ran** — The producing workflow job was cancelled, the
+     upload step was skipped due to a failed prior step, or the `if:` condition
+     on the upload step evaluated to false.
+
+  3. **Name mismatch** — The `name:` specified in `download-artifact` doesn't
+     exactly match the name used in `upload-artifact` (case-sensitive).
+
+  4. **Cross-workflow download without explicit run-id** — In v4, downloading
+     artifacts from a different workflow run requires an explicit `run-id:`.
+     Omitting it defaults to the current run, which may not have those artifacts.
+
+  Documented in GitHub Community discussion #109905.
+fix: |
+  For cross-workflow artifact sharing:
+  1. Capture the producing workflow's run-id dynamically using the GitHub REST
+     API or by passing it as a workflow_dispatch input or repository_dispatch payload.
+  2. Verify the upload step ran successfully in the producer workflow before
+     downloading in a consumer workflow.
+  3. Ensure `name:` matches exactly (case-sensitive) between upload and download.
+  4. For same-workflow jobs, omit `run-id:` — download-artifact v4 defaults to
+     the current run automatically.
+fix_code:
+  - language: yaml
+    label: "WRONG — hard-coded run-id that may be stale"
+    code: |
+      - uses: actions/download-artifact@v4
+        with:
+          name: build-output
+          run-id: 12345678  # ❌ hard-coded run ID — stale if re-run or wrong workflow
+  - language: yaml
+    label: "RIGHT — same-workflow, no run-id needed"
+    code: |
+      # Job A (producer)
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - run: make build
+            - uses: actions/upload-artifact@v4
+              with:
+                name: build-output       # ✅ exact name matters
+                path: dist/
+
+        test:
+          needs: build
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/download-artifact@v4
+              with:
+                name: build-output       # ✅ same name, no run-id needed for current run
+  - language: yaml
+    label: "RIGHT — cross-workflow download, run-id from API"
+    code: |
+      - name: Get latest successful run ID
+        id: get-run
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          RUN_ID=$(gh run list \
+            --workflow=build.yml \
+            --branch=main \
+            --status=success \
+            --limit=1 \
+            --json databaseId \
+            --jq '.[0].databaseId')
+          echo "run_id=$RUN_ID" >> $GITHUB_OUTPUT
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: build-output
+          run-id: ${{ steps.get-run.outputs.run_id }}  # ✅ dynamic run ID
+          github-token: ${{ github.token }}
+prevention:
+  - "Never hard-code run-id values — always fetch them dynamically via the GitHub API or pass them as workflow inputs."
+  - "Always verify artifact upload completed successfully before writing a consuming workflow that depends on it."
+  - "Use exact case-matching artifact names — `build-output` and `Build-Output` are different artifacts."
+  - "For same-workflow artifact sharing between jobs, omit `run-id:` entirely — it defaults to the current run."
+  - "Check artifact retention settings — artifacts expire after 90 days (public) or 400 days (private) by default."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/storing-and-sharing-data-from-a-workflow"
+    label: "Storing and sharing data from a workflow"
+  - url: "https://github.com/actions/download-artifact"
+    label: "actions/download-artifact — README and cross-run download docs"
+  - url: "https://github.com/orgs/community/discussions/109905"
+    label: "GitHub Community #109905 — Unable to find any artifacts troubleshooting"
+  - url: "https://stackoverflow.com/questions/78238187/unable-to-find-any-artifacts-for-the-associated-workflow-github-actions"
+    label: "Stack Overflow — Unable to find any artifacts for the associated workflow"

package/errors/concurrency-timing/job-stuck-waiting-for-runner.yml

@@ -0,0 +1,105 @@
+id: concurrency-timing-006
+title: "Job Stuck: 'Waiting for a Runner to Pick Up This Job'"
+category: concurrency-timing
+severity: error
+tags:
+  - runner
+  - runs-on
+  - self-hosted
+  - queued
+  - stuck
+  - deprecated-runner
+patterns:
+  - regex: "Waiting for a runner to pick up this job"
+    flags: "i"
+  - regex: "No runner matching the specified labels"
+    flags: "i"
+  - regex: "Could not find any online and idle runners"
+    flags: "i"
+error_messages:
+  - "Waiting for a runner to pick up this job."
+  - "No runner matching the specified labels was found: [your-label]"
+  - "Could not find any online and idle runners matching the required labels."
+root_cause: |
+  A job remains stuck in the "queued" state — showing "Waiting for a runner to pick up
+  this job" — when GitHub Actions cannot find an available runner matching the `runs-on:`
+  labels. The job will wait indefinitely until the `timeout-minutes` limit is reached.
+
+  The most common causes:
+
+  1. **Deprecated or retired runner label** — GitHub periodically retires old runner images.
+     `ubuntu-18.04` was retired in April 2023. `ubuntu-20.04` deprecation is in progress.
+     Jobs using these labels get stuck because no GitHub-hosted runners serve the label.
+
+  2. **Typo in `runs-on:` label** — `ubuntu-latets`, `ubuntu_latest`, `UBuntu-latest` all
+     fail silently. GitHub-hosted label matching is case-sensitive for custom labels.
+
+  3. **Self-hosted runner offline or de-registered** — the runner was stopped, the service
+     was not restarted after a reboot, or the runner registration token expired. GitHub queues
+     the job and waits for a registered runner with matching labels to come online.
+
+  4. **Runner group restrictions** — organization admins restrict which repositories can use
+     which runner groups. A job referencing a group the repository is not authorized for will
+     queue indefinitely without an explicit permission error.
+
+  5. **All runners busy** — all matching runners are executing other jobs. The job correctly
+     queues but appears "stuck" during peak usage. It will eventually be picked up.
+
+  There is no notification when a job has been queued for an unusually long time — the only
+  signal is the job's wall-clock age and the static "Waiting for a runner" message.
+fix: |
+  Verify the `runs-on:` label against the current list of supported GitHub-hosted runner
+  images. For self-hosted runners, check runner registration and service health.
+fix_code:
+  - language: yaml
+    label: "Use current, non-deprecated GitHub-hosted runner labels"
+    code: |
+      jobs:
+        build:
+          # Use current supported labels only
+          runs-on: ubuntu-latest     # OR ubuntu-22.04, ubuntu-24.04
+          # NOT: ubuntu-18.04 (retired), ubuntu-20.04 (deprecated)
+
+        build-windows:
+          runs-on: windows-latest   # OR windows-2022, windows-2025
+
+        build-macos:
+          runs-on: macos-latest     # OR macos-13, macos-14, macos-15
+  - language: yaml
+    label: "Self-hosted runner — verify registration and labels match exactly"
+    code: |
+      jobs:
+        deploy:
+          # Labels must exactly match what the runner was registered with
+          # Check: GitHub Settings → Actions → Runners → click runner → Labels
+          runs-on: [self-hosted, linux, production]
+
+          steps:
+            - name: Verify runner is the expected host
+              run: echo "Running on $RUNNER_NAME at $(hostname)"
+  - language: yaml
+    label: "Fallback: matrix across hosted and self-hosted runners"
+    code: |
+      jobs:
+        build:
+          strategy:
+            matrix:
+              runner: [ubuntu-latest, [self-hosted, linux]]
+          runs-on: ${{ matrix.runner }}
+prevention:
+  - "Audit `runs-on:` labels in all workflows when GitHub announces runner image deprecations."
+  - "Set a job-level `timeout-minutes` so stuck jobs don't consume queue slots indefinitely."
+  - "For self-hosted runners, configure the runner service to auto-restart on reboot (e.g., `--service` install on Linux via `./svc.sh install`)."
+  - "Use GitHub's runner status page (Settings → Actions → Runners) to verify runners are Online before triggering long jobs."
+  - "Subscribe to GitHub Changelog and Actions deprecation notices to catch retiring runner labels early."
+docs:
+  - 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 GitHub-hosted runner labels"
+  - url: "https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/adding-self-hosted-runners"
+    label: "Adding self-hosted runners"
+  - url: "https://stackoverflow.com/questions/70959954/error-waiting-for-a-runner-to-pick-up-this-job-using-github-actions"
+    label: "Stack Overflow: Waiting for a runner to pick up this job"
+  - url: "https://github.com/actions/runner/issues/3609"
+    label: "actions/runner#3609 — Self-hosted runner stuck / deadlock"
+  - url: "https://github.com/orgs/community/discussions/147604"
+    label: "Community: Workflow stuck in queued state"

package/errors/concurrency-timing/matrix-fail-fast-sibling-cancellation.yml

@@ -0,0 +1,113 @@
+id: concurrency-timing-007
+title: "Matrix Sibling Jobs Silently Cancelled by fail-fast Default"
+category: concurrency-timing
+severity: silent-failure
+tags:
+  - matrix
+  - fail-fast
+  - cancellation
+  - silent-failure
+  - strategy
+  - job-cancelled
+patterns:
+  - regex: "Some jobs were not run because a sibling job failed"
+    flags: "i"
+  - regex: "Canceling since a higher priority waiting run was found"
+    flags: "i"
+  - regex: "The workflow run was canceled\\."
+    flags: "i"
+error_messages:
+  - "Some jobs were not run because a sibling job failed. To allow them to run anyway, add 'continue-on-error: true' to the matrix job."
+  - "Job was cancelled"
+root_cause: |
+  GitHub Actions matrix strategy defaults to `fail-fast: true`. When ANY matrix leg fails,
+  GitHub immediately cancels all other in-progress and pending legs in the same matrix.
+
+  This default is rarely what developers want during debugging or CI investigation, and
+  produces a confusing failure pattern:
+
+  1. **Cancelled legs appear as "Cancelled" not "Failed"** — matrix siblings killed by
+     `fail-fast` show as CANCELLED in the UI (grey icon) rather than red failures. Developers
+     scanning the run summary see one red failure and many grey cancellations, and may not
+     realize those sibling legs had reached significant progress (e.g., partway through a
+     test suite on a different OS or Node version) before being killed.
+
+  2. **Root cause is obscured** — the only failing leg that matters for diagnosis is the one
+     that triggered `fail-fast`, but with multiple cancellations in the UI, it can be hard to
+     identify which leg failed first.
+
+  3. **`fail-fast` is inherited silently** — there is no warning annotation that says
+     "fail-fast is enabled and cancelled 5 sibling legs." The default is documented but
+     easy to forget when adding a new matrix.
+
+  4. **Re-running failed jobs doesn't re-run cancelled siblings** — "Re-run failed jobs"
+     only re-runs the legs that explicitly FAILED, not the ones that were cancelled by
+     fail-fast. Developers re-running failed jobs think they'll see results from all legs,
+     but cancelled siblings stay cancelled. Only "Re-run all jobs" restarts everything.
+
+  Example: a 3-OS matrix (ubuntu, windows, macos) where ubuntu fails. With fail-fast,
+  windows and macos are immediately cancelled. The developer sees one failure and two
+  cancellations, re-runs the failed ubuntu job, and never discovers that windows also
+  had an independent failing test.
+fix: |
+  Set `fail-fast: false` explicitly on any matrix where you need full signal from all
+  legs — especially for cross-platform or multi-version compatibility matrices. Use
+  `fail-fast: true` intentionally only when running the full matrix after one failure is
+  wasteful (e.g., expensive build matrices during pre-merge CI).
+fix_code:
+  - language: yaml
+    label: "Disable fail-fast to see all matrix leg results"
+    code: |
+      jobs:
+        test:
+          strategy:
+            fail-fast: false  # All legs run regardless of siblings failing
+            matrix:
+              os: [ubuntu-latest, windows-latest, macos-latest]
+              node: [18, 20, 22]
+          runs-on: ${{ matrix.os }}
+          steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-node@v4
+              with:
+                node-version: ${{ matrix.node }}
+            - run: npm ci
+            - run: npm test
+  - language: yaml
+    label: "Use fail-fast: true only for expensive pre-merge CI"
+    code: |
+      jobs:
+        # Pre-merge: fail fast to conserve minutes — just need to know if it passes
+        lint-and-typecheck:
+          strategy:
+            fail-fast: true  # OK: fast, cheap, fail early
+            matrix:
+              node: [20, 22]
+          runs-on: ubuntu-latest
+          steps:
+            - run: npm run lint && npm run typecheck
+
+        # Post-merge: always see all platform results
+        full-test-suite:
+          if: github.event_name == 'push'
+          strategy:
+            fail-fast: false  # Need full signal on all platforms
+            matrix:
+              os: [ubuntu-latest, windows-latest, macos-latest]
+          runs-on: ${{ matrix.os }}
+          steps:
+            - run: npm test
+prevention:
+  - "Always set `fail-fast: false` explicitly on cross-platform or multi-version matrices where you need full compatibility signal."
+  - "After a matrix failure, use 'Re-run all jobs' (not 'Re-run failed jobs') to get results from previously-cancelled siblings."
+  - "Add a workflow summary step with `if: always()` to collect and consolidate test results across all matrix legs even when some are cancelled."
+  - "Be aware that cancelled legs (grey) are NOT the same as passed legs (green) — visually scan for both red and grey when investigating failures."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstrategyfail-fast"
+    label: "Workflow syntax: jobs.<job_id>.strategy.fail-fast"
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstrategymatrix"
+    label: "Workflow syntax: jobs.<job_id>.strategy.matrix"
+  - url: "https://github.com/orgs/community/discussions/26822"
+    label: "Community: fail-fast cancels matrix siblings unexpectedly"
+  - url: "https://stackoverflow.com/questions/57850553/github-actions-check-steps-status"
+    label: "Stack Overflow: Matrix job cancellation behavior with fail-fast"

package/errors/concurrency-timing/timeout-minutes-job-killed.yml

@@ -0,0 +1,107 @@
+id: concurrency-timing-005
+title: "Job Silently Cancelled When timeout-minutes Is Exceeded"
+category: concurrency-timing
+severity: error
+tags:
+  - timeout
+  - timeout-minutes
+  - job-cancelled
+  - timing
+  - runner
+patterns:
+  - regex: "##\\[error\\]The operation was cancelled\\."
+    flags: "i"
+  - regex: "The job '.*' was cancelled because it exceeded the maximum execution time"
+    flags: "i"
+  - regex: "Error: The operation was canceled"
+    flags: "i"
+  - regex: "cancel is received"
+    flags: "i"
+error_messages:
+  - "##[error]The operation was cancelled."
+  - "Error: The operation was canceled"
+  - "The runner has received a shutdown signal. This can happen when the runner service is stopped, or a manually started runner is canceled."
+root_cause: |
+  When a job (or step) exceeds its configured `timeout-minutes`, GitHub Actions sends a
+  cancellation signal to the runner. The runner has 5 minutes to complete graceful shutdown,
+  after which it is forcibly terminated.
+
+  The failure mode has two layers of confusion:
+
+  1. **Status shows "Cancelled" not "Failed"** — a timed-out job is marked CANCELLED in the
+     UI. It does not appear as a red failure. Developers scanning the Actions tab may miss it
+     entirely, especially if another run succeeded after it.
+
+  2. **No step-level attribution** — the job log shows "The operation was cancelled" but does
+     not identify which specific step was still running or how far it had progressed. Long
+     builds, network-heavy steps, and interactive prompts are common culprits.
+
+  3. **Default timeout is 360 minutes (6 hours)** — if `timeout-minutes` is not explicitly
+     set, GitHub uses the platform default of 6 hours for GitHub-hosted runners. A job that
+     accidentally blocks (waiting for user input, infinite loop, hung network call) will silently
+     consume 6 hours of runner minutes before being cancelled with no diagnostic output.
+
+  4. **Step-level timeouts are independent** — `timeout-minutes` on a `steps[*]` entry cancels
+     only that step; the job continues. `timeout-minutes` on `jobs[*]` cancels the entire job.
+     Mixing both is valid but must be understood deliberately.
+fix: |
+  Always set explicit `timeout-minutes` at the job level to bound worst-case runner cost.
+  Tune based on your typical build time (e.g., 2-3× the median duration). Add step-level
+  timeouts on known slow steps (network downloads, test suites) to get better attribution.
+
+  To diagnose which step was running at cancellation: add a step near the end that dumps
+  elapsed time, or use `if: cancelled()` post-steps to capture diagnostics on timeout.
+fix_code:
+  - language: yaml
+    label: "Explicit job-level timeout with diagnostic post-step"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          timeout-minutes: 30  # Set explicitly — don't rely on 6h default
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Build
+              run: make build
+
+            - name: Tests
+              timeout-minutes: 15  # Step-level timeout for attribution
+              run: make test
+
+            # Always runs — captures which step caused the timeout
+            - name: Dump elapsed time on cancellation
+              if: cancelled()
+              run: echo "Job was cancelled at $(date -u). Check step durations above."
+  - language: yaml
+    label: "Identify which step timed out with job summary annotation"
+    code: |
+      steps:
+        - name: Long network operation
+          timeout-minutes: 10
+          run: |
+            # Use --max-time with curl to avoid relying solely on timeout-minutes
+            curl --max-time 300 https://example.com/large-asset -o output.bin
+
+        - name: Report timeout if cancelled
+          if: cancelled()
+          run: |
+            echo "## ⏱️ Job Timed Out" >> $GITHUB_STEP_SUMMARY
+            echo "The job was cancelled. Review step durations in the log." >> $GITHUB_STEP_SUMMARY
+prevention:
+  - "Always set `timeout-minutes` at the job level — never rely on the 6-hour GitHub default."
+  - "Add step-level `timeout-minutes` on network-heavy or test steps so cancellation is attributed to a specific step."
+  - "Use `if: cancelled()` post-steps to write a job summary annotation explaining the timeout."
+  - "Run commands with their own timeout flags (e.g., `curl --max-time`, `pytest --timeout`) in addition to runner timeouts."
+  - "Monitor job duration trends — a job approaching its timeout limit is a signal to investigate performance."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idtimeout-minutes"
+    label: "Workflow syntax: jobs.<job_id>.timeout-minutes"
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepstimeout-minutes"
+    label: "Workflow syntax: jobs.<job_id>.steps[*].timeout-minutes"
+  - url: "https://github.com/actions/runner/issues/1326"
+    label: "actions/runner#1326 — Steps hanging until timeout with no log output"
+  - url: "https://github.com/orgs/community/discussions/38004"
+    label: "Community: Job stops producing output and is later cancelled"
+  - url: "https://docs.github.com/en/actions/administering-github-actions/usage-limits-billing-and-administration#usage-limits"
+    label: "Usage limits: maximum job execution time"

package/errors/known-unsolved/github-step-summary-size-limit.yml

@@ -0,0 +1,112 @@
+id: known-unsolved-008
+title: "GITHUB_STEP_SUMMARY Upload Aborted When Content Exceeds 1024k"
+category: known-unsolved
+severity: error
+tags:
+  - step-summary
+  - GITHUB_STEP_SUMMARY
+  - size-limit
+  - job-summary
+  - markdown
+  - limitation
+patterns:
+  - regex: "\\$GITHUB_STEP_SUMMARY upload aborted, supports content up to a size of 1024k, got \\d+k"
+    flags: "i"
+  - regex: "upload aborted.*supports content up to a size of 1024k"
+    flags: "i"
+  - regex: "Error: GITHUB_STEP_SUMMARY.*1024"
+    flags: "i"
+error_messages:
+  - "$GITHUB_STEP_SUMMARY upload aborted, supports content up to a size of 1024k, got 1387k"
+  - "$GITHUB_STEP_SUMMARY upload aborted, supports content up to a size of 1024k, got 2048k"
+root_cause: |
+  GitHub Actions imposes a hard 1 MiB (1024 KiB) size limit on the content written to
+  `$GITHUB_STEP_SUMMARY`. When a step writes more than this limit, the runner aborts
+  the summary upload and logs an error.
+
+  This is a **platform limit with no workaround** — you cannot increase it. GitHub has not
+  announced plans to raise the limit.
+
+  Common triggers:
+  1. **Test reporters** — tools like `dorny/test-reporter`, `ctrf-io/github-actions-ctrf`,
+     or `EnricoMi/publish-unit-test-result-action` write per-test result tables. Large
+     test suites (thousands of test cases, especially with long failure messages) easily
+     exceed 1 MiB.
+  2. **Dependency review action** — `actions/dependency-review-action` writes full
+     dependency diff tables. Large projects with hundreds of transitive dependencies produce
+     summaries well above 1 MiB.
+  3. **Coverage reports** — HTML-style coverage tables written to `$GITHUB_STEP_SUMMARY`
+     with per-file rows can grow unboundedly on large monorepos.
+  4. **Log echo pipelines** — `cat large-file >> $GITHUB_STEP_SUMMARY` without size
+     checking is the most direct way to hit the limit.
+
+  The error aborts the summary upload but does **not** fail the step or job by default.
+  Depending on the action's error handling, the step may succeed (exit 0) even though the
+  summary was not written — making this a silent failure from a reporting perspective.
+fix: |
+  Truncate or paginate summary content before writing it. Most test reporters provide
+  options to limit which results are written (e.g., only failures, not all passed tests).
+  For custom summary generation, check the size before writing and truncate with a note.
+fix_code:
+  - language: yaml
+    label: "Truncate summary content with size check before writing"
+    code: |
+      - name: Generate test report
+        run: |
+          # Generate report to a temp file first
+          ./scripts/generate-report.sh > /tmp/report.md
+
+          # Check size before writing to summary
+          SIZE_KB=$(du -k /tmp/report.md | cut -f1)
+          MAX_KB=800  # Leave headroom below 1024k limit
+
+          if [ "$SIZE_KB" -gt "$MAX_KB" ]; then
+            echo "⚠️ Full report too large (${SIZE_KB}k). Showing failures only." >> "$GITHUB_STEP_SUMMARY"
+            ./scripts/generate-report.sh --failures-only >> "$GITHUB_STEP_SUMMARY"
+          else
+            cat /tmp/report.md >> "$GITHUB_STEP_SUMMARY"
+          fi
+  - language: yaml
+    label: "dorny/test-reporter — limit to failures only for large test suites"
+    code: |
+      - name: Test Report
+        uses: dorny/test-reporter@v1
+        if: always()
+        with:
+          name: Test Results
+          path: test-results/**/*.xml
+          reporter: jest-junit
+          # Limit output to avoid 1024k summary limit on large suites
+          only-summary: true          # Write only totals, not per-test rows
+          fail-on-error: false
+  - language: yaml
+    label: "Upload full report as artifact instead of writing to summary"
+    code: |
+      - name: Generate full coverage report
+        run: ./scripts/coverage.sh > /tmp/coverage-full.md
+
+      - name: Write summary (truncated)
+        run: |
+          head -100 /tmp/coverage-full.md >> "$GITHUB_STEP_SUMMARY"
+          echo "" >> "$GITHUB_STEP_SUMMARY"
+          echo "_Full report available as workflow artifact._" >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Upload full report as artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-report
+          path: /tmp/coverage-full.md
+prevention:
+  - "Never pipe unbounded command output directly to `$GITHUB_STEP_SUMMARY` — always size-check or limit first."
+  - "Configure test reporter actions to write only failures (not all passing tests) when the test suite is large."
+  - "Upload large reports as workflow artifacts and link to them from a short summary, instead of embedding all content in the summary."
+  - "The undocumented historical limit of 65,535 characters cited in older docs/answers is no longer accurate — the current limit is 1024 KiB (1 MiB)."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#adding-a-job-summary"
+    label: "Workflow commands: Adding a job summary"
+  - url: "https://github.com/actions/dependency-review-action/issues/786"
+    label: "dependency-review-action#786 — Job Summary Size Limitation aborts the job"
+  - url: "https://github.com/dorny/test-reporter/issues/379"
+    label: "dorny/test-reporter#379 — Is the step summary limit for 65535 characters still accurate?"
+  - url: "https://docs.github.com/en/actions/administering-github-actions/usage-limits-billing-and-administration#usage-limits"
+    label: "Usage limits — GitHub Actions"