@htekdev/actions-debugger 1.0.31 → 1.0.33

package/errors/caching-artifacts/download-artifact-v5-single-artifact-no-subdirectory.yml

@@ -0,0 +1,106 @@
+id: 'caching-artifacts-029'
+title: '`download-artifact` v5+ omits artifact subdirectory when only one artifact exists — dynamic workflows break intermittently'
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - download-artifact
+  - v5-breaking-change
+  - path-behavior
+  - single-artifact
+  - subdirectory
+  - dynamic-matrix
+patterns:
+  - regex: 'uses:\s*actions/download-artifact@v[5-9]'
+    flags: 'i'
+  - regex: 'An extra directory with the artifact name will be created for each download'
+    flags: 'i'
+error_messages:
+  - 'No input name, artifact-ids or pattern filtered specified, downloading all artifacts'
+  - 'An extra directory with the artifact name will be created for each download'
+root_cause: |
+  In actions/download-artifact v5 (released August 2025) and later (v6, v7), when
+  downloading ALL artifacts without specifying name: or id:, and only ONE artifact exists
+  in the workflow run, the action does NOT create a subdirectory for that artifact.
+  Files are extracted directly into the destination path (default ./):
+
+    Expected (v4 and v5+ with >=2 artifacts): ./{artifact-name}/file.ext
+    Actual (v5+ with exactly 1 artifact):      ./file.ext
+
+  When two or more artifacts exist, subdirectories are created correctly. This
+  inconsistency breaks workflows where artifact count varies dynamically — e.g., matrix
+  strategies that produce 0, 1, or N artifacts based on test conditions.
+
+  The action logs "An extra directory with the artifact name will be created for each
+  download" even when it will NOT do this — making the bug invisible in logs.
+
+  Bug tracked in actions/download-artifact#455 (December 2025, still open).
+  Affected versions: v5.0.0+, v6.0.0+, v7.0.0+
+  v4 behavior (correct): always creates a named subdirectory, regardless of artifact count.
+
+  This is a regression from a path behavior fix introduced in v5 for single-artifact
+  downloads by ID (PR #416), which had an unintended side effect on the "all artifacts"
+  code path when n=1.
+fix: |
+  Option 1 (simplest): Pin to actions/download-artifact@v4, which always creates a
+  subdirectory regardless of artifact count. v4 remains maintained for GHES compatibility.
+
+  Option 2: Always specify name: for each download to avoid the "all artifacts" code path.
+
+  Option 3: In downstream steps, detect the n=1 case at runtime and normalize the
+  directory structure before relying on subdirectory paths.
+fix_code:
+  - language: yaml
+    label: 'Pin to download-artifact@v4 for consistent subdirectory behavior'
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Download all artifacts
+              uses: actions/download-artifact@v4    # v4: always creates subdirs
+              with:
+                path: artifacts/
+              # Result: artifacts/{name}/... for every artifact, even when n=1
+
+            - name: Deploy each artifact directory
+              run: |
+                for dir in artifacts/*/; do
+                  name=$(basename "$dir")
+                  echo "Deploying $name from $dir"
+                done
+  - language: yaml
+    label: 'Workaround for v5+: download by name into named subdirectories explicitly'
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: List artifact names for this run
+              id: list
+              uses: actions/github-script@v7
+              with:
+                script: |
+                  const { data } = await github.rest.actions.listWorkflowRunArtifacts({
+                    owner: context.repo.owner,
+                    repo: context.repo.repo,
+                    run_id: context.runId
+                  });
+                  return data.artifacts.map(a => a.name);
+
+            - name: Download artifact into named subdirectory
+              uses: actions/download-artifact@v5
+              with:
+                name: my-artifact
+                path: artifacts/my-artifact/   # Explicit subdir — consistent always
+prevention:
+  - 'Pin to download-artifact@v4 if your deployment logic assumes each artifact lands in its own named subdirectory'
+  - 'Test your workflow with exactly one artifact in CI — the n=1 edge case is easy to miss in standard multi-run testing'
+  - 'Avoid relying on implicit subdirectory creation; always specify explicit path: values that include the artifact name'
+  - 'Track actions/download-artifact#455 for a fix in v5+ that restores consistent subdirectory behavior'
+docs:
+  - url: 'https://github.com/actions/download-artifact/issues/455'
+    label: 'actions/download-artifact#455: Single artifact omits subdirectory in v5+ (open, December 2025)'
+  - url: 'https://github.com/actions/download-artifact/releases/tag/v5.0.0'
+    label: 'download-artifact v5.0.0 release notes: path behavior breaking change'
+  - url: 'https://github.com/actions/download-artifact/blob/main/docs/MIGRATION.md'
+    label: 'download-artifact migration guide: v3/v4 to v5+'

package/errors/permissions-auth/ghs-token-new-jwt-format-breaks-length-pattern-validation.yml

@@ -0,0 +1,95 @@
+id: 'permissions-auth-031'
+title: 'GitHub App installation token new stateless JWT format (~520 chars) breaks hardcoded length and regex validation'
+category: permissions-auth
+severity: error
+tags:
+  - github-app-token
+  - ghs-token
+  - jwt-format
+  - token-validation
+  - installation-token
+  - breaking-change-2026
+patterns:
+  - regex: 'ghs_[A-Za-z0-9]{36}\b'
+    flags: ''
+  - regex: 'Data too long for column|token.*length.*40|varchar\s*\(\s*40\s*\)'
+    flags: 'i'
+error_messages:
+  - "Data too long for column 'access_token' at row 1"
+  - 'Token validation failed: token length 521 does not match expected 40'
+  - 'Invalid token format: expected 40 characters, got 523'
+  - 'ghs_[A-Za-z0-9]{36} pattern did not match token starting with ghs_'
+root_cause: |
+  Starting April 27, 2026, GitHub began a staged rollout that changes the format of all
+  GitHub App installation tokens (ghs_ prefixed tokens), including the GITHUB_TOKEN
+  issued to Actions workflows.
+
+  Old format: ghs_<36 alphanumeric chars> — exactly 40 characters, opaque string
+  New format: ghs_<AppID>_<JWT> — approximately 520 characters (variable length),
+              JWT payload is signed by a GitHub-internal issuer
+
+  Any code that validates or stores tokens with the old format assumption WILL break:
+  - Regex: ghs_[A-Za-z0-9]{36} — the {36} quantifier rejects the new variable-length JWT
+  - Length checks: len(token) == 40, token.length === 40, strlen($token) == 40
+  - Database columns: VARCHAR(40) or CHAR(40) — the new ~520-char token truncates or errors
+  - Secret scanning rules with exact-length matchers for ghs_ tokens miss leaked tokens
+
+  The rollout timeline:
+  - April 27 – mid-May 2026: GITHUB_TOKEN and first-party tokens (Dependabot, Slack, Teams)
+  - Mid-May to late-June 2026: staged rollout to all GitHub App installation tokens
+
+  Despite the new internal JWT structure, the token prefix ghs_ is unchanged. Clients
+  must treat the entire token as an opaque string and must NOT parse or validate the JWT.
+fix: |
+  Treat all ghs_ tokens as variable-length opaque strings. Remove any assumptions about
+  exact length or character structure after the ghs_ prefix:
+
+  1. Update regex patterns: replace ghs_[A-Za-z0-9]{36} with ghs_[A-Za-z0-9._-]+
+  2. Increase database columns: VARCHAR(40) or CHAR(40) → TEXT or VARCHAR(1024)
+  3. Remove hardcoded length checks: len(token) == 40 → len(token) > 3
+  4. Update secret scanning rules to match variable-length ghs_ tokens
+
+  To test your tooling against the new format BEFORE the rollout reaches your integration,
+  use the X-GitHub-Stateless-S2S-Token: enabled header on access token API requests.
+fix_code:
+  - language: yaml
+    label: 'Verify GITHUB_TOKEN length in a workflow — expect ~520 chars with new format'
+    code: |
+      jobs:
+        check-token-format:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Check GITHUB_TOKEN length
+              env:
+                TOKEN: ${{ secrets.GITHUB_TOKEN }}
+              run: |
+                echo "Token length: ${#TOKEN}"
+                # Old format: exactly 40 chars
+                # New format (post-April 2026 rollout): ~520 chars (variable)
+                # If your tooling uses this token, ensure it handles both lengths
+  - language: yaml
+    label: 'Correct regex for ghs_ tokens in secret scanning custom patterns'
+    code: |
+      # WRONG — only matches old 40-char opaque tokens:
+      #   ghs_[A-Za-z0-9]{36}
+      #
+      # CORRECT — matches old and new JWT format:
+      #   ghs_[A-Za-z0-9._-]+
+      #
+      # .github/secret_scanning.yml custom pattern (if scanning for leaked tokens):
+      custom_patterns:
+        - name: GitHub App installation token (all formats)
+          regex: 'ghs_[A-Za-z0-9._-]+'
+prevention:
+  - 'Treat all GitHub tokens as variable-length opaque strings — never hardcode expected length'
+  - 'Use TEXT or VARCHAR(1024) for any database column that stores GitHub App installation tokens'
+  - 'Validate ghs_ tokens by prefix only, not by exact length or post-prefix character class'
+  - 'Subscribe to the GitHub Changelog (github.blog/changelog) to catch token format changes early'
+  - 'Use X-GitHub-Stateless-S2S-Token: enabled header to test your tooling before the rollout reaches your repos'
+docs:
+  - url: 'https://github.blog/changelog/2026-04-24-notice-about-upcoming-new-format-for-github-app-installation-tokens/'
+    label: 'GitHub Changelog: Notice about upcoming new format for GitHub App installation tokens (April 24, 2026)'
+  - url: 'https://github.blog/changelog/2026-05-15-github-app-installation-tokens-per-request-override-header/'
+    label: 'GitHub Changelog: Per-request override header for testing the new token format (May 15, 2026)'
+  - url: 'https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-an-installation-access-token-for-a-github-app'
+    label: 'GitHub Docs: Generating an installation access token for a GitHub App'

package/errors/runner-environment/macos-15-arm64-homebrew-rustup-init-argv-rejected.yml

@@ -0,0 +1,114 @@
+id: 'runner-environment-086'
+title: 'macOS 15 arm64 Homebrew `rustup-init` rejects `+stable` toolchain specifier and subcommands — Rust builds fail with ~50% probability'
+category: runner-environment
+severity: error
+tags:
+  - macos
+  - arm64
+  - homebrew
+  - rust
+  - rustup
+  - maturin
+  - napi-rs
+  - image-regression
+patterns:
+  - regex: 'error: unexpected argument .+stable. found'
+    flags: 'i'
+  - regex: 'error: unexpected argument .metadata. found'
+    flags: 'i'
+  - regex: 'Usage: rustup-init\[EXE\] \[OPTIONS\]'
+    flags: 'i'
+  - regex: 'macos-15-arm64.*20260511'
+    flags: 'i'
+error_messages:
+  - "Error: error: error: unexpected argument '+stable' found"
+  - "error: error: unexpected argument 'metadata' found"
+  - "Usage: rustup-init[EXE] [OPTIONS]"
+  - "info: self-update is disabled for this build of rustup"
+  - "Could not parse the Cargo.toml: Error: Command failed: cargo metadata"
+root_cause: |
+  The macos-15-arm64 runner image version 20260511.0048 ships a broken Homebrew rustup
+  formula at /opt/homebrew/bin/rustup (version 1.29.0) whose bundled rustup-init binary
+  rejects standard argv that the outer rustup CLI forwards internally.
+
+  When rustup receives a command like `rustup component add llvm-tools-preview` or when
+  cargo shims invoke `cargo metadata`, the outer rustup binary calls rustup-init with
+  forwarded arguments (+stable, metadata, etc.). On this image version, rustup-init
+  treats these as unknown positional arguments and immediately exits with an error.
+
+  The failure is intermittent because GitHub's runner scheduler assigns jobs to different
+  image versions: 20260511.0048 (broken) and 20260427.0018 (working). A single workflow
+  run with multiple matrix entries can produce a mix of passing and failing jobs depending
+  on which image version each job lands on. Reruns do not reliably fix the issue because
+  rerun jobs may again be scheduled on the broken image version.
+
+  Affected downstream tools (all work on 20260427.0018, all fail on 20260511.0048):
+  - PyO3/maturin-action@v1 — calls `rustup component add llvm-tools-preview`
+  - @napi-rs/cli — calls `cargo metadata --format-version 1`
+  - Any workflow that calls `rustup component add` with a toolchain specifier
+  - Any Rust build that uses the Homebrew rustup shim for internal rustup-init calls
+
+  Tracked in actions/runner-images#14097 (May 2026, open).
+fix: |
+  Option 1 (recommended): Install rustup from the upstream installer (sh.rustup.rs)
+  before any Rust build steps. This replaces the broken Homebrew binary at
+  /opt/homebrew/bin/rustup with the upstream version and resolves the argv issue.
+
+  Option 2: Pin the runner to macos-15-arm64 explicitly and avoid the image lottery.
+  Note: this only temporarily avoids the issue; broken images will eventually be the
+  only version served.
+
+  Option 3: Use the dtolnay/rust-toolchain action before any Rust operations to
+  install or update rustup via the upstream installer, bypassing the Homebrew version.
+fix_code:
+  - language: yaml
+    label: 'Replace Homebrew rustup with upstream installer before Rust build steps'
+    code: |
+      jobs:
+        build:
+          runs-on: macos-latest   # or macos-15-arm64
+          steps:
+            - uses: actions/checkout@v6
+
+            - name: Replace Homebrew rustup with upstream installer
+              run: |
+                # Remove Homebrew rustup to avoid the broken rustup-init binary
+                brew uninstall rustup-init rustup 2>/dev/null || true
+                # Install from upstream — stable, no Homebrew dependency
+                curl https://sh.rustup.rs -sSf | sh -s -- -y --no-modify-path
+                echo "$HOME/.cargo/bin" >> $GITHUB_PATH
+
+            - name: Install Rust target
+              run: rustup target add aarch64-apple-darwin
+
+            - uses: PyO3/maturin-action@v1
+              with:
+                target: aarch64-apple-darwin
+  - language: yaml
+    label: 'Use dtolnay/rust-toolchain to install a clean rustup before builds'
+    code: |
+      jobs:
+        build:
+          runs-on: macos-latest
+          steps:
+            - uses: actions/checkout@v6
+
+            - name: Install Rust toolchain (upstream, not Homebrew)
+              uses: dtolnay/rust-toolchain@stable
+              with:
+                components: llvm-tools-preview
+
+            - name: Build
+              run: cargo build --release
+prevention:
+  - 'Prefer dtolnay/rust-toolchain or rustup-toolchain-install-master for cross-platform Rust toolchain management rather than relying on the pre-installed Homebrew rustup'
+  - 'Test macOS ARM64 jobs on both arm64 and x86-via-Rosetta matrix entries to detect image-lottery regressions early'
+  - 'Watch actions/runner-images#14097 for the fix and the image version that resolves the broken rustup-init'
+  - 'Avoid using the Homebrew rustup binary directly; upstream rustup at ~/.cargo/bin/rustup is more stable across image updates'
+docs:
+  - url: 'https://github.com/actions/runner-images/issues/14097'
+    label: 'actions/runner-images#14097: macos-15-arm64/20260511.0048 ships broken Homebrew rustup-init (May 2026)'
+  - url: 'https://rustup.rs/'
+    label: 'rustup.rs: Official upstream rustup installer'
+  - url: 'https://github.com/PyO3/maturin-action'
+    label: 'PyO3/maturin-action: Affected action that calls rustup component add'

package/errors/runner-environment/ubuntu-24-04-iproute2-kernel-614-vxlan-segfault.yml

@@ -0,0 +1,102 @@
+id: 'runner-environment-087'
+title: '`ip -d link show` segfaults (exit 139 / SIGSEGV) on VXLAN interfaces on ubuntu-24.04 after kernel 6.14 upgrade'
+category: runner-environment
+severity: error
+tags:
+  - ubuntu-24-04
+  - networking
+  - vxlan
+  - iproute2
+  - kernel
+  - segfault
+  - regression
+  - container-networking
+patterns:
+  - regex: 'Segmentation fault.*ip.*link'
+    flags: 'i'
+  - regex: 'ip -d link show.*exit.*139'
+    flags: 'i'
+  - regex: 'ip\s+-d\s+link\s+show'
+    flags: 'i'
+error_messages:
+  - 'Segmentation fault (core dumped)'
+  - 'Process completed with exit code 139.'
+  - 'ip: Segmentation fault'
+root_cause: |
+  On ubuntu-24.04 runner image 20260209.23 and later, the kernel was upgraded to
+  6.14.0-1017-azure while the iproute2 package remained at version 6.1.0-1ubuntu6.2.
+
+  Linux kernel 6.14 introduced a new VXLAN netlink attribute (IFLA_VXLAN_FAN_MAP) in
+  the rtnetlink interface. When iproute2 6.1 receives a netlink response containing this
+  unrecognized attribute and parses it with the -d (details) flag, it dereferences an
+  unexpected attribute structure, triggering a SIGSEGV.
+
+  The crash occurs specifically when:
+  1. A VXLAN network interface exists on the runner (e.g., created with `ip link add ... type vxlan`)
+  2. `ip -d link show dev <vxlan-interface>` is executed to inspect its details
+
+  Without the -d flag, `ip link show` succeeds. The regression was confirmed by comparing:
+  - Working image: 20260201.15.1 (kernel 6.11.0-1018-azure, iproute2 6.1.0-1ubuntu6.2)
+  - Broken image:  20260209.23.1 (kernel 6.14.0-1017-azure, iproute2 6.1.0-1ubuntu6.2)
+
+  Affected workflows: any CI that creates VXLAN interfaces for network simulation, overlay
+  networking tests, or Kubernetes-in-CI scenarios (e.g., containerlab, kind with custom
+  network topologies, network protocol testing).
+
+  Tracked in actions/runner-images#13669 (February 2026, open).
+fix: |
+  Option 1: Upgrade iproute2 to a version compatible with kernel 6.14 at the start of
+  the job. Install a newer iproute2 from a backport PPA or compile from source.
+
+  Option 2: Avoid the -d flag when only basic VXLAN interface information is needed.
+  `ip link show dev <vxlan-interface>` (without -d) does not trigger the crash.
+
+  Option 3: Pin to ubuntu-22.04, which uses an older kernel/iproute2 combination that
+  does not exhibit this issue.
+
+  Option 4: Parse VXLAN interface details via /sys/class/net/ sysfs entries instead of
+  relying on `ip -d link show`.
+fix_code:
+  - language: yaml
+    label: 'Upgrade iproute2 before creating VXLAN interfaces to avoid segfault'
+    code: |
+      jobs:
+        network-test:
+          runs-on: ubuntu-24.04
+          steps:
+            - name: Upgrade iproute2 to kernel-6.14-compatible version
+              run: |
+                sudo apt-get update -qq
+                sudo apt-get install -y --only-upgrade iproute2
+                ip -V    # Verify new version
+
+            - name: Create and inspect VXLAN interface
+              run: |
+                sudo ip link add vxlan-test type vxlan id 100 \
+                  local 10.0.0.1 remote 10.0.0.2 dev eth0 dstport 4789
+                ip -d link show dev vxlan-test   # Safe with upgraded iproute2
+
+  - language: yaml
+    label: 'Avoid -d flag as workaround on ubuntu-24.04 without iproute2 upgrade'
+    code: |
+      jobs:
+        network-test:
+          runs-on: ubuntu-24.04
+          steps:
+            - name: Create VXLAN interface
+              run: |
+                sudo ip link add vxlan-test type vxlan id 100 dstport 4789
+                # Use ip link show WITHOUT -d flag to avoid SIGSEGV on kernel 6.14
+                ip link show dev vxlan-test
+                # VXLAN-specific attributes via sysfs instead of iproute2 -d output:
+                cat /sys/class/net/vxlan-test/carrier || true
+prevention:
+  - 'Add an iproute2 upgrade step when workflows inspect VXLAN or other advanced interface types with `ip -d link show`'
+  - 'Watch actions/runner-images#13669 for a fix that aligns iproute2 with the kernel 6.14 netlink attributes'
+  - 'Test network-intensive CI on both ubuntu-22.04 and ubuntu-24.04 to detect kernel/iproute2 mismatch regressions'
+  - 'Consider ubuntu-22.04 for VXLAN-dependent workflows until the iproute2 package is updated on ubuntu-24.04 images'
+docs:
+  - url: 'https://github.com/actions/runner-images/issues/13669'
+    label: 'actions/runner-images#13669: ip -d link show segfaults on vxlan interfaces — iproute2/kernel 6.14 mismatch'
+  - url: 'https://manpages.ubuntu.com/manpages/noble/man8/ip-link.8.html'
+    label: 'Ubuntu ip-link manpage: ip link show options'

package/errors/runner-environment/ubuntu-slim-setup-node-semver-range-toolcache-miss.yml

@@ -0,0 +1,108 @@
+id: 'runner-environment-088'
+title: '`ubuntu-slim` runner has empty Node.js toolcache — `setup-node` with semver range downloads latest patch instead of using cached version'
+category: runner-environment
+severity: error
+tags:
+  - ubuntu-slim
+  - setup-node
+  - toolcache
+  - semver
+  - caching
+  - node
+  - version-mismatch
+patterns:
+  - regex: 'evaluating 0 versions'
+    flags: 'i'
+  - regex: 'Attempting to download.*\.\.\.'
+    flags: 'i'
+  - regex: 'ubuntu-slim.*setup-node'
+    flags: 'i'
+error_messages:
+  - '##[debug]evaluating 0 versions'
+  - '##[debug]match not found'
+  - 'Attempting to download 24.x...'
+  - 'Acquiring 24.13.1 - x64 from https://github.com/actions/node-versions/releases/download/'
+root_cause: |
+  The ubuntu-slim runner image ships with an empty or absent Node.js toolcache manifest.
+  When actions/setup-node evaluates a semver range (e.g., 24, 24.x, 22.x) it first
+  inspects the local toolcache versions manifest. On ubuntu-slim, the manifest contains
+  zero cached versions (log line: "evaluating 0 versions"), so setup-node falls through
+  to download the latest matching version from GitHub releases at runtime.
+
+  On ubuntu-24.04 and ubuntu-latest, setup-node finds the cached version (e.g., 24.13.0)
+  and logs "Found tool in cache". The same workflow on ubuntu-slim downloads a newer
+  patch release (e.g., 24.13.1) because the remote versions API returns the freshest
+  available release.
+
+  This causes three distinct problems:
+  1. Slower CI: every job downloads Node.js from the network instead of using the cache
+  2. Version drift: ubuntu-slim jobs may use a different Node.js version than ubuntu-24.04
+     jobs in the same matrix, silently breaking cross-platform consistency checks
+  3. Test failures: libraries that cache built binaries keyed on Node.js version will
+     produce cache misses across ubuntu-slim and ubuntu-latest jobs in the same run
+
+  Reproduced on ubuntu-slim image version 20260120.46.1.
+  Tracked in actions/runner-images#13671 and actions/setup-node#1492 (February 2026).
+fix: |
+  Option 1: Pin an explicit Node.js version (e.g., 24.13.0) instead of a semver range.
+  setup-node downloads this version on ubuntu-slim, but the result is deterministic and
+  matches any version you also pin on ubuntu-latest or ubuntu-24.04.
+
+  Option 2: Use a .node-version or .nvmrc file with an exact version. setup-node reads
+  the file and pins to that version on all runner images.
+
+  Option 3: Use actions/cache to manually cache the Node.js installation directory on
+  ubuntu-slim jobs.
+
+  Option 4: Avoid ubuntu-slim for workflows that require a specific Node.js toolcache
+  version. Use ubuntu-24.04 or ubuntu-latest which ship pre-cached Node.js versions.
+fix_code:
+  - language: yaml
+    label: 'Pin exact Node.js version to avoid toolcache miss on ubuntu-slim'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-slim   # empty toolcache
+          steps:
+            - uses: actions/checkout@v6
+
+            # WRONG: semver range downloads latest patch on ubuntu-slim
+            # - uses: actions/setup-node@v6
+            #   with:
+            #     node-version: '24'    # evaluating 0 versions → downloads 24.13.1
+
+            # CORRECT: explicit version is deterministic on all images
+            - uses: actions/setup-node@v6
+              with:
+                node-version: '24.13.0'   # exact — no toolcache lookup needed
+
+  - language: yaml
+    label: 'Use .node-version file for consistent version across all runner images'
+    code: |
+      # .node-version (at repo root):
+      #   24.13.0
+
+      jobs:
+        build:
+          runs-on: ${{ matrix.os }}
+          strategy:
+            matrix:
+              os: [ubuntu-slim, ubuntu-24.04, macos-latest]
+          steps:
+            - uses: actions/checkout@v6
+
+            - uses: actions/setup-node@v6
+              with:
+                node-version-file: '.node-version'   # same version on all images
+prevention:
+  - 'Use exact Node.js versions (not semver ranges like 24.x) when running on ubuntu-slim to ensure deterministic toolcache behavior'
+  - 'Add a .node-version or .nvmrc file at the repo root and reference it with node-version-file: for consistent versions across all runner images'
+  - 'In matrix builds mixing ubuntu-slim with ubuntu-24.04, verify that node --version outputs match to detect silent version drift'
+  - 'Watch actions/runner-images#13671 for a fix that pre-populates the ubuntu-slim toolcache with a Node.js manifest'
+docs:
+  - url: 'https://github.com/actions/runner-images/issues/13671'
+    label: 'actions/runner-images#13671: setup-node incorrectly downloads latest on ubuntu-slim'
+  - url: 'https://github.com/actions/setup-node/issues/1492'
+    label: 'actions/setup-node#1492: ubuntu-slim toolcache manifest missing'
+  - url: 'https://github.com/actions/setup-node#usage'
+    label: 'actions/setup-node documentation: node-version-file option'

package/errors/silent-failures/download-artifact-merge-multiple-parallel-file-clobber.yml

@@ -0,0 +1,119 @@
+id: 'silent-failures-038'
+title: '`download-artifact` `merge-multiple: true` silently corrupts files when multiple artifacts contain identical filenames'
+category: silent-failures
+severity: silent-failure
+tags:
+  - download-artifact
+  - merge-multiple
+  - file-corruption
+  - parallel-download
+  - race-condition
+  - artifacts
+patterns:
+  - regex: 'merge-multiple:\s*true'
+    flags: 'i'
+  - regex: 'Downloading artifact:.*\n.*Downloading artifact:'
+    flags: 'im'
+error_messages:
+  - 'Downloading artifact: build-linux to /home/runner/work/repo/repo/dist'
+  - 'Downloading artifact: build-macos to /home/runner/work/repo/repo/dist'
+root_cause: |
+  When actions/download-artifact (v4+) is used with merge-multiple: true and two or more
+  artifacts contain files with identical relative paths (e.g., multiple matrix builds each
+  upload a file named checksums.txt or report.json), the action downloads all artifacts
+  in parallel using a PARALLEL_DOWNLOADS worker pool.
+
+  All parallel workers write to the same destination directory concurrently. When two
+  workers attempt to write to the same filename simultaneously, the result is undefined:
+  - The output file may contain interleaved bytes from both sources
+  - The file may be truncated to the size of the smaller upload
+  - One artifact's version may completely overwrite the other (last writer wins)
+
+  The action exits with code 0 and emits no error or warning. The log shows both artifacts
+  downloading normally. The resulting corrupt file is indistinguishable from a valid one
+  unless explicitly checksummed.
+
+  Bug confirmed in actions/download-artifact#395 (March 2025, still open as of Jan 2026).
+  Affects: v4.x, v5.x, v6.x, v7.x
+
+  Common patterns that trigger this bug:
+  - Matrix builds across OS/arch each producing a same-named binary or manifest
+  - Release workflows where each artifact contains a same-named README.md or LICENSE
+  - Merge-and-sign workflows where each per-platform artifact has a checksums.txt
+fix: |
+  Option 1 — Rename artifact files to include OS/arch before uploading so no two
+  artifacts ever contain a file at the same relative path.
+
+  Option 2 — Download each artifact by name into a separate directory rather than using
+  merge-multiple: true.
+
+  Option 3 — Validate checksums of all critical files after downloading and before
+  using them, so corruption is detected rather than silently propagated.
+
+  Option 4 — Use pattern: to download specific artifact subsets one group at a time,
+  ensuring no overlapping filenames within each group.
+fix_code:
+  - language: yaml
+    label: 'Include OS/arch in output filenames to eliminate same-path collisions'
+    code: |
+      jobs:
+        build:
+          strategy:
+            matrix:
+              os: [ubuntu-latest, macos-latest, windows-latest]
+          runs-on: ${{ matrix.os }}
+          steps:
+            - name: Build and rename output to include OS identifier
+              run: |
+                cp build/output dist/output-${{ runner.os }}-${{ runner.arch }}
+
+            - uses: actions/upload-artifact@v4
+              with:
+                name: build-${{ runner.os }}-${{ runner.arch }}
+                path: dist/output-${{ runner.os }}-${{ runner.arch }}
+
+        release:
+          needs: build
+          runs-on: ubuntu-latest
+          steps:
+            - name: Download all artifacts (safe — all filenames are unique)
+              uses: actions/download-artifact@v4
+              with:
+                pattern: build-*
+                path: dist/
+                merge-multiple: true
+  - language: yaml
+    label: 'Download each artifact by name into a separate directory (avoids merge-multiple entirely)'
+    code: |
+      jobs:
+        release:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/download-artifact@v4
+              with:
+                name: build-Linux
+                path: dist/linux/
+
+            - uses: actions/download-artifact@v4
+              with:
+                name: build-macOS
+                path: dist/macos/
+
+            - uses: actions/download-artifact@v4
+              with:
+                name: build-Windows
+                path: dist/windows/
+
+            # Files are in separate directories — no parallel write collision possible
+prevention:
+  - 'Always include a unique dimension (OS, arch, matrix value) in filenames when uploading from matrix jobs'
+  - 'Audit all artifacts before using merge-multiple: true to confirm no two artifacts share a file path'
+  - 'Verify checksums of all merged files before using them in signing, publishing, or deployment steps'
+  - 'Prefer downloading by name into separate directories over merge-multiple when file collisions are possible'
+docs:
+  - url: 'https://github.com/actions/download-artifact/issues/395'
+    label: 'actions/download-artifact#395: merge-multiple silently corrupts files when same-named files exist (open, March 2025)'
+  - url: 'https://github.com/actions/download-artifact/blob/main/docs/MIGRATION.md#merging-multiple-artifacts'
+    label: 'download-artifact migration guide: Merging multiple artifacts'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflows-do/storing-workflow-data-as-artifacts'
+    label: 'GitHub Docs: Storing workflow data as artifacts'

package/errors/silent-failures/step-summary-content-silently-dropped-near-limit.yml

@@ -0,0 +1,115 @@
+id: 'silent-failures-039'
+title: '`GITHUB_STEP_SUMMARY` content silently discarded when write size approaches the 1 MiB per-step limit'
+category: silent-failures
+severity: silent-failure
+tags:
+  - step-summary
+  - github-step-summary
+  - silent-discard
+  - 1mib-limit
+  - job-summary
+  - reporting
+patterns:
+  - regex: 'GITHUB_STEP_SUMMARY'
+    flags: 'i'
+  - regex: '\$env:GITHUB_STEP_SUMMARY'
+    flags: 'i'
+error_messages:
+  - 'Summary content written to /home/runner/work/_temp/_github_workflow/step_summary_*.md'
+  - 'Summary content written to C:\Users\runneradmin\AppData\Local\Temp\_github_workflow\step_summary_*.md'
+root_cause: |
+  The GitHub Actions runner enforces a 1 MiB (1,048,576 bytes) per-step size limit on
+  GITHUB_STEP_SUMMARY content. When a step writes content that is within approximately
+  2 bytes of this limit, the runner silently discards the entire summary with no error
+  message, no warning, and no non-zero exit code.
+
+  Two distinct bugs are present (both observed on runner 2.333.1+):
+
+  Bug 1 — Off-by-one at the limit boundary: Content that is exactly (1 MiB - 1) bytes
+  is rejected as "too long" even though it is one byte below the documented limit.
+  The effective hard limit is (1 MiB - 2) bytes, not 1 MiB.
+
+  Bug 2 — Silent discard near the boundary: Content written when the running total is
+  within ~2 bytes of the effective limit is silently dropped. The write succeeds (no
+  error), the step exits 0, but the summary does not appear in the GitHub Actions UI.
+  There is no log line, annotation, or job-level error indicating the drop occurred.
+
+  This is particularly dangerous for CI workflows that rely on step summary for:
+  - Test result tables (many failed tests → large HTML tables)
+  - Build logs written to summary for easy access
+  - Deployment manifests or diff outputs
+  - Security scan results
+
+  The content is lost at job execution time; there is no way to recover it after the fact.
+  The only indication is that the summary section in the GitHub UI appears blank or shows
+  less content than expected.
+
+  Tracked in actions/runner#4337 (April 2026, open).
+fix: |
+  Truncate summary content to a safe size before writing to GITHUB_STEP_SUMMARY.
+  Leave a margin of ~5 KB below the 1 MiB limit to account for multi-step accumulation
+  and the off-by-one bug.
+
+  For multi-step workflows, track cumulative size: each step's contribution adds to the
+  total step summary for the job. The 1 MiB limit applies per step, not per job.
+
+  Always validate that critical summary content was written by checking the file size
+  after the write, not by relying on exit code alone.
+fix_code:
+  - language: yaml
+    label: 'Truncate step summary to safe size before writing (bash)'
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Run tests and write summary
+              run: |
+                # Generate potentially large summary content
+                content=$(cat test-results.md 2>/dev/null || echo "No results")
+
+                # Enforce safe limit: 1 MiB minus 10 KB buffer
+                max_bytes=$(( 1048576 - 10240 ))
+                content_bytes=${#content}
+
+                if [ "$content_bytes" -gt "$max_bytes" ]; then
+                  content="${content:0:$max_bytes}"
+                  content="${content}"$'\n\n> **Note:** Summary truncated — exceeded safe 1 MiB limit.'
+                fi
+
+                printf '%s' "$content" >> "$GITHUB_STEP_SUMMARY"
+  - language: yaml
+    label: 'Truncate step summary to safe size before writing (PowerShell)'
+    code: |
+      jobs:
+        test:
+          runs-on: windows-latest
+          steps:
+            - name: Write test summary with size guard
+              shell: pwsh
+              run: |
+                $content = Get-Content test-results.md -Raw -ErrorAction SilentlyContinue
+                if (-not $content) { $content = "No test results found." }
+
+                # Safe limit: 1 MiB minus 10 KB buffer (accounts for off-by-one bug)
+                $maxBytes = 1048576 - 10240
+                $bytes = [System.Text.Encoding]::UTF8.GetByteCount($content)
+
+                if ($bytes -gt $maxBytes) {
+                  # Truncate and add warning marker
+                  $truncated = $content.Substring(0, [Math]::Min($content.Length, $maxBytes / 2))
+                  $content = $truncated + "`n`n> **Note:** Summary truncated — exceeded safe 1 MiB limit."
+                }
+
+                $content | Out-File -Append -FilePath $env:GITHUB_STEP_SUMMARY -Encoding utf8
+prevention:
+  - 'Always apply a size guard before writing to GITHUB_STEP_SUMMARY — use (1 MiB - 10 KB) as a safe upper bound'
+  - 'For test result summaries, limit to the N most-recent or most-critical failures rather than dumping all output'
+  - 'Verify critical summary writes by checking file size after the write step, not by relying on exit code 0'
+  - 'Track actions/runner#4337 for a runner fix that either raises the limit or surfaces an error when content is discarded'
+  - 'Split large summaries across multiple steps — but note each step has its own 1 MiB budget, not a shared pool'
+docs:
+  - url: 'https://github.com/actions/runner/issues/4337'
+    label: 'actions/runner#4337: GITHUB_STEP_SUMMARY content silently dropped when size approaches 1 MiB limit (April 2026)'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#adding-a-job-summary'
+    label: 'GitHub Docs: Adding a job summary — GITHUB_STEP_SUMMARY documentation and limits'

package/errors/triggers/copilot-coding-agent-workflows-require-approval.yml

@@ -0,0 +1,104 @@
+id: 'triggers-027'
+title: 'Copilot coding agent PR workflows stuck in `action_required` — require human approval before running'
+category: triggers
+severity: error
+tags:
+  - copilot
+  - coding-agent
+  - approval-required
+  - action-required
+  - pull-request
+  - workflow-approval
+patterns:
+  - regex: 'action_required'
+    flags: 'i'
+  - regex: 'waiting for approval.*(?:outside contributor|fork|bot)|Approve and run'
+    flags: 'i'
+error_messages:
+  - 'This workflow is waiting for approval from a maintainer. Learn more about approving workflows from public forks.'
+  - 'Workflow run is in action_required state. Approval is required before jobs can start.'
+root_cause: |
+  Starting April 2025, GitHub treats the Copilot coding agent as an "outside contributor"
+  for GitHub Actions workflow approval purposes — the same policy applied to first-time
+  contributors from public forks.
+
+  When Copilot coding agent opens a pull request or pushes commits to a branch:
+  - Associated CI/CD workflows do NOT run automatically
+  - The check suite is created with conclusion: action_required
+  - No jobs start until a human with repository write access (or actions:write) manually
+    clicks "Approve and run workflows" in the PR UI, or approves via the REST API
+  - Unapproved runs are automatically deleted after 30 days with no notification
+
+  This is by design: Copilot-triggered workflows may have access to GITHUB_TOKEN,
+  repository secrets, and deployment environments. The approval gate prevents a
+  compromised or misbehaving AI agent from triggering arbitrary CI/CD actions.
+
+  However, this significantly slows AI-assisted development loops where developers rely
+  on CI feedback to validate Copilot's work. Teams discover this when:
+  - All Copilot-opened PRs show "Waiting for approval" with no CI results
+  - Required status checks never populate, blocking PR merges
+  - Automated pipelines that expected CI to run on all PRs silently stall
+
+  Affects: all GitHub Actions workflows triggered by pull_request, push, or
+  pull_request_target events on branches where Copilot coding agent is the commit author.
+fix: |
+  Option 1 (Recommended for trusted private repos): Enable automatic workflow runs for
+  Copilot coding agent in repository settings:
+  Settings → Actions → General → "Approval for running workflows triggered by Copilot
+  coding agent" → "Allow Copilot coding agent to trigger workflows without approval"
+  (Available since March 2026 changelog)
+
+  Option 2: Manually approve each run after Copilot opens a PR.
+  In the PR, click "Approve and run workflows" in the Checks section.
+
+  Option 3: Build a lightweight auto-approve workflow triggered by check_suite events
+  with action: requested, scoped to Copilot actor identity.
+fix_code:
+  - language: yaml
+    label: 'Approve a pending workflow run via GitHub CLI'
+    code: |
+      # List runs awaiting approval on a Copilot PR branch:
+      # gh run list --repo owner/repo --branch copilot/issue-123
+
+      # Approve a specific run (requires write access):
+      # gh run review <run-id> --approve --repo owner/repo
+
+      # Or approve via REST API:
+      # POST /repos/{owner}/{repo}/actions/runs/{run_id}/approve
+  - language: yaml
+    label: 'Auto-approve workflow: trigger CI immediately on Copilot PRs (use with caution)'
+    code: |
+      name: Auto-approve Copilot workflows
+      on:
+        workflow_run:
+          workflows: ['CI']
+          types: [requested]
+
+      jobs:
+        approve:
+          runs-on: ubuntu-latest
+          # Only auto-approve if triggered by Copilot coding agent
+          if: github.event.workflow_run.actor.login == 'copilot-swe-agent[bot]'
+          permissions:
+            actions: write
+          steps:
+            - name: Approve the workflow run
+              env:
+                RUN_ID: ${{ github.event.workflow_run.id }}
+                GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+              run: |
+                gh run review $RUN_ID --approve --repo ${{ github.repository }}
+prevention:
+  - 'Configure the "Allow Copilot coding agent to trigger workflows without approval" setting if your team uses Copilot heavily and the repo is trusted'
+  - 'Monitor for action_required check suite conclusions so stalled Copilot PRs do not block merges silently'
+  - 'Scope GITHUB_TOKEN permissions to the minimum required before enabling auto-approval, to reduce the blast radius if Copilot misbehaves'
+  - 'Set up required status checks carefully — if CI never runs, required checks will block PR merges indefinitely'
+docs:
+  - url: 'https://github.blog/changelog/2025-04-15-upcoming-breaking-changes-and-releases-for-github-actions/'
+    label: 'GitHub Changelog: Copilot events not automatically triggering GitHub Actions workflows (April 2025)'
+  - url: 'https://github.blog/changelog/2026-03-13-optionally-skip-approval-for-copilot-coding-agent-actions-workflows/'
+    label: 'GitHub Changelog: Optionally skip approval for Copilot coding agent Actions workflows (March 2026)'
+  - url: 'https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/approving-workflow-runs-from-public-forks'
+    label: 'GitHub Docs: Approving workflow runs from public forks'
+  - url: 'https://docs.github.com/en/copilot/using-github-copilot/using-copilot-coding-agent-to-work-on-tasks/configuring-settings-for-github-copilot-coding-agent'
+    label: 'GitHub Docs: Configuring settings for GitHub Copilot coding agent'

package/package.json

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