@htekdev/actions-debugger 1.0.14 → 1.0.16

package/errors/runner-environment/setup-java-distribution-required.yml

@@ -0,0 +1,108 @@
+id: runner-environment-039
+title: "setup-java Fails with 'Distribution Input Value Is Required' After v1 to v2 Migration"
+category: runner-environment
+severity: error
+tags:
+  - setup-java
+  - java
+  - distribution
+  - breaking-change
+  - temurin
+  - adoptopenjdk
+  - v2-migration
+patterns:
+  - regex: "Distribution input value is required"
+    flags: "i"
+  - regex: "'distribution' must be one of:.*temurin|adopt|zulu|liberica|corretto|microsoft|semeru"
+    flags: "i"
+  - regex: "actions/setup-java.*distribution.*required"
+    flags: "i"
+  - regex: "Input required and not supplied: distribution"
+    flags: "i"
+error_messages:
+  - "Error: Distribution input value is required. 'distribution' must be one of: temurin, adopt, zulu, liberica, corretto, microsoft, semeru, dragonwell, sapmachine, graalvm"
+  - "Error: Input required and not supplied: distribution"
+root_cause: |
+  In `actions/setup-java` v2 (released 2021), the `distribution` input became mandatory.
+  In v1, AdoptOpenJDK was the implicit default distribution and no `distribution` key was
+  needed. When workflows that were written for v1 are updated to use @v2, @v3, or @v4 without
+  adding a `distribution:` input, the action fails immediately.
+
+  This also occurs when:
+  - An organization adopts setup-java for the first time using documentation examples from an
+    older blog post or tutorial that predates v2
+  - A Dependabot PR bumps setup-java from @v1 to @v3 or @v4 without updating the inputs
+  - Internal action templates or reusable workflows reference setup-java without distribution
+
+  Available distributions (as of 2024-2026):
+  - `temurin` — Eclipse Temurin (recommended, successor to AdoptOpenJDK)
+  - `zulu` — Azul Zulu OpenJDK
+  - `corretto` — Amazon Corretto
+  - `microsoft` — Microsoft Build of OpenJDK
+  - `liberica` — BellSoft Liberica JDK
+  - `semeru` — IBM Semeru Runtime
+  - `dragonwell` — Alibaba Dragonwell
+  - `sapmachine` — SAP Machine
+  - `graalvm` — GraalVM Community Edition
+  - `adopt` — Legacy AdoptOpenJDK alias (still supported but deprecated; use temurin instead)
+
+  Note: `adopt` (AdoptOpenJDK) was renamed/rebranded to Adoptium / Eclipse Temurin.
+  Using `distribution: adopt` still works but `distribution: temurin` is the modern equivalent.
+fix: |
+  Add the `distribution:` input to all `actions/setup-java` steps. Use `temurin` as the
+  recommended default (it is the open-source successor to AdoptOpenJDK hosted by Adoptium).
+
+  If you need to match your production environment's exact JDK distribution, choose the
+  corresponding option from the available distributions list.
+fix_code:
+  - language: yaml
+    label: "Add required distribution input to setup-java"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            # ❌ v1-style — fails on v2+
+            # - uses: actions/setup-java@v4
+            #   with:
+            #     java-version: '17'
+
+            # ✅ v2+ style — distribution is required
+            - uses: actions/setup-java@v4
+              with:
+                distribution: 'temurin'   # Eclipse Temurin (recommended)
+                java-version: '21'
+                cache: 'maven'            # optional: enables Maven dependency caching
+
+            - name: Build with Maven
+              run: mvn --batch-mode --update-snapshots package
+  - language: yaml
+    label: "Using Corretto (Amazon) or Zulu distributions"
+    code: |
+      # Amazon Corretto
+      - uses: actions/setup-java@v4
+        with:
+          distribution: 'corretto'
+          java-version: '21'
+
+      # Azul Zulu
+      - uses: actions/setup-java@v4
+        with:
+          distribution: 'zulu'
+          java-version: '17'
+prevention:
+  - "Always specify `distribution:` when using actions/setup-java v2 or later — there is no default."
+  - "Use `temurin` as the default distribution for open-source projects (it is the community-maintained successor to AdoptOpenJDK)."
+  - "When Dependabot bumps setup-java, check that the resulting PR also adds or preserves the `distribution:` input."
+  - "Review your org's reusable workflow templates and action wrappers for setup-java v1-style usage that lacks distribution."
+docs:
+  - url: "https://github.com/actions/setup-java/blob/main/docs/advanced-usage.md"
+    label: "actions/setup-java — advanced usage and distribution options"
+  - url: "https://github.com/actions/setup-java/releases/tag/v2.0.0"
+    label: "actions/setup-java v2.0.0 release notes (distribution became required)"
+  - url: "https://adoptium.net/"
+    label: "Eclipse Temurin (Adoptium) — recommended open-source JDK distribution"
+  - url: "https://stackoverflow.com/questions/69595609/github-actions-actions-setup-java-distribution-input-required"
+    label: "Stack Overflow — setup-java distribution input required error"

package/errors/runner-environment/ubuntu-2004-retirement-brownout.yml

@@ -0,0 +1,107 @@
+id: runner-environment-049
+title: "ubuntu-20.04 runner retired — jobs fail during brownouts or after full removal"
+category: runner-environment
+severity: error
+tags:
+  - ubuntu
+  - ubuntu-20-04
+  - runner-retirement
+  - image-removal
+  - brownout
+  - eol
+patterns:
+  - regex: "scheduled Ubuntu 20\\.04 retirement|Ubuntu 20\\.04.*retirement"
+    flags: "i"
+  - regex: "ubuntu-20\\.04.*removed|ubuntu-20\\.04.*unavailable"
+    flags: "i"
+  - regex: "ubuntu-20\\.04.*runner will be removed"
+    flags: "i"
+  - regex: "No hosted runner.*ubuntu-20|ubuntu-20\\.04.*no.*runner"
+    flags: "i"
+error_messages:
+  - "This is a scheduled Ubuntu 20.04 retirement. Ubuntu 20.04 LTS runner will be removed on 2025-04-15. For more details, see https://github.com/actions/runner-images/issues/11101"
+  - "ubuntu-20.04 is no longer available. Please use ubuntu-22.04 or ubuntu-24.04 instead."
+  - "No hosted runner was found that matches the requested labels: ubuntu-20.04"
+root_cause: |
+  Ubuntu 20.04 LTS (Focal Fossa) reached end of standard support on April 2,
+  2025. GitHub followed by retiring the ubuntu-20.04 GitHub-hosted runner
+  image on April 15, 2025, after a series of intentional brownout windows
+  that began in March 2025 (March 4, 11, 18, 25 and April 1, 8).
+
+  During each brownout window (13:00–21:00 UTC), any job using runs-on:
+  ubuntu-20.04 was deliberately failed with an explicit retirement message.
+  After April 15, 2025, the image was permanently removed and no longer
+  available as a runner label on GitHub.com.
+
+  Workflows that hardcode ubuntu-20.04 in their runs-on: field now fail
+  immediately with "No hosted runner was found that matches the requested
+  labels: ubuntu-20.04". This also affects:
+  - Actions pinned inside third-party repos that ship their own workflow
+    files using ubuntu-20.04
+  - Reusable workflow templates or starter workflows referencing ubuntu-20.04
+  - Matrix strategies that include ubuntu-20.04 as one of several OS targets
+  - Composite actions or action.yml files in public actions that list
+    ubuntu-20.04 as a required environment
+
+  Self-hosted runners with the ubuntu-20.04 label are NOT affected — they
+  only match the name locally and keep running as long as the self-hosted
+  runner agent is online.
+fix: |
+  Replace ubuntu-20.04 with ubuntu-22.04 or ubuntu-24.04 (ubuntu-latest).
+
+  For most workflows, ubuntu-22.04 is the most compatible drop-in replacement:
+  it shares glibc 2.35 which supports binaries built on Ubuntu 20. However,
+  several packages and tools differ between 20.04 and 22.04:
+  - Python 3.8 and 3.9 are no longer pre-installed on ubuntu-22.04+
+  - libssl1.1 is absent; libssl3 is the current version
+  - Some apt package versions differ
+
+  For ubuntu-24.04:
+  - Python 3.11 is the default (3.8/3.9/3.10 absent)
+  - libssl3 only
+  - Node 18 removed from toolcache
+
+  Run your workflow with ubuntu-22.04 first. Address any package-version
+  failures before migrating to ubuntu-24.04.
+fix_code:
+  - language: yaml
+    label: "Upgrade hardcoded ubuntu-20.04 references to ubuntu-22.04"
+    code: |
+      jobs:
+        build:
+          # Replace deprecated image with supported LTS
+          runs-on: ubuntu-22.04  # was: ubuntu-20.04
+          steps:
+            - uses: actions/checkout@v4
+            - name: Install dependencies
+              run: sudo apt-get install -y libssl-dev  # libssl3 on 22.04, libssl1.1 on 20.04
+            - run: make build
+  - language: yaml
+    label: "Migrate matrix strategy that included ubuntu-20.04"
+    code: |
+      jobs:
+        test:
+          strategy:
+            matrix:
+              os:
+                - ubuntu-22.04   # was ubuntu-20.04
+                - ubuntu-24.04   # was ubuntu-latest (if you want explicit LTS pin)
+                - windows-latest
+                - macos-latest
+          runs-on: ${{ matrix.os }}
+          steps:
+            - uses: actions/checkout@v4
+            - run: make test
+prevention:
+  - "Use ubuntu-latest instead of pinning specific Ubuntu versions to avoid hard failures on retirement"
+  - "If you need a specific Ubuntu LTS, pin to ubuntu-22.04 or ubuntu-24.04 — never a version past its support window"
+  - "Subscribe to runner-images retirement notifications on GitHub (watch actions/runner-images for Issues)"
+  - "Add a monthly workflow audit job that fails if any runs-on: references a known-retired image label"
+  - "Check third-party action.yml files in your dependency tree for hardcoded ubuntu-20.04 references"
+docs:
+  - url: "https://github.com/actions/runner-images/issues/11101"
+    label: "runner-images#11101 — Ubuntu 20.04 retirement announcement and timeline"
+  - url: "https://github.blog/changelog/2025-02-12-notice-of-upcoming-deprecations-and-breaking-changes-for-github-actions/"
+    label: "GitHub Changelog — Ubuntu 20.04 brownout schedule (Feb 2025)"
+  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources"
+    label: "GitHub Docs — Supported GitHub-hosted runner images"

package/errors/runner-environment/windows-latest-d-drive-removed.yml

@@ -0,0 +1,104 @@
+id: runner-environment-043
+title: "windows-latest Windows Server 2025 Runner Removed D: Drive — Paths Fail"
+category: runner-environment
+severity: error
+tags:
+  - windows
+  - runner-image
+  - d-drive
+  - path
+  - windows-server-2025
+  - breaking-change
+patterns:
+  - regex: "The system cannot find the path specified.*D:\\\\"
+    flags: "i"
+  - regex: "D:\\\\.*No such file or directory"
+    flags: "i"
+  - regex: "Path.*D:\\\\.*does not exist"
+    flags: "i"
+  - regex: "cannot find.*'D:\\\\|D:\\\\.*not found"
+    flags: "i"
+error_messages:
+  - "The system cannot find the path specified: 'D:\\a\\'"
+  - "D:\\a\\ : No such file or directory"
+  - "Cannot find path 'D:\\build' because it does not exist."
+  - "Error: ENOENT: no such file or directory, open 'D:\\tools\\...'"
+root_cause: |
+  The Windows Server 2025 runner image, which became the target of `windows-latest`
+  and `windows-2025` starting mid-2026, **removed the D: drive** that was present
+  on earlier Windows runner images (Windows Server 2019 and 2022).
+
+  On Windows Server 2019/2022 runners, the D: drive was a separate disk used for
+  temporary build storage and tools. Some workflows hardcoded paths like
+  `D:\a\`, `D:\tools\`, `D:\hostedtoolcache\`, or `D:\temp\` instead of using
+  environment variables like `${{ runner.tool_cache }}`, `$RUNNER_TOOL_CACHE`,
+  or workspace-relative paths.
+
+  On Windows Server 2025 runners, only the C: drive is available. Any workflow
+  step that writes to or reads from an absolute `D:\` path will immediately fail
+  with a path-not-found error, often as a confusing "system cannot find path" error
+  rather than a clear "D: drive missing" message.
+
+  Root issue thread: actions/runner-images#12416 (D: drive removal discussion)
+  and runner-images#12677 (windows-latest → Windows Server 2025 migration).
+fix: |
+  Replace all hardcoded `D:\` paths with environment variable references or
+  workspace-relative paths:
+
+  | Old (hardcoded D:) | New (portable)                          |
+  |--------------------|----------------------------------------|
+  | `D:\hostedtoolcache` | `${{ runner.tool_cache }}`          |
+  | `D:\a\${{ github.repository }}` | `${{ github.workspace }}`  |
+  | `D:\temp\`         | `${{ runner.temp }}`                   |
+  | `D:\tools\`        | Explicit installation to `C:\tools\`   |
+
+  For existing scripts that reference `D:\` directly, either:
+  1. Update all references to use RUNNER_TEMP, RUNNER_TOOL_CACHE, or GITHUB_WORKSPACE
+  2. Temporarily pin `runs-on: windows-2022` while you migrate
+fix_code:
+  - language: yaml
+    label: "Replace D:\\ paths with portable runner environment variables"
+    code: |
+      jobs:
+        build:
+          runs-on: windows-latest  # Works on Server 2025 (no D: drive)
+          steps:
+            - uses: actions/checkout@v4
+
+            # ❌ Broken: hardcoded D: path
+            # - run: Copy-Item -Path "D:\hostedtoolcache\node\20.0.0\x64\bin\node.exe" -Destination "${{ github.workspace }}"
+
+            # ✅ Fixed: use runner context variables
+            - name: Use portable paths
+              run: |
+                echo "Workspace: ${{ github.workspace }}"
+                echo "Tool cache: ${{ runner.tool_cache }}"
+                echo "Temp dir: ${{ runner.temp }}"
+                # C: drive is always available on all Windows runner images
+                $toolsDir = "C:\tools"
+                New-Item -ItemType Directory -Force -Path $toolsDir
+  - language: yaml
+    label: "Temporary rollback — pin to windows-2022 while migrating"
+    code: |
+      jobs:
+        build:
+          # Pin to windows-2022 (D: drive still present) while fixing hardcoded paths
+          runs-on: windows-2022
+          steps:
+            - uses: actions/checkout@v4
+            - run: msbuild MyProject.sln
+prevention:
+  - "Never hardcode `D:\\` paths in workflows or scripts — always use `${{ runner.tool_cache }}`, `${{ runner.temp }}`, `${{ github.workspace }}`, or `C:\\`-relative paths."
+  - "Audit workflows and called scripts for `D:\\` references before migrating to `windows-latest` (Windows Server 2025)."
+  - "Subscribe to actions/runner-images release announcements so runner image migrations do not catch you off-guard."
+  - "Use `windows-2022` as a temporary pin if immediate migration is not feasible; note that Server 2022 images have a defined EOL."
+  - "Test Windows workflows in a `windows-2025` matrix slot before the `windows-latest` migration window completes."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/12416"
+    label: "runner-images#12416 — D: drive removal discussion"
+  - url: "https://github.com/actions/runner-images/issues/12677"
+    label: "runner-images#12677 — windows-latest migration to Windows Server 2025"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables#default-environment-variables"
+    label: "GitHub Docs: Default environment variables (runner.tool_cache, runner.temp)"
+  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners#standard-github-hosted-runners-for-public-repositories"
+    label: "About GitHub-hosted runners — Windows Server 2025 specs"

package/errors/runner-environment/windows-vs2026-cuda-host-compiler-unsupported.yml

@@ -0,0 +1,145 @@
+id: runner-environment-046
+title: "CUDA nvcc Rejects Visual Studio 2026 Host Compiler on windows-latest"
+category: runner-environment
+severity: error
+tags:
+  - windows
+  - windows-latest
+  - cuda
+  - nvcc
+  - visual-studio-2026
+  - vs2026
+  - runner-image
+  - breaking-change
+  - gpu
+patterns:
+  - regex: "unsupported Microsoft Visual Studio version.*Only the versions between 2019 and 2022"
+    flags: "i"
+  - regex: "fatal error C1189.*unsupported Microsoft Visual Studio version"
+    flags: "i"
+  - regex: "nvcc.*error.*host_config\\.h.*C1189"
+    flags: "i"
+  - regex: "CUDA.*requires Visual Studio.*2022|nvcc.*does not support.*Visual Studio 18"
+    flags: "i"
+  - regex: "error:\\s+--\\s+unsupported Microsoft Visual Studio version"
+    flags: "i"
+error_messages:
+  - "fatal error C1189: #error:  -- unsupported Microsoft Visual Studio version! Only the versions between 2019 and 2022 (inclusive) are supported!"
+  - "Error in C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\v13.1\\include\\crt/host_config.h(164)"
+  - "nvcc fatal   : Host compiler targets unsupported OS."
+  - "nvcc error  : Failed to preprocess the host compiler properties."
+root_cause: |
+  GitHub Actions migrated `windows-latest` (and `windows-2025`) from Visual Studio 2022 to
+  Visual Studio 2026 (version 18.x) beginning June 8, 2026, completing by June 15, 2026.
+  Additionally, some users saw the switch as early as May 5, 2026 when `windows-2025`
+  started serving the `windows-2025-vs2026` image label prematurely (runner-images#14004).
+
+  CUDA toolkits up to and including CUDA 13.x hard-code supported Visual Studio version
+  ranges inside `<CUDA_ROOT>/include/crt/host_config.h`. The file checks the `_MSC_VER`
+  compiler macro and rejects any version outside the explicitly listed range. Visual Studio
+  2022 (MSVC 19.3x) is the last version supported by all CUDA releases through CUDA 13.x.
+  Visual Studio 2026 (MSVC 19.4x / VS version 18.x) falls outside these ranges and triggers
+  an immediate hard compiler error:
+
+    fatal error C1189: #error:  -- unsupported Microsoft Visual Studio version! Only the
+    versions between 2019 and 2022 (inclusive) are supported! The nvcc flag
+    '-allow-unsupported-compiler' can be used to override this version check; however,
+    using an unsupported host compiler may cause compilation failure or incorrect run time
+    execution. Use at your own risk.
+
+  The error fires at the preprocessing stage — before any CUDA code is compiled — so it
+  affects any project that invokes `nvcc`, regardless of the CUDA source code content.
+
+  Source: actions/runner-images#14017, runner-images#14004, NVIDIA CUDA Installation Guide
+fix: |
+  **Option 1 — Use `-allow-unsupported-compiler` flag** (quick unblock, use at own risk):
+  Adds a flag to nvcc that bypasses the version check. Works for many projects but NVIDIA
+  does not guarantee correctness with unsupported compilers.
+
+  **Option 2 — Pin to windows-2022** (safest immediate fix):
+  `windows-2022` still ships Visual Studio 2022. It is not yet deprecated.
+
+  **Option 3 — Upgrade to a CUDA version that supports VS 2026** (best long-term):
+  NVIDIA releases new CUDA toolkits that list VS 2026 in their supported compiler matrix.
+  Check the CUDA Toolkit Release Notes for the current supported VS version table.
+
+  **Option 4 — Use CMake's `CUDAARCHS` + VS2022 generator explicitly**:
+  If using CMake, pin the generator to `Visual Studio 17 2022` even on windows-latest by
+  specifying `-G "Visual Studio 17 2022"` in your cmake configure step. This forces CMake
+  to use the VS 2022 tools even if VS 2026 is the default.
+fix_code:
+  - language: yaml
+    label: "Pin to windows-2022 to avoid VS 2026 entirely"
+    code: |
+      jobs:
+        build-cuda:
+          runs-on: windows-2022   # VS 2022 — supported by CUDA up to 13.x
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Build with CUDA
+              run: cmake --build . --config Release
+  - language: yaml
+    label: "Pass -allow-unsupported-compiler to nvcc (quick unblock)"
+    code: |
+      jobs:
+        build-cuda:
+          runs-on: windows-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            # Pass flag via CMake CUDA_NVCC_FLAGS
+            - name: Configure CMake
+              run: |
+                cmake -B build -DCMAKE_CUDA_FLAGS="-allow-unsupported-compiler"
+
+            - name: Build
+              run: cmake --build build --config Release
+  - language: yaml
+    label: "Force VS 2022 CMake generator on windows-latest (VS 2026 image)"
+    code: |
+      jobs:
+        build-cuda:
+          runs-on: windows-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            # Explicitly select VS 2022 generator even when VS 2026 is default
+            - name: Configure with VS 2022 generator
+              run: |
+                cmake -B build `
+                  -G "Visual Studio 17 2022" `
+                  -A x64
+
+            - name: Build
+              run: cmake --build build --config Release
+  - language: yaml
+    label: "Upgrade CUDA toolkit version that supports VS 2026"
+    code: |
+      jobs:
+        build-cuda:
+          runs-on: windows-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            # Install a CUDA version that explicitly supports VS 2026
+            # (check NVIDIA release notes for the current minimum supported version)
+            - name: Install CUDA Toolkit
+              uses: Jimver/cuda-toolkit@v0.2.21
+              with:
+                cuda: '12.8.0'   # Check if this version lists VS 2026 in its support matrix
+
+            - name: Build
+              run: cmake --build build --config Release
+prevention:
+  - "Never assume CUDA is forward-compatible with new Visual Studio versions — CUDA hard-codes supported MSVC version ranges."
+  - "Pin `runs-on: windows-2022` for CUDA workflows until the CUDA version you use explicitly lists VS 2026 as supported."
+  - "Subscribe to runner-images#14017 and similar announcements before the windows-latest label migration date."
+  - "Check the CUDA Toolkit Release Notes for your version's supported host compiler table before upgrading either Visual Studio or CUDA."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/14017"
+    label: "runner-images#14017: windows-latest will use VS 2026 image in June 2026"
+  - url: "https://github.com/actions/runner-images/issues/14004"
+    label: "runner-images#14004: windows-2025 serving VS 2026 image prematurely (May 2026)"
+  - url: "https://docs.nvidia.com/cuda/cuda-installation-guide-microsoft-windows/"
+    label: "NVIDIA CUDA Installation Guide — supported Visual Studio versions"

package/errors/silent-failures/event-commits-empty-on-workflow-dispatch.yml

@@ -0,0 +1,110 @@
+id: silent-failures-018
+title: "github.event.commits and github.event.head_commit Are Null/Empty on Non-Push Triggers"
+category: silent-failures
+severity: silent-failure
+tags:
+  - github-context
+  - workflow-dispatch
+  - schedule
+  - commits
+  - null-access
+  - push-event
+  - expression
+patterns:
+  - regex: "github\\.event\\.commits\\[0\\]"
+    flags: "i"
+  - regex: "github\\.event\\.head_commit\\.(message|id|author)"
+    flags: "i"
+  - regex: "github\\.event\\.commits is not iterable|Cannot read.*commits"
+    flags: "i"
+error_messages:
+  - "Error: Cannot read properties of undefined (reading 'message')"
+  - "Error: github.event.commits[0] is undefined"
+root_cause: |
+  The `github.event.commits` array and `github.event.head_commit` object are ONLY populated
+  for `push` webhook events. They are absent (null / empty array) for all other trigger types:
+
+  - `workflow_dispatch` — manual UI or API trigger, no commit context
+  - `schedule` — cron-triggered run, no specific push associated
+  - `pull_request` / `pull_request_target` — uses github.event.pull_request instead
+  - `workflow_call` — reusable workflow invocation, no commit array
+  - `repository_dispatch` — uses github.event.client_payload, no commits key
+  - `release` — uses github.event.release, no commits array
+
+  When a workflow is triggered on both `push` and `workflow_dispatch` (a common pattern),
+  expressions like:
+    ${{ github.event.commits[0].message }}
+    ${{ github.event.head_commit.id }}
+
+  silently evaluate to empty string ('') on non-push triggers rather than raising an error.
+  GitHub Actions treats missing context properties as empty string, so the step runs but
+  with blank or wrong data — the workflow shows green while producing incorrect output.
+
+  This is a silent failure because there is no error in the logs when the empty string is
+  used in a step (e.g., an echo, a tag, a release title). The problem only becomes visible
+  when the downstream artifact or message is inspected.
+fix: |
+  Use git directly to extract commit information — it works reliably across all trigger types
+  (as long as fetch-depth is not 1 / uses default full clone or depth >= 2):
+
+    git log --format=%s -1      # subject line
+    git log --format=%H -1      # full SHA
+    git log --format=%ae -1     # author email
+
+  Alternatively, guard commit-context access with an event_name check, or use the
+  github.sha context (which IS available on all triggers) when a commit SHA is needed.
+fix_code:
+  - language: yaml
+    label: "Portable commit message extraction via git (works on all triggers)"
+    code: |
+      jobs:
+        release:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                fetch-depth: 2  # depth >= 2 required for git log on non-push
+
+            - name: Get commit message (safe for push, workflow_dispatch, schedule)
+              id: meta
+              run: |
+                echo "sha=${{ github.sha }}" >> $GITHUB_OUTPUT
+                echo "message=$(git log --format=%s -1 ${{ github.sha }})" >> $GITHUB_OUTPUT
+                echo "author=$(git log --format=%ae -1 ${{ github.sha }})" >> $GITHUB_OUTPUT
+
+            - name: Use commit metadata
+              run: |
+                echo "SHA: ${{ steps.meta.outputs.sha }}"
+                echo "Message: ${{ steps.meta.outputs.message }}"
+  - language: yaml
+    label: "Guard push-only context with event_name check"
+    code: |
+      - name: Get commit message (push only)
+        if: github.event_name == 'push' && github.event.commits[0] != null
+        run: |
+          echo "COMMIT_MSG=${{ github.event.commits[0].message }}" >> $GITHUB_ENV
+
+      - name: Fallback for non-push triggers
+        if: github.event_name != 'push'
+        run: |
+          echo "COMMIT_MSG=$(git log --format=%s -1)" >> $GITHUB_ENV
+  - language: yaml
+    label: "Debug: dump full event payload to understand what is available"
+    code: |
+      - name: Debug — dump event context
+        run: echo '${{ toJSON(github.event) }}'
+prevention:
+  - "Never access github.event.commits or github.event.head_commit without first checking github.event_name == 'push'."
+  - "Use `git log --format=%s -1 ${{ github.sha }}` for commit message extraction — it works on all trigger types."
+  - "Note that github.sha IS available on all triggers and points to the relevant commit; use it as a portable substitute for github.event.head_commit.id."
+  - "Add a debug step early in development to dump `${{ toJSON(github.event) }}` so you can see exactly what context is available for each trigger type."
+  - "Test workflows by triggering them manually via workflow_dispatch to catch push-only context assumptions before they hit production."
+docs:
+  - url: "https://docs.github.com/en/webhooks/webhook-events-and-payloads#push"
+    label: "GitHub docs — push event payload (includes commits array)"
+  - url: "https://docs.github.com/en/webhooks/webhook-events-and-payloads#workflow_dispatch"
+    label: "GitHub docs — workflow_dispatch event payload (no commits array)"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/accessing-contextual-information-about-workflow-runs#github-context"
+    label: "GitHub docs — github context reference"
+  - url: "https://github.com/orgs/community/discussions/27058"
+    label: "Community discussion — github.event.commits undefined on workflow_dispatch"

package/errors/silent-failures/fetch-tags-depth-one-silent-no-op.yml

@@ -0,0 +1,77 @@
+id: silent-failures-022
+title: "fetch-tags: true Silently Fetches No Tags When fetch-depth Is 1"
+category: silent-failures
+severity: silent-failure
+tags:
+  - checkout
+  - fetch-tags
+  - shallow-clone
+  - fetch-depth
+  - git-tags
+  - versioning
+patterns:
+  - regex: "No tags found|no tags found"
+    flags: "i"
+  - regex: "fatal: No names found, cannot describe anything"
+    flags: "i"
+  - regex: "CHANGELOG.*No tag found"
+    flags: "i"
+error_messages:
+  - "fatal: No names found, cannot describe anything"
+  - "No tags found. Try unshallowing the repository"
+  - "CHANGELOG ERROR: No tag found on HEAD"
+  - "Error: No tags matching '*' found, exiting"
+root_cause: |
+  The `fetch-tags: true` option in `actions/checkout` was introduced in v3.6.0 to restore tag
+  fetching after `--no-tags` was made the default for shallow clones. However, when `fetch-depth`
+  remains at its default value of `1` (shallow clone), the tag fetch silently produces no results.
+
+  With a shallow clone, git only downloads a single commit. Tags are only present if they point
+  directly to that one commit — i.e., the workflow was triggered by a tag push. In all other
+  cases, `fetch-tags: true` appears to succeed (no error, no warning) but `git tag -l` returns
+  empty results.
+
+  This silently breaks tools that depend on git tags for versioning: semantic-release,
+  commitizen, standard-version, cargo-smart-release, setuptools-scm, and any script using
+  `git describe --tags`. Builds succeed but produce wrong version numbers (often 0.0.0 or
+  commit-hash-only versions).
+fix: |
+  Pair `fetch-tags: true` with `fetch-depth: 0` to fetch the full history including all tags.
+  On very large repositories, use `filter: tree:0` for a blobless partial clone that still
+  includes complete tag history. As a targeted workaround, add a second step to fetch only
+  tags after a shallow checkout.
+fix_code:
+  - language: yaml
+    label: "Recommended: full history with all tags"
+    code: |
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0     # full history required for tags
+          fetch-tags: true   # fetch all tags
+  - language: yaml
+    label: "Large repos: blobless filter (faster, still includes tags)"
+    code: |
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          filter: tree:0     # blobless clone — avoids downloading file blobs
+          fetch-tags: true
+  - language: yaml
+    label: "Workaround: shallow checkout + separate tag fetch step"
+    code: |
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+      - name: Fetch all tags
+        run: git fetch --prune --unshallow --tags
+prevention:
+  - "Always pair `fetch-tags: true` with `fetch-depth: 0` unless the workflow is only triggered by tag pushes"
+  - "Add `git tag -l` as a debug step in release workflows to verify tags are present after checkout"
+  - "If using semantic-release or similar, test your version script locally with a shallow clone to catch this early"
+docs:
+  - url: "https://github.com/actions/checkout/issues/1471"
+    label: "actions/checkout#1471 — fetch-tags: true doesn't actually fetch any tags (126 reactions)"
+  - url: "https://github.com/actions/checkout/issues/1467"
+    label: "actions/checkout#1467 — related: no-tags default behavior"
+  - url: "https://github.com/actions/checkout#usage"
+    label: "actions/checkout — fetch-tags and fetch-depth inputs documentation"