@htekdev/actions-debugger 1.0.112 → 1.0.114

package/errors/runner-environment/cache-restore-windows-runner-silent-crash.yml

@@ -0,0 +1,130 @@
+id: runner-environment-196
+title: 'actions/cache restore silently crashes Windows runner — job jumps to Post cleanup with no error'
+category: runner-environment
+severity: silent-failure
+tags:
+  - cache
+  - windows
+  - crash
+  - silent-failure
+  - cargo
+  - large-cache
+  - post-cleanup
+patterns:
+  - regex: 'Cache hit for:.*\n(?:.*\n){0,3}Post job cleanup'
+    flags: 'i'
+  - regex: 'Cache hit for:[\s\S]{0,200}Post job cleanup'
+    flags: 'i'
+  - regex: 'Cache up-to-date\.\s*\(node:\d+\) \[DEP0040\] DeprecationWarning.*punycode'
+    flags: 'i'
+error_messages:
+  - 'Cache hit for: [key]'
+  - 'Post job cleanup.'
+  - 'Cache up-to-date.'
+root_cause: |
+  On Windows GitHub-hosted runners, actions/cache@v5 can silently crash the Node.js
+  runner process during cache restore when extracting very large cache archives (multi-GB
+  caches, e.g. Rust/Cargo registry + cache, large Maven/Gradle dependency trees).
+
+  The failure manifests as the job jumping directly from "Cache hit for: [key]" to
+  "Post job cleanup." with no intervening restore log lines and no error message.
+  The step exits with code 0 (success), but the cache was never extracted. Subsequent
+  build steps fail with missing dependency errors (e.g. "error: no such file or directory:
+  ~/.cargo/registry") rather than a cache-related error, making the root cause opaque.
+
+  The log sequence for affected runs:
+  1. "Cache hit for: [cache-key]"  (restore begins)
+  2. [no tar extraction log lines]
+  3. "Post job cleanup."            (job finishes or runner crashes)
+  4. "Cache up-to-date."
+  5. "(node:XXXX) [DEP0040] DeprecationWarning: The `punycode` module is deprecated"
+  6. "Post job cleanup."
+
+  Root cause analysis: The Windows runner process (Runner.Worker.exe) terminates
+  abnormally during tar/zstd decompression of the cache archive. This appears to be a
+  memory-related crash (similar to the Windows heap corruption pattern in upload-artifact,
+  tracked in toolkit#2406) triggered by the high memory pressure of decompressing large
+  archives within the Node.js 20 heap on Windows runners as of May 2026.
+
+  The crash is non-deterministic (intermittent) — the same cache key may restore
+  successfully on retry. Affected cache sizes are typically 1 GB+ uncompressed.
+  Rust Cargo caches (registry/index + registry/cache + git/db) are the most commonly
+  reported trigger.
+
+  Source: actions/cache#1754 (May 2026, Windows runner, Cargo cache).
+fix: |
+  Short-term workaround: Add `continue-on-error: true` to the cache restore step.
+  The job will proceed to the build step which will then reinstall dependencies from
+  scratch. The build takes longer but completes reliably.
+
+  Preferred workaround: Split the cache into smaller chunks. Rust/Cargo caches can be
+  split by caching registry/index, registry/cache, and git/db in separate cache steps
+  with different keys, keeping each archive under ~500 MB.
+
+  Alternative: Use sccache or a remote cache (e.g. Cloudflare R2 + sccache) instead of
+  actions/cache for Rust builds on Windows — this avoids large local archives entirely.
+
+  Long-term: Track actions/cache#1754 for an upstream fix. Adding
+  `ACTIONS_STEP_DEBUG: true` as a repository secret may reveal the crash signal in
+  verbose runner logs.
+fix_code:
+  - language: yaml
+    label: 'Short-term: continue-on-error to prevent job failure on crash'
+    code: |
+      - name: Restore Cargo cache
+        uses: actions/cache@v5
+        continue-on-error: true   # Job proceeds even if cache restore crashes
+        with:
+          path: |
+            ~/.cargo/registry/index/
+            ~/.cargo/registry/cache/
+            ~/.cargo/git/db/
+            target/
+          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: ${{ runner.os }}-cargo-
+
+  - language: yaml
+    label: 'Split large Cargo cache into smaller chunks to avoid crash threshold'
+    code: |
+      - name: Restore Cargo registry index (small, fast)
+        uses: actions/cache@v5
+        with:
+          path: ~/.cargo/registry/index/
+          key: ${{ runner.os }}-cargo-index-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: ${{ runner.os }}-cargo-index-
+
+      - name: Restore Cargo registry cache (large packages)
+        uses: actions/cache@v5
+        continue-on-error: true
+        with:
+          path: ~/.cargo/registry/cache/
+          key: ${{ runner.os }}-cargo-cache-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: ${{ runner.os }}-cargo-cache-
+
+      - name: Restore Cargo git sources
+        uses: actions/cache@v5
+        continue-on-error: true
+        with:
+          path: ~/.cargo/git/db/
+          key: ${{ runner.os }}-cargo-git-${{ hashFiles('**/Cargo.lock') }}
+
+      - name: Restore build target dir
+        uses: actions/cache@v5
+        continue-on-error: true
+        with:
+          path: target/
+          key: ${{ runner.os }}-cargo-target-${{ hashFiles('**/Cargo.lock') }}
+
+prevention:
+  - 'Keep individual cache archives under ~500 MB by splitting large dependency trees (Cargo, Maven, Gradle) into multiple cache steps'
+  - 'Add continue-on-error: true to cache restore steps on Windows runners as a safety net for intermittent crashes'
+  - 'Monitor workflow durations — a sudden increase in Windows build time (cache miss equivalent) with no cache-related error in logs is a symptom of this crash'
+  - 'For Rust/Cargo on Windows runners, consider sccache with a remote backend to avoid large local cache archives entirely'
+  - 'Enable ACTIONS_STEP_DEBUG=true (as repository secret) to capture runner-level crash signals when this failure is suspected'
+docs:
+  - url: 'https://github.com/actions/cache/issues/1754'
+    label: 'actions/cache#1754 — Windows runner randomly dies during cache restore (May 2026)'
+  - url: 'https://github.com/actions/cache#tips-for-using-cache'
+    label: 'actions/cache — usage tips and cache size guidance'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows'
+    label: 'Caching dependencies — limits and best practices'

package/errors/runner-environment/git-248-fetch-tags-shallow-clone-regression.yml

@@ -0,0 +1,100 @@
+id: runner-environment-190
+title: 'Git 2.48.0 silently stops fetching tags with fetch-tags: true on non-depth-1 shallow clones'
+category: runner-environment
+severity: silent-failure
+tags:
+  - git-version
+  - fetch-tags
+  - shallow-clone
+  - fetch-depth
+  - ubuntu-24.04
+  - regression
+  - checkout
+patterns:
+  - regex: 'git version 2\.48\.'
+    flags: 'i'
+  - regex: 'fetch-tags.*fetch-depth|fetch-depth.*fetch-tags'
+    flags: 'i'
+error_messages:
+  - "# No error — tags are silently absent after checkout with fetch-tags: true and fetch-depth: N on git 2.48.0"
+  - "fatal: No names found, cannot describe anything."
+  - "fatal: not a tag 'HEAD'"
+root_cause: |
+  Git 2.48.0 introduced a change in how `git fetch --depth=N` handles tag following for
+  direct refspec fetches. In git ≤ 2.47.x, when actions/checkout ran:
+
+    git fetch --depth=N origin +<sha>:refs/remotes/origin/<branch>
+
+  git would automatically follow tags reachable within the depth window — any tag pointing
+  to a commit within the fetched depth was included. This is known as automatic tag following.
+
+  Starting with git 2.48.0, automatic tag following is suppressed for direct refspec fetches
+  with `--depth`. Only the explicitly requested ref is fetched; no tags are included even if
+  they point to commits within the shallow clone window. The fetch log shows only the branch
+  ref fetched — no tag lines appear.
+
+  Result: `fetch-tags: true` combined with `fetch-depth: N` (where N > 1, such as 100, 383, 500)
+  silently returns no tags on runner images shipping git 2.48.0. The workflow log shows no error
+  and no warning — `git tag -l` returns empty. Downstream steps using git describe, semantic-release,
+  helm chart versioning, or any tool that reads git tags break with "no names found" or
+  "not a tag 'HEAD'" errors.
+
+  This regression first appeared when ubuntu-24.04 runner image updated from 20250105.1.0 to
+  20250113.1.0 (which shipped git 2.48.0). The issue was resolved in runner image 20250117.1.0+
+  when git was updated to 2.48.1 which patched the regression. Self-hosted runners running
+  git 2.48.0 remain affected.
+
+  Note: This is distinct from the existing known silent failure where fetch-depth: 1 silently
+  fetches no tags regardless of git version. That is expected shallow-clone behavior. This
+  regression affects fetch-depth: N > 1 scenarios that previously worked.
+fix: |
+  Use `fetch-depth: 0` when git tags are required. A full clone fetches all history and all
+  tags regardless of git version. This is the most reliable fix.
+
+  For large repositories where a full clone is too slow, add a separate fetch --tags step
+  immediately after checkout to explicitly fetch all tag objects:
+
+    git fetch --tags --force
+
+  Self-hosted runners on git 2.48.0 should upgrade to git 2.48.1 or later which patches
+  the tag following regression.
+fix_code:
+  - language: yaml
+    label: 'Use fetch-depth: 0 for reliable tag fetching (recommended)'
+    code: |
+      - name: Checkout with full history and all tags
+        uses: actions/checkout@v4
+        with:
+          # fetch-depth: 0 always fetches all commits and tags regardless of git version
+          fetch-depth: 0
+  - language: yaml
+    label: 'Add explicit git fetch --tags step after shallow checkout'
+    code: |
+      - name: Checkout (shallow)
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 100
+          # fetch-tags: true is unreliable on git 2.48.0 — use explicit fetch instead
+
+      - name: Fetch tags explicitly (git-version-safe)
+        run: git fetch --tags --force
+  - language: yaml
+    label: 'Check git version in CI for debugging'
+    code: |
+      - name: Debug git version and tags
+        run: |
+          git --version
+          git tag -l | head -20
+          git describe --tags --always || echo "No reachable tags"
+prevention:
+  - 'Always use fetch-depth: 0 when git tags are required by downstream steps like git describe or semantic-release'
+  - 'Add a git tag -l debug step after checkout to verify tags are present before release tooling runs'
+  - 'For self-hosted runners, prefer git 2.48.1+ over 2.48.0 — the regression was patched in 2.48.1'
+  - 'Pin to fetch-depth: 0 in release workflows — the performance cost of a full clone is worth the reliability'
+docs:
+  - url: 'https://github.com/actions/checkout/issues/2041'
+    label: 'actions/checkout#2041: Tags no longer fetch with Git v2.48.0'
+  - url: 'https://github.com/actions/checkout#usage'
+    label: 'actions/checkout — fetch-depth and fetch-tags input documentation'
+  - url: 'https://git-scm.com/docs/git-fetch#_description'
+    label: 'git fetch documentation — tag following with --depth'

package/errors/runner-environment/javascript-actions-alpine-arm64-not-supported.yml

@@ -0,0 +1,121 @@
+id: runner-environment-195
+title: 'JavaScript Actions in Alpine containers not supported on ARM64 runners'
+category: runner-environment
+severity: error
+tags:
+  - alpine
+  - arm64
+  - javascript-action
+  - container
+  - ubuntu-24.04-arm
+  - musl
+patterns:
+  - regex: 'JavaScript Actions in Alpine containers are only supported on x64 Linux runners'
+    flags: 'i'
+  - regex: 'Detected Linux Arm64'
+    flags: 'i'
+  - regex: 'JavaScript Actions in Alpine containers.*Detected Linux'
+    flags: 'i'
+error_messages:
+  - 'Error: JavaScript Actions in Alpine containers are only supported on x64 Linux runners. Detected Linux Arm64'
+root_cause: |
+  The Actions runner's container hook for JavaScript-based actions (actions that use
+  `using: node20` or `using: node24` in their action.yml) includes a hard platform check
+  when the container image is detected as Alpine Linux.
+
+  Alpine Linux uses musl libc instead of glibc. The Node.js binaries bundled inside
+  GitHub-hosted Actions runners are compiled against glibc and cannot run inside Alpine
+  containers without compatibility shims. The runner guards against this by rejecting
+  JavaScript action execution in Alpine containers that are not on x64 Linux, where a
+  limited musl-compatibility workaround exists.
+
+  On ARM64 runners (ubuntu-24.04-arm, ubuntu-22.04-arm), the runner explicitly rejects
+  JavaScript actions run inside Alpine containers with this error. The check evaluates the
+  container image's /etc/os-release ID field: when ID=alpine is found AND the runner
+  architecture is not x64, the error is thrown.
+
+  Common trigger patterns:
+  - Workflow uses `container: alpine` or a custom image FROM alpine
+  - One or more steps use JavaScript-based actions (e.g. actions/upload-artifact,
+    actions/checkout, actions/setup-node)
+  - Workflow or matrix includes ubuntu-24.04-arm or ubuntu-22.04-arm runners
+
+  Upgrading to a larger ubuntu-based base image resolves the issue because glibc is
+  present. There is no planned fix to add ARM64 Alpine support to the runner.
+fix: |
+  Option 1 (recommended): Replace the Alpine container with a Debian/Ubuntu-based image.
+  Alpine is often chosen for image size, but if JavaScript actions must be used inside the
+  container, a glibc-based image is required on ARM64 runners.
+
+  Option 2: Run JavaScript actions as host-level steps (outside the container) and
+  restrict container use to run: shell steps that do not invoke JS actions.
+
+  Option 3: Restrict ARM64 runners to non-Alpine container images in your matrix.
+
+  Option 4: If the Alpine container is only for the build environment, restructure the
+  workflow so JavaScript actions (checkout, upload-artifact, etc.) run before the
+  container is started rather than inside it.
+fix_code:
+  - language: yaml
+    label: 'Replace Alpine with Debian-slim (smallest glibc image)'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-24.04-arm
+          container:
+            # Replace: image: alpine:latest
+            image: debian:bookworm-slim   # glibc-based, JS actions work on ARM64
+          steps:
+            - uses: actions/checkout@v6
+            - run: apt-get update && apt-get install -y curl
+            - uses: actions/upload-artifact@v4
+              with:
+                name: output
+                path: dist/
+
+  - language: yaml
+    label: 'Run JS actions on host, only use Alpine container for build steps'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-24.04-arm
+          steps:
+            # Checkout on host (no container) — JS action works fine
+            - uses: actions/checkout@v6
+            # Run build inside Alpine via docker run (shell step, not JS action)
+            - name: Build in Alpine
+              run: |
+                docker run --rm -v "$GITHUB_WORKSPACE:/work" -w /work \
+                  alpine:latest sh -c "apk add --no-cache build-base && make"
+            # Upload on host — JS action works fine
+            - uses: actions/upload-artifact@v4
+              with:
+                name: output
+                path: dist/
+
+  - language: yaml
+    label: 'Matrix: restrict Alpine container to x64 runners only'
+    code: |
+      jobs:
+        build:
+          runs-on: ${{ matrix.runner }}
+          container:
+            image: ${{ matrix.runner == 'ubuntu-24.04-arm' && 'debian:bookworm-slim' || 'alpine:latest' }}
+          strategy:
+            matrix:
+              runner: [ubuntu-24.04, ubuntu-24.04-arm]
+          steps:
+            - uses: actions/checkout@v6
+
+prevention:
+  - 'Never use Alpine-based container images on ARM64 GitHub-hosted runners if any workflow step calls a JavaScript action'
+  - 'Use debian:bookworm-slim or ubuntu:24.04 as a lightweight glibc alternative to Alpine when JS actions must run in-container on ARM64'
+  - 'When migrating workflows to ARM64 runners, audit all container: image values for Alpine derivation (FROM alpine, alpine:latest, alpine:3.x)'
+  - 'Run JavaScript actions (checkout, upload-artifact, setup-*) as host-level steps before or after the Alpine container block when possible'
+docs:
+  - url: 'https://github.com/actions/upload-artifact/issues/739'
+    label: 'actions/upload-artifact#739 — JS Actions in Alpine containers not supported on ARM64 (Feb 2026)'
+  - 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: 'GitHub-hosted runners — ARM64 runner support'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/running-jobs-in-a-container'
+    label: 'Running jobs in a container'

package/errors/runner-environment/runner-environment-185.yml

@@ -0,0 +1,88 @@
+id: runner-environment-185
+title: "Node.js 18 Removed from Toolcache After EOL — setup-node Falls Back to Slow Download or Times Out"
+category: runner-environment
+severity: error
+tags:
+  - nodejs
+  - node18
+  - toolcache
+  - eol
+  - setup-node
+  - runner-images
+patterns:
+  - regex: "Unable to find Node version '18|Couldn't find a version that satisfied.*18"
+    flags: i
+  - regex: 'Acquiring 18\.[0-9]+\.[0-9]+ - (x64|arm64) from.*node-versions'
+    flags: i
+  - regex: 'Client network socket disconnected before secure TLS connection was established'
+    flags: i
+  - regex: 'Request timeout.*node.*18|Error.*node.*18.*download'
+    flags: i
+error_messages:
+  - "Unable to find Node version '18' in the local cache."
+  - "Couldn't resolve the package 'node' to a version matching '18'"
+  - "Acquiring 18.20.4 - x64 from https://github.com/actions/node-versions/releases/download/18.20.4-xxxxxxxxxxxxxxxx/node-18.20.4-linux-x64.tar.gz"
+  - "Request timeout..."
+  - "Client network socket disconnected before secure TLS connection was established"
+root_cause: |
+  Node.js 18 reached end-of-life on **April 30, 2025**. GitHub subsequently removed it from the
+  pre-installed toolcache on all GitHub-hosted runner images (Ubuntu, macOS, and Windows). When
+  a workflow specifies `node-version: '18'` or `node-version: '18.x'`, the `actions/setup-node`
+  action cannot find Node 18 in the local toolcache and falls back to downloading the binary from
+  GitHub's node-versions release page. This remote download frequently times out on hosted runners
+  (the GitHub Releases endpoint for old Node versions is rate-limited under load), causing the step
+  to fail part-way through setup. On self-hosted runners without unrestricted outbound internet
+  access, the fallback download fails immediately with a TLS or connection error. The failure is
+  unexpected for teams that previously never pinned a `setup-node` step because Node 18 "just
+  worked" from the toolcache — after the removal, those workflows break silently on the next
+  runner image update. Distinct from `runner-environment-029` (Node.js 20 toolcache removal)
+  and `runner-environment-062` (ubuntu-latest default changing from Node 20 to 22).
+fix: |
+  Upgrade to a currently-supported Node.js LTS version. Node.js 22 is the current Active LTS
+  (supported until April 2027). Update the `node-version` field in your `setup-node` step and
+  verify your `package.json` `engines` field matches the new version:
+fix_code:
+  - language: yaml
+    label: "Upgrade to Node.js 22 (Active LTS)"
+    code: |
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+  - language: yaml
+    label: "Pin to .nvmrc / .node-version file for consistency"
+    code: |
+      # .nvmrc or .node-version in repo root:
+      # 22
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'npm'
+  - language: yaml
+    label: "Matrix test across supported LTS versions"
+    code: |
+      strategy:
+        matrix:
+          node-version: ['20', '22']
+      steps:
+        - uses: actions/setup-node@v4
+          with:
+            node-version: ${{ matrix.node-version }}
+prevention:
+  - "Subscribe to Node.js EOL announcements at https://nodejs.org/en/about/previous-releases to know when to migrate"
+  - "Use `node-version-file: '.nvmrc'` so your CI and local environments stay in sync automatically"
+  - "Enable Dependabot or Renovate to auto-bump `node-version` in workflow files when LTS versions rotate"
+  - "Prefer `lts/*` for non-version-sensitive workflows to always track the current LTS without manual updates"
+  - "Avoid relying on the toolcache for EOL versions — always add an explicit `setup-node` step"
+docs:
+  - url: "https://github.com/actions/setup-node"
+    label: "actions/setup-node"
+  - url: "https://nodejs.org/en/about/previous-releases"
+    label: "Node.js Release Schedule and EOL Dates"
+  - url: "https://github.com/actions/setup-node/issues/933"
+    label: "setup-node #933: Node 18 toolcache download timeout reports"
+  - url: "https://github.com/actions/runner-images"
+    label: "actions/runner-images — pre-installed toolcache contents"

package/errors/runner-environment/runner-environment-186.yml

@@ -0,0 +1,95 @@
+id: runner-environment-186
+title: "windows-2025 Runner Label Unexpectedly Includes VS 2026 — Pinned VS 2022 Paths Break"
+category: runner-environment
+severity: error
+tags:
+  - windows
+  - windows-2025
+  - visual-studio
+  - runner-image
+  - msbuild
+  - cmake
+  - breaking-change
+patterns:
+  - regex: 'Cannot find path.*Visual Studio\\2022.*because it does not exist'
+    flags: i
+  - regex: 'Visual Studio 2022.*not found|MSBuild.*17\.[0-9]+.*not available'
+    flags: i
+  - regex: 'CMake.*generator.*Visual Studio 17 2022.*not available'
+    flags: i
+  - regex: 'vswhere.*version.*\[17,18\).*returned empty|No valid VS instances found'
+    flags: i
+  - regex: 'MSB4019.*Microsoft\.CppBuild\.targets.*was not found'
+    flags: i
+error_messages:
+  - "Cannot find path 'C:\\Program Files\\Microsoft Visual Studio\\2022\\Enterprise\\MSBuild\\Microsoft\\VC' because it does not exist."
+  - "MSB4019: The imported project 'Microsoft.CppBuild.targets' was not found. Confirm that the expression in the Import declaration is correct."
+  - "CMake Error: CMake was unable to find a build program corresponding to \"Visual Studio 17 2022\"."
+  - "The C++ toolchain version 14.30 targeting platform 'x64' is not installed. Install it from the VS Installer."
+root_cause: |
+  In early 2026, some builds of the `windows-2025` runner image label began shipping with
+  Visual Studio 2026 (Public Preview) as the primary Visual Studio installation, removing or
+  demoting VS 2022 components that had been present in earlier `windows-2025` builds. Developers
+  who had explicitly pinned `runs-on: windows-2025` (rather than `windows-latest`) to preserve
+  VS 2022 compatibility found their workflows unexpectedly broken, because hardcoded paths to
+  `C:\Program Files\Microsoft Visual Studio\2022\...` no longer existed, and CMake generators
+  targeting "Visual Studio 17 2022" could not locate a matching installation.
+
+  This is distinct from the intentional `windows-latest` → VS 2026 migration documented in
+  `runner-environment-020`. In that case, developers pinned to a versioned label specifically
+  to avoid the change — the versioned label was supposed to be stable. The regression occurred
+  because `windows-2025` image builds that included VS 2026 were briefly pushed to the label's
+  rotation before being identified and rolled back.
+
+  Source: actions/runner-images#13638, actions/runner-images#14004.
+fix: |
+  Pin to `windows-2022` to guarantee a VS 2022 toolchain for the foreseeable future. Use
+  `vswhere.exe` to discover Visual Studio components at runtime rather than hardcoding
+  installation paths, which protects against future image changes on any Windows label.
+fix_code:
+  - language: yaml
+    label: "Pin to windows-2022 for guaranteed VS 2022"
+    code: |
+      jobs:
+        build:
+          # Use windows-2022 instead of windows-2025 to guarantee VS 2022 toolchain
+          runs-on: windows-2022
+  - language: yaml
+    label: "Use vswhere to discover MSBuild path at runtime"
+    code: |
+      - name: Locate MSBuild via vswhere
+        id: msbuild
+        shell: pwsh
+        run: |
+          $vswhere = "${env:ProgramFiles(x86)}\Microsoft Visual Studio\Installer\vswhere.exe"
+          $msbuild = & $vswhere -latest -requires Microsoft.Component.MSBuild `
+            -find MSBuild\**\Bin\MSBuild.exe | Select-Object -First 1
+          if (-not $msbuild) { throw "MSBuild not found via vswhere" }
+          "path=$msbuild" | Out-File -Append $env:GITHUB_OUTPUT
+
+      - name: Build solution
+        shell: pwsh
+        run: |
+          & "${{ steps.msbuild.outputs.path }}" MySolution.sln /p:Configuration=Release /p:Platform=x64
+  - language: yaml
+    label: "Use CMake with dynamic VS version detection"
+    code: |
+      - name: Configure CMake
+        run: |
+          # Let CMake auto-detect the installed VS version instead of pinning generator
+          cmake -B build -DCMAKE_BUILD_TYPE=Release
+        # Avoid: cmake -G "Visual Studio 17 2022" which fails if VS 2022 is absent
+prevention:
+  - "Use `vswhere.exe` to locate Visual Studio and MSBuild components at runtime — never hardcode installation paths"
+  - "Subscribe to the actions/runner-images releases feed to get notified when versioned labels are updated"
+  - "Avoid CMake `-G \"Visual Studio 17 2022\"` in favor of `cmake -B build` with auto-detection when possible"
+  - "For CUDA or other toolchain integrations that require a specific VS version, test on a matrix of runner labels to catch regressions early"
+docs:
+  - url: "https://github.com/actions/runner-images/issues/13638"
+    label: "runner-images #13638: windows-2025 label includes VS2026 regression report"
+  - url: "https://github.com/actions/runner-images/issues/14004"
+    label: "runner-images #14004: VS 2022 paths missing on windows-2025"
+  - url: "https://github.com/microsoft/vswhere"
+    label: "vswhere — Visual Studio locator (Microsoft)"
+  - url: "https://github.com/actions/runner-images/blob/main/images/windows/Windows2025-Readme.md"
+    label: "Windows Server 2025 Runner Image Readme"

package/errors/runner-environment/runner-environment-187.yml

@@ -0,0 +1,90 @@
+id: runner-environment-187
+title: "ubuntu-24.04 Runner Missing software-properties-common — add-apt-repository Not Found"
+category: runner-environment
+severity: error
+tags:
+  - ubuntu
+  - ubuntu-24.04
+  - apt
+  - ppa
+  - runner-image
+  - breaking-change
+patterns:
+  - regex: 'add-apt-repository.*not found|command not found.*add-apt-repository'
+    flags: i
+  - regex: '/bin/(sh|bash).*add-apt-repository.*not found'
+    flags: i
+  - regex: 'Unable to locate executable file: add-apt-repository'
+    flags: i
+  - regex: 'No such file or directory.*add-apt-repository'
+    flags: i
+error_messages:
+  - "/bin/sh: 1: add-apt-repository: not found"
+  - "bash: add-apt-repository: command not found"
+  - "Error: Unable to locate executable file: add-apt-repository"
+  - "/usr/bin/add-apt-repository: No such file or directory"
+root_cause: |
+  The `ubuntu-24.04` GitHub-hosted runner image does not pre-install `software-properties-common`,
+  the Debian/Ubuntu package that provides the `add-apt-repository` command. On `ubuntu-22.04`
+  runners, `software-properties-common` was included by default, so workflows that used
+  `add-apt-repository` to add third-party PPAs (e.g., `ppa:deadsnakes/ppa` for older Python
+  versions, `ppa:graphics-drivers/ppa` for NVIDIA drivers) worked without any explicit install
+  step. After migrating to `ubuntu-24.04` — either explicitly or when `ubuntu-latest` switched
+  from 22.04 to 24.04 in March 2025 — these workflows fail immediately with "command not found".
+
+  The failure message points at the `add-apt-repository` line, but the actual missing dependency
+  is the `software-properties-common` package. Other apt commands in the same step (like
+  `apt-get update`) succeed, making the root cause less obvious.
+fix: |
+  Install `software-properties-common` before calling `add-apt-repository`. For new workflows,
+  prefer adding apt source lists directly using a signing key, which does not require
+  `software-properties-common` and is more reproducible.
+fix_code:
+  - language: yaml
+    label: "Install software-properties-common before using add-apt-repository"
+    code: |
+      - name: Add PPA and install package
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y software-properties-common
+          sudo add-apt-repository -y ppa:deadsnakes/ppa
+          sudo apt-get update
+          sudo apt-get install -y python3.11 python3.11-venv
+  - language: yaml
+    label: "Preferred: add repository via source list (no software-properties-common needed)"
+    code: |
+      - name: Add repository via signed source list
+        run: |
+          # Download and install the repository GPG key
+          curl -fsSL https://example.com/gpg.key \
+            | sudo gpg --dearmor -o /usr/share/keyrings/example-archive-keyring.gpg
+
+          # Add the apt source list with the key reference
+          echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/example-archive-keyring.gpg] \
+            https://example.com/apt stable main" \
+            | sudo tee /etc/apt/sources.list.d/example.list > /dev/null
+
+          sudo apt-get update
+          sudo apt-get install -y example-package
+  - language: yaml
+    label: "Conditionally install software-properties-common (ubuntu-24.04 only)"
+    code: |
+      - name: Install apt prerequisites
+        run: |
+          # software-properties-common is not pre-installed on ubuntu-24.04
+          sudo apt-get install -y software-properties-common
+prevention:
+  - "Do not rely on `software-properties-common` being pre-installed — always add it as an explicit apt-get install step"
+  - "Prefer direct apt source list additions (with GPG key dearmoring) over PPAs for better reproducibility on ubuntu-24.04"
+  - "Verify pre-installed packages when migrating runner labels — check https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2404-Readme.md"
+  - "Test workflows explicitly on ubuntu-24.04 before relying on ubuntu-latest defaulting to 24.04"
+  - "Use `apt-get install -y --no-install-recommends` to keep explicit and minimal dependencies"
+docs:
+  - url: "https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2404-Readme.md"
+    label: "Ubuntu 24.04 Runner Image Readme — pre-installed packages list"
+  - url: "https://github.com/actions/runner-images/issues/9848"
+    label: "runner-images #9848: ubuntu-latest migration to ubuntu-24.04 tracking issue"
+  - url: "https://manpages.ubuntu.com/manpages/noble/man1/add-apt-repository.1.html"
+    label: "add-apt-repository man page (Ubuntu Noble)"
+  - url: "https://help.launchpad.net/Packaging/PPA/InstallingSoftware"
+    label: "Launchpad PPA Installation Guide"