@htekdev/actions-debugger 1.0.49 → 1.0.51

package/errors/caching-artifacts/caching-artifacts-035.yml

@@ -0,0 +1,119 @@
+id: caching-artifacts-035
+title: 'actions/cache fail-on-cache-miss: true causes first-run workflow failure — no cache exists on initial or rekeyed run'
+category: caching-artifacts
+severity: error
+tags:
+  - cache
+  - fail-on-cache-miss
+  - first-run
+  - actions-cache
+  - cache-miss
+  - bootstrap
+patterns:
+  - regex: 'fail-on-cache-miss:\s*true'
+    flags: 'i'
+  - regex: 'Error: Cannot find a cache that matches the specified keys'
+    flags: 'i'
+error_messages:
+  - 'Error: Cannot find a cache that matches the specified keys'
+  - 'Cache not found for input keys: ...'
+  - '##[error]Cannot find a cache that matches the specified keys'
+root_cause: |
+  The actions/cache action added a fail-on-cache-miss input (introduced in v3.3.0,
+  available in v4). When set to true, the action exits with a non-zero status code
+  if no cache entry matches the provided key or restore-keys list. The intended use
+  case is detecting stale or misconfigured cache keys in established pipelines.
+
+  The critical problem: on the very first run of a workflow (new repository, newly
+  added cache step, or after changing the cache key expression), NO cache exists by
+  definition. With fail-on-cache-miss: true, the action fails immediately and the
+  job exits before any steps produce the artifacts that would be cached.
+
+  This creates a bootstrap deadlock:
+  1. Job starts — no cache exists — fail-on-cache-miss: true fires — job fails
+  2. Post-step cache save never runs because the job failed
+  3. Next run repeats step 1 — cache is never populated — workflow is permanently broken
+
+  The same issue occurs whenever the cache key expression changes (adding runner OS,
+  changing the hash source file, bumping a version prefix), because all existing
+  caches miss the new key pattern. Until the new cache is warm, every run fails.
+
+  Matrix builds compound the problem: each unique matrix dimension (OS × version)
+  needs its own initial run to seed the cache, so all combinations fail in parallel
+  on first use of the new key.
+fix: |
+  Remove fail-on-cache-miss: true from the actions/cache step unless you have an
+  externally pre-seeded cache and a specific requirement to guarantee it exists
+  (rare, advanced use case).
+
+  For the common use case of skipping expensive install steps on cache hit:
+  use the cache-hit output instead. cache-hit is 'true' on exact key match and
+  allows downstream steps to be conditional, while still letting the job complete
+  successfully on a miss so the cache can be populated.
+
+  If you genuinely need to gate on cache existence (e.g., a nightly build that
+  consumes a separately-seeded model or dataset cache), run a dedicated cache-warming
+  workflow first and use fail-on-cache-miss: true only after confirming the seeder
+  workflow has run at least once.
+fix_code:
+  - language: yaml
+    label: 'Use cache-hit output for conditional install instead of fail-on-cache-miss'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Cache npm dependencies
+              id: cache-npm
+              uses: actions/cache@v4
+              with:
+                path: ~/.npm
+                key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
+                restore-keys: |
+                  ${{ runner.os }}-npm-
+                # AVOID: fail-on-cache-miss: true  ← breaks first run (deadlock)
+
+            - name: Install dependencies
+              # Only runs on cache miss — fast path skipped on hit
+              if: steps.cache-npm.outputs.cache-hit != 'true'
+              run: npm ci
+
+            - name: Build
+              run: npm run build
+
+  - language: yaml
+    label: 'Dedicated cache-warming workflow to pre-seed before fail-on-cache-miss use'
+    code: |
+      # .github/workflows/warm-cache.yml — run this first to pre-seed
+      name: Warm Cache
+      on:
+        schedule:
+          - cron: '0 6 * * 1'
+        workflow_dispatch:   # Allow manual trigger when rekeying cache
+
+      jobs:
+        warm:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - name: Cache dependencies
+              uses: actions/cache@v4
+              with:
+                path: ~/.npm
+                key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
+            - name: Install to populate cache
+              run: npm ci
+prevention:
+  - 'Never set fail-on-cache-miss: true on a fresh workflow or after changing the cache key expression — the cache cannot exist yet'
+  - 'Use cache-hit output and conditional if: steps.id.outputs.cache-hit != true for skip-on-hit behavior without failing on miss'
+  - 'When rekeying cache (OS prefix, hash source change), trigger a manual cache-warming workflow_dispatch run before deploying the new key'
+  - 'Test new cache key expressions in a feature branch where a job failure will not block main'
+docs:
+  - url: 'https://github.com/actions/cache'
+    label: 'actions/cache README — fail-on-cache-miss input documentation'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows'
+    label: 'GitHub Docs: Caching dependencies to speed up workflows'
+  - url: 'https://github.com/actions/cache/blob/main/tips-and-workarounds.md'
+    label: 'actions/cache tips and workarounds — cache miss handling patterns'

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

@@ -0,0 +1,111 @@
+id: runner-environment-105
+title: 'macOS 12 (Monterey) runner retired September 2024 — runs-on: macos-12 workflows fail or queue indefinitely'
+category: runner-environment
+severity: error
+tags:
+  - macos-12
+  - runner-retirement
+  - macos-monterey
+  - deprecated-runner
+  - github-hosted
+  - runs-on
+patterns:
+  - regex: 'runs-on:\s*macos-12'
+    flags: 'i'
+  - regex: 'No runner matching the specified labels was found.*macos-12|Requested labels: macos-12'
+    flags: 'i'
+error_messages:
+  - 'No runner matching the specified labels was found: macos-12'
+  - '##[error]No runner matching the specified labels was found'
+  - 'Runner not found matching labels: [macos-12]'
+root_cause: |
+  GitHub retired the macOS 12 (Monterey) hosted runner on September 1, 2024. After
+  this date, workflows specifying runs-on: macos-12 can no longer be scheduled on a
+  GitHub-hosted runner matching that label.
+
+  Depending on repository and organization settings, affected jobs may:
+  - Fail immediately with "No runner matching the specified labels was found"
+  - Queue indefinitely waiting for a runner that will never be provisioned
+  - Show a "This job was skipped" status with no clear error message
+
+  GitHub announced the deprecation on May 20, 2024 (90+ days notice) and made it
+  official with a deprecation flag on July 1, 2024. Hard retirement occurred
+  September 1, 2024.
+
+  macOS 12 was the Monterey release. GitHub's macOS runner fleet moved to:
+  - macOS 13 (Ventura) — Intel x86-64, became the Intel baseline
+  - macOS 14 (Sonoma) — Apple Silicon M1, new default for macos-latest (Oct 2024)
+  - macOS 15 (Sequoia) — Apple Silicon M2, macos-latest as of January 2025
+
+  Common sources of this error after retirement:
+  - Long-lived workflow files written when macOS 12 was current
+  - Forks and template repositories with outdated runner labels
+  - Composite actions that pin macos-12 in their action.yml runs: block
+  - Third-party reusable workflows that have not been updated
+fix: |
+  Replace runs-on: macos-12 with a supported macOS runner label. Choose based on
+  architecture requirements:
+
+  - macos-13       — Intel x86-64, macOS Ventura (closest to macOS 12 behavior)
+  - macos-14       — Apple Silicon M1, macOS Sonoma
+  - macos-15       — Apple Silicon M2, macOS Sequoia
+  - macos-latest   — currently macOS 15 / Apple Silicon as of January 2025
+
+  IMPORTANT: macos-14 and later use Apple Silicon (M1/M2). If your workflow depends
+  on Intel x86-64 architecture (Homebrew formula paths differ, Rosetta 2 needed for
+  old binaries, or x86-specific compiler flags), migrate to macos-13, not macos-latest.
+
+  After migrating, verify:
+  - Homebrew default prefix changed from /usr/local (Intel) to /opt/homebrew (ARM)
+  - Xcode version availability — use actions/setup-xcode for explicit version pinning
+  - System Python and Ruby versions differ between macOS generations
+  - Any hardcoded SDKROOT or architecture flags targeting x86-64
+fix_code:
+  - language: yaml
+    label: 'Replace retired macos-12 with macos-13 (Intel) or macos-14/15 (Apple Silicon)'
+    code: |
+      jobs:
+        build-intel:
+          # Before: runs-on: macos-12  ← retired September 1, 2024
+          # Intel x86-64 — closest behavioral match to macOS 12:
+          runs-on: macos-13
+          steps:
+            - uses: actions/checkout@v4
+            - name: Build
+              run: make build
+
+        build-arm:
+          # Apple Silicon M1/M2 — use for new projects or ARM-compatible builds:
+          runs-on: macos-latest   # macOS 15 / Apple Silicon as of Jan 2025
+          steps:
+            - uses: actions/checkout@v4
+            - name: Build
+              run: make build
+
+  - language: yaml
+    label: 'Matrix across macOS versions to validate compatibility before committing to one'
+    code: |
+      jobs:
+        test:
+          strategy:
+            matrix:
+              # Test Intel (13) and Apple Silicon (14) in parallel
+              os: [macos-13, macos-14]
+            fail-fast: false
+          runs-on: ${{ matrix.os }}
+          steps:
+            - uses: actions/checkout@v4
+            - name: Test on ${{ matrix.os }}
+              run: make test
+prevention:
+  - 'Subscribe to the GitHub Changelog (github.blog/changelog) for runner retirement notices — typically 90+ days notice'
+  - 'Pin to a specific macOS version (macos-13, macos-14) rather than macos-latest for reproducible builds; macos-latest advances'
+  - 'Be aware of architecture differences: macos-13 is Intel x86-64; macos-14 and later are Apple Silicon'
+  - 'Search workflow files periodically for retired labels: look for macos-12, macos-11, ubuntu-18.04, windows-2019'
+docs:
+  - url: 'https://github.blog/changelog/2024-05-20-actions-upcoming-changes-to-github-hosted-macos-runners/'
+    label: 'GitHub Changelog: Upcoming changes to macOS runners (May 2024)'
+  - url: 'https://github.blog/changelog/2024-07-01-github-actions-macos-12-is-now-deprecated/'
+    label: 'GitHub Changelog: macOS 12 is now deprecated (July 2024)'
+  - 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 Docs: Supported runners and hardware resources'

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

@@ -0,0 +1,110 @@
+id: runner-environment-106
+title: 'Windows Server 2019 (windows-2019) runner retired April 1, 2025 — jobs fail or queue indefinitely'
+category: runner-environment
+severity: error
+tags:
+  - windows-2019
+  - runner-retirement
+  - windows-server-2019
+  - deprecated-runner
+  - github-hosted
+  - runs-on
+  - visual-studio-2019
+patterns:
+  - regex: 'runs-on:\s*windows-2019'
+    flags: 'i'
+  - regex: 'No runner matching the specified labels was found.*windows-2019|Requested labels:\s*windows-2019'
+    flags: 'i'
+error_messages:
+  - 'No runner matching the specified labels was found: windows-2019'
+  - '##[error]No runner matching the specified labels was found'
+  - 'Runner not found matching labels: [windows-2019]'
+root_cause: |
+  GitHub retired the Windows Server 2019 (windows-2019) GitHub-hosted runner on
+  April 1, 2025. After this date, workflows specifying runs-on: windows-2019 can
+  no longer be scheduled on a GitHub-hosted runner matching that label.
+
+  GitHub announced the deprecation in September 2024 (90+ days notice) with
+  brownout periods beginning before the hard cutoff. windows-latest had already
+  transitioned to point to windows-2022 (Windows Server 2022 with Visual Studio
+  2022) on October 28, 2024, giving teams an early signal.
+
+  Workflows most affected:
+  - Files explicitly specifying runs-on: windows-2019 (not windows-latest)
+  - Builds relying on Visual Studio 2019 toolset version v142 MSBuild tools
+  - .csproj files with hardcoded <PlatformToolset>v142</PlatformToolset>
+  - Workflows using .NET Framework or SDK behaviors specific to the VS2019 era
+  - Actions pinned to a major version that internally specified windows-2019
+  - Forks and template repositories written before windows-2022 was the default
+
+  A secondary migration concern: workflows that used windows-latest and relied on
+  VS2019 behavior were silently broken when windows-latest moved to windows-2022
+  in October 2024. Pinning to windows-2019 was a common workaround — the
+  retirement forced resolution of both the workaround and the underlying toolset
+  incompatibility simultaneously.
+fix: |
+  Replace runs-on: windows-2019 with a supported Windows runner label:
+
+  - windows-2022     — Windows Server 2022, Visual Studio 2022 (toolset v143)
+  - windows-2025     — Windows Server 2025, Visual Studio 2022 (available 2025)
+  - windows-latest   — currently maps to windows-2022
+
+  If your workflow uses MSBuild and specifies PlatformToolset=v142 (VS2019
+  toolset), you have two options:
+  1. Update project files to remove the explicit PlatformToolset element and
+     let MSBuild select the installed toolset automatically (preferred).
+  2. Migrate the .csproj to PlatformToolset v143 (VS2022 toolset).
+
+  Check these locations for VS2019-specific behavior:
+  - .csproj files with <PlatformToolset>v142</PlatformToolset>
+  - Hardcoded paths like C:\Program Files (x86)\Microsoft Visual Studio\2019\...
+  - vcpkg toolchain files referencing VS2019 installs
+  - Workflow env: blocks with hardcoded VSINSTALLDIR paths
+fix_code:
+  - language: yaml
+    label: 'Replace retired windows-2019 with windows-2022'
+    code: |
+      jobs:
+        build:
+          # Before: runs-on: windows-2019  <- retired April 1, 2025
+          runs-on: windows-2022
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Setup MSBuild
+              uses: microsoft/setup-msbuild@v2
+
+            - name: Build solution
+              run: msbuild solution.sln /p:Configuration=Release /p:Platform="Any CPU"
+              # If build fails on toolset version, update PlatformToolset in .csproj
+              # from v142 (VS2019) to v143 (VS2022) or remove it to auto-select
+
+  - language: yaml
+    label: 'Matrix across Windows versions to verify migration before cutover'
+    code: |
+      jobs:
+        build:
+          strategy:
+            matrix:
+              # windows-2019 removed — retired April 1, 2025
+              os: [windows-2022]
+            fail-fast: false
+          runs-on: ${{ matrix.os }}
+          steps:
+            - uses: actions/checkout@v4
+            - name: Setup MSBuild
+              uses: microsoft/setup-msbuild@v2
+            - name: Build
+              run: msbuild solution.sln /p:Configuration=Release
+prevention:
+  - 'Use windows-latest or windows-2022 — never pin to a specific older Windows runner label for long-lived workflows'
+  - 'Avoid hardcoding Visual Studio toolset versions (v142, v143) in .csproj files — let MSBuild auto-select the installed toolset'
+  - 'Subscribe to GitHub Changelog at github.blog/changelog to receive runner retirement announcements before hard cutoff dates'
+  - 'Test on windows-2022 in a feature branch before any deprecation deadline to catch VS toolset migration issues early'
+docs:
+  - url: 'https://github.blog/changelog/2024-09-12-windows-2019-actions-runner-image-brownout-and-deprecation/'
+    label: 'GitHub Changelog: Windows 2019 runner image brownout and deprecation'
+  - 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 Docs: Supported GitHub-hosted runners and hardware resources'
+  - url: 'https://github.com/actions/runner-images'
+    label: 'actions/runner-images: GitHub-hosted runner image specifications'

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

@@ -0,0 +1,105 @@
+id: runner-environment-107
+title: 'Ubuntu 24.04 runner: unversioned python command absent — /usr/bin/env: python: No such file or directory'
+category: runner-environment
+severity: error
+tags:
+  - ubuntu-24
+  - python
+  - python3
+  - unversioned-alias
+  - command-not-found
+  - ubuntu-noble
+  - ubuntu-latest
+patterns:
+  - regex: '/usr/bin/env:\s*[''"]?python[''"]?:\s*No such file|python:\s*command not found'
+    flags: 'i'
+  - regex: 'runs-on:\s*ubuntu-2[4-9]|runs-on:\s*ubuntu-latest'
+    flags: 'i'
+error_messages:
+  - '/usr/bin/env: python: No such file or directory'
+  - 'python: command not found'
+  - '##[error]Process completed with exit code 127.'
+root_cause: |
+  Ubuntu 24.04 (Noble Numbat) does not install the unversioned python command by
+  default. Only python3 (Python 3.12+) is present in the PATH. This follows
+  PEP 394 guidance and a deliberate Ubuntu packaging decision: the
+  python3-is-python package (which creates a /usr/bin/python -> python3 symlink)
+  is not pre-installed on GitHub-hosted Ubuntu 24.04 runners.
+
+  As of November 2024, ubuntu-latest on GitHub-hosted runners maps to ubuntu-24.04.
+  Workflows that ran on ubuntu-latest (previously ubuntu-22.04) began failing
+  because Ubuntu 22.04 runners had side-effected python aliases through
+  actions/setup-python or the python-is-python3 shim, while the Ubuntu 24.04
+  baseline has no unversioned python at all.
+
+  Affected patterns:
+  - run: python script.py
+  - run: python -m pytest
+  - Shell scripts with #!/usr/bin/env python shebang lines
+  - Makefile targets invoking python
+  - Third-party composite actions that call python internally without setup-python
+  - pip invocations — pip is also absent (only pip3 available)
+fix: |
+  Option 1 (recommended): Use actions/setup-python before any step that needs
+  Python. This installs a versioned Python and creates both python and python3
+  symlinks in PATH, resolving the problem portably across all runner OS versions.
+
+  Option 2: Replace all python invocations with python3 in workflow files.
+  Also replace pip with pip3 or python3 -m pip. Works if you control all scripts
+  but misses shebangs in vendor code or third-party tools.
+
+  Option 3: Install the alias manually in a setup step:
+    sudo apt-get install -y python-is-python3
+  This creates the /usr/bin/python -> python3 symlink immediately. The package is
+  already in the apt cache — install is fast with no download required.
+fix_code:
+  - language: yaml
+    label: 'Use actions/setup-python (recommended — portable across all runner versions)'
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Set up Python
+              uses: actions/setup-python@v5
+              with:
+                python-version: '3.12'
+              # Creates both python and python3 aliases in PATH
+
+            - name: Install dependencies
+              run: python -m pip install -r requirements.txt
+
+            - name: Run tests
+              run: python -m pytest tests/
+
+  - language: yaml
+    label: 'Install python-is-python3 alias for scripts with hardcoded python shebangs'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Install python alias
+              run: sudo apt-get install -y python-is-python3
+              # Creates /usr/bin/python -> python3 symlink
+              # Fast: package already in apt cache on ubuntu-24.04
+
+            - name: Run script with python shebang
+              run: ./scripts/legacy-build.sh
+              # Script uses #!/usr/bin/env python internally
+prevention:
+  - 'Always use actions/setup-python in workflows that invoke python — portable and creates the python alias on all runner OS versions'
+  - 'Avoid relying on system Python; python version and alias availability varies between Ubuntu 22.04 and 24.04'
+  - 'When ubuntu-latest bumps to a new Ubuntu version, search run: blocks and scripts for bare python and pip invocations'
+  - 'Pin ubuntu-24.04 explicitly during transition testing rather than ubuntu-latest to catch breakage before it hits production'
+docs:
+  - url: 'https://github.com/actions/runner-images/issues/9654'
+    label: 'runner-images#9654: python command not found on Ubuntu 24.04'
+  - url: 'https://github.com/actions/runner-images'
+    label: 'actions/runner-images: GitHub-hosted runner image specifications'
+  - url: 'https://github.com/actions/setup-python'
+    label: 'actions/setup-python: Set up a Python environment for use in Actions'

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

@@ -0,0 +1,109 @@
+id: runner-environment-108
+title: 'Ubuntu 22.04 runner: libssl.so.1.1 missing — binaries compiled on Ubuntu 20.04 fail with cannot open shared object file'
+category: runner-environment
+severity: error
+tags:
+  - ubuntu-22
+  - libssl
+  - openssl3
+  - shared-library
+  - binary-compatibility
+  - ubuntu-jammy
+  - dynamic-linking
+patterns:
+  - regex: 'libssl\.so\.1\.1.*cannot open shared object file|error while loading shared libraries: libssl\.so\.1\.1'
+    flags: 'i'
+  - regex: 'libcrypto\.so\.1\.1.*cannot open shared object file'
+    flags: 'i'
+error_messages:
+  - 'error while loading shared libraries: libssl.so.1.1: cannot open shared object file: No such file or directory'
+  - '/usr/lib/x86_64-linux-gnu/libssl.so.1.1: No such file or directory'
+  - 'error while loading shared libraries: libcrypto.so.1.1: cannot open shared object file: No such file or directory'
+root_cause: |
+  Ubuntu 22.04 (Jammy) ships OpenSSL 3.0, replacing OpenSSL 1.1. The shared
+  library libssl.so.1.1 is absent — the libssl1.1 package that provided it is
+  not available in the Ubuntu 22.04 (jammy) package repository at all; it was
+  a focal (Ubuntu 20.04) package only.
+
+  When ubuntu-latest transitioned from Ubuntu 20.04 to Ubuntu 22.04 in 2022,
+  CI pipelines that downloaded or shipped pre-compiled binaries started failing
+  because those binaries were dynamically linked against libssl1.1. Common
+  scenarios that trigger this error:
+
+  - Self-hosted runners migrated from Ubuntu 20.04 to 22.04 while tool cache
+    contains pre-compiled focal binaries
+  - Docker images with pre-compiled binaries using libssl1.1 run in container
+    jobs on ubuntu-22.04 hosts
+  - Ruby gems with native extensions (mysql2, pg, ruby-openssl) compiled on
+    Ubuntu 20.04 and installed from a cached bundler path
+  - Node.js native add-ons (node-gyp built) that link against libssl1.1
+  - Custom CLI tools shipped as pre-built .deb or tar.gz for Ubuntu 20.04
+  - Python C extension packages (pycurl, cryptography old versions) with
+    libssl1.1 runtime dependency
+
+  libcrypto.so.1.1 is also absent — tools linked against both libraries fail
+  with the same error on whichever library is loaded first.
+fix: |
+  Option 1 (best long-term): Recompile the affected binary for Ubuntu 22.04 or
+  later against OpenSSL 3.0 (libssl3). Ubuntu 20.04 reached end-of-standard-support
+  in April 2025 — new binaries should target OpenSSL 3.0.
+
+  Option 2: Install a libssl1.1 compatibility .deb backported from Ubuntu 20.04
+  focal. Add an install step using the focal security archive. This is a
+  temporary workaround — the package receives no security patches on 22.04.
+
+  Option 3: Use a container job with ubuntu:20.04 base image for steps that
+  require libssl1.1, isolating the dependency from the host runner OS.
+
+  Option 4: Pin runs-on: ubuntu-20.04 temporarily while planning recompile.
+  ubuntu-20.04 runners will eventually be retired — plan a migration timeline.
+fix_code:
+  - language: yaml
+    label: 'Install libssl1.1 compatibility shim from Ubuntu 20.04 focal archive (temporary workaround)'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-22.04
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Install libssl1.1 compatibility shim
+              run: |
+                wget -q http://security.ubuntu.com/ubuntu/pool/main/o/openssl/libssl1.1_1.1.1f-1ubuntu2_amd64.deb
+                sudo dpkg -i libssl1.1_1.1.1f-1ubuntu2_amd64.deb
+              # WARNING: Temporary workaround only. Recompile binary against OpenSSL 3.0 for the permanent fix.
+
+            - name: Run legacy binary
+              run: ./vendor/legacy-tool
+
+  - language: yaml
+    label: 'Use container job with ubuntu:20.04 base image to isolate libssl1.1 dependency'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          container:
+            image: ubuntu:20.04
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Install prerequisites
+              run: |
+                apt-get update
+                apt-get install -y libssl1.1 curl
+
+            - name: Run legacy binary
+              run: ./vendor/legacy-tool
+              # Binary now runs with libssl1.1 available in container
+prevention:
+  - 'Compile release binaries against the same OpenSSL version as the target runner OS (3.0 for Ubuntu 22.04+)'
+  - 'When upgrading ubuntu-latest, audit all pre-compiled binaries with ldd to check for libssl.so.1.1 dynamic dependencies before rolling out'
+  - 'Use statically-linked binaries or distroless container images for tools that must run across multiple Ubuntu versions'
+  - 'In matrix workflows, include ubuntu-22.04 alongside ubuntu-20.04 to catch OpenSSL ABI incompatibilities before retirement deadlines'
+docs:
+  - url: 'https://github.com/actions/runner-images/issues/6399'
+    label: 'runner-images#6399: libssl.so.1.1 missing on Ubuntu 22.04'
+  - url: 'https://wiki.openssl.org/index.php/OpenSSL_3.0'
+    label: 'OpenSSL 3.0 migration guide — ABI compatibility with OpenSSL 1.1'
+  - url: 'https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners'
+    label: 'GitHub Docs: About GitHub-hosted runners'

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

@@ -0,0 +1,121 @@
+id: runner-environment-109
+title: 'macOS 14+ (Apple Silicon) runner: Homebrew prefix changed from /usr/local to /opt/homebrew — hardcoded paths fail'
+category: runner-environment
+severity: error
+tags:
+  - macos-14
+  - apple-silicon
+  - homebrew
+  - arm64
+  - path
+  - macos-sonoma
+  - opt-homebrew
+  - cross-architecture
+patterns:
+  - regex: '/usr/local/(bin/brew|Cellar|opt)\b'
+    flags: 'i'
+  - regex: 'No such file or directory.*(/usr/local/bin/brew|/usr/local/opt|/usr/local/Cellar)'
+    flags: 'i'
+error_messages:
+  - '/usr/local/bin/brew: No such file or directory'
+  - 'Error: No such file or directory @ rb_sysopen - /usr/local/Cellar'
+  - '/usr/local/opt/openssl: No such file or directory'
+  - 'pkg-config: /usr/local/opt/openssl/lib/pkgconfig: No such file or directory'
+root_cause: |
+  Homebrew on Apple Silicon (ARM64) installs to /opt/homebrew, while Homebrew on
+  Intel x86-64 installs to /usr/local. This architectural split was introduced when
+  Homebrew added native Apple Silicon support in early 2021.
+
+  GitHub-hosted macOS runners on Apple Silicon hardware (macos-14, macos-15, and
+  macos-latest since October 2024) use /opt/homebrew as the Homebrew prefix.
+  Workflows migrating from macOS 12 or macOS 13 (Intel x86-64) to macOS 14+
+  (Apple Silicon) break when they reference hardcoded /usr/local paths:
+
+  - /usr/local/bin/brew — the brew binary itself
+  - /usr/local/Cellar/package-name — installed package files
+  - /usr/local/opt/package-name — formula options/keg link (very common for
+    openssl, readline, libpq, libyaml, icu4c, pkg-config)
+  - PKG_CONFIG_PATH=/usr/local/opt/openssl/lib/pkgconfig in env: blocks
+  - OPENSSL_ROOT_DIR=/usr/local/opt/openssl in build steps
+  - LDFLAGS=-L/usr/local/opt/readline/lib for native extension builds
+  - CPPFLAGS=-I/usr/local/opt/openssl/include for C/C++ compilation
+  - Shell scripts that source /usr/local/etc/profile.d/
+
+  Commonly broken language ecosystems:
+  - Ruby gems with native extensions (nokogiri --with-opt-dir=/usr/local/opt/openssl)
+  - Python packages (pycurl, psycopg2, cryptography) with hardcoded CPPFLAGS
+  - Node.js native add-ons reading PKG_CONFIG_PATH pointing to /usr/local/opt
+  - Go builds with CGO_CFLAGS referencing /usr/local/include
+fix: |
+  Replace all hardcoded /usr/local/opt and /usr/local/Cellar paths with the
+  dynamic output of brew --prefix [formula-name].
+
+  The portable pattern:
+    OPENSSL_ROOT_DIR=$(brew --prefix openssl)
+    PKG_CONFIG_PATH="$(brew --prefix openssl)/lib/pkgconfig"
+
+  brew --prefix returns /usr/local/opt/package on Intel and /opt/homebrew/opt/package
+  on Apple Silicon — making it correct on both architectures automatically.
+
+  For the Homebrew root itself, use the $HOMEBREW_PREFIX environment variable
+  which is pre-set by the runner image to the correct prefix (/usr/local or
+  /opt/homebrew) depending on the runner architecture.
+
+  Actionlint does not flag hardcoded /usr/local paths — a manual audit of
+  env: blocks and run: scripts is required when migrating runner architectures.
+fix_code:
+  - language: yaml
+    label: 'Use brew --prefix for portable formula paths across Intel and Apple Silicon'
+    code: |
+      jobs:
+        build:
+          runs-on: macos-latest   # macos-14+ on Apple Silicon (/opt/homebrew)
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Install dependencies
+              run: brew install openssl readline libpq
+
+            - name: Set library paths (portable — works on Intel and Apple Silicon)
+              run: |
+                echo "OPENSSL_ROOT_DIR=$(brew --prefix openssl)" >> $GITHUB_ENV
+                echo "PKG_CONFIG_PATH=$(brew --prefix openssl)/lib/pkgconfig:$(brew --prefix readline)/lib/pkgconfig" >> $GITHUB_ENV
+                echo "LDFLAGS=-L$(brew --prefix openssl)/lib -L$(brew --prefix readline)/lib" >> $GITHUB_ENV
+                echo "CPPFLAGS=-I$(brew --prefix openssl)/include -I$(brew --prefix readline)/include" >> $GITHUB_ENV
+                # DO NOT hardcode /usr/local/opt/... — breaks on Apple Silicon (/opt/homebrew)
+
+            - name: Install native gems
+              run: bundle install
+
+  - language: yaml
+    label: 'Use $HOMEBREW_PREFIX env variable for Homebrew root references'
+    code: |
+      jobs:
+        build:
+          runs-on: macos-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Install tool
+              run: brew install libffi
+
+            - name: Build with native dependency
+              run: |
+                # $HOMEBREW_PREFIX is pre-set by the runner image
+                # Intel macOS 12/13:   /usr/local
+                # Apple Silicon 14/15: /opt/homebrew
+                export LIBRARY_PATH="$HOMEBREW_PREFIX/lib:$LIBRARY_PATH"
+                export C_INCLUDE_PATH="$HOMEBREW_PREFIX/include:$C_INCLUDE_PATH"
+                make install
+prevention:
+  - 'Never hardcode /usr/local/opt, /usr/local/Cellar, or /usr/local/bin/brew — always use brew --prefix <formula> at runtime'
+  - 'Use $HOMEBREW_PREFIX (set by runner images) for generic Homebrew root path references'
+  - 'When migrating from macos-12/13 (Intel) to macos-14+ (Apple Silicon), grep workflow files and scripts for /usr/local/ strings'
+  - 'Test with runs-on: macos-14 in a feature branch before switching macos-latest to catch architecture-specific path failures'
+docs:
+  - url: 'https://docs.brew.sh/Installation'
+    label: 'Homebrew Installation docs: default prefix differences between Intel and Apple Silicon'
+  - url: 'https://github.com/actions/runner-images/blob/main/images/macos/macos-14-arm64-Readme.md'
+    label: 'actions/runner-images: macOS 14 ARM64 image README'
+  - url: 'https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners'
+    label: 'GitHub Docs: About GitHub-hosted runners — macOS runner architecture details'

package/errors/triggers/triggers-038.yml

@@ -0,0 +1,126 @@
+id: triggers-038
+title: 'workflow_run.conclusion is null when the upstream run was cancelled before any job started — if: checks silently skip'
+category: triggers
+severity: silent-failure
+tags:
+  - workflow-run
+  - conclusion
+  - cancelled
+  - null-conclusion
+  - if-condition
+  - cross-workflow
+patterns:
+  - regex: 'github\.event\.workflow_run\.conclusion\s*==\s*[''"]success[''"]'
+    flags: 'i'
+  - regex: 'github\.event\.workflow_run\.conclusion\s*==\s*[''"]failure[''"]'
+    flags: 'i'
+error_messages:
+  - "(No error — triggered workflow runs but all jobs/steps with if: github.event.workflow_run.conclusion == 'success' silently skip)"
+root_cause: |
+  When a downstream workflow uses on: workflow_run (types: [completed]), it fires
+  whenever an upstream workflow run reaches a terminal state. The
+  github.event.workflow_run.conclusion field is expected to reflect the outcome of
+  that upstream run.
+
+  However, if the upstream run was cancelled before any job started — for example,
+  due to a concurrent push triggering cancel-in-progress on the queued run, or a
+  manual UI cancellation before the run left the queue — the conclusion field is
+  null, not "cancelled".
+
+  GitHub's API returns: { "conclusion": null, "status": "cancelled" } for runs
+  cancelled while still queued. This is documented behavior: conclusion is only set
+  when at least one job has run to completion.
+
+  The effect on downstream conditional logic:
+    if: github.event.workflow_run.conclusion == 'success'    → false (null != string)
+    if: github.event.workflow_run.conclusion == 'failure'    → false
+    if: github.event.workflow_run.conclusion == 'cancelled'  → also false (null != string)
+    if: github.event.workflow_run.conclusion != 'success'    → TRUE (null != string)
+
+  The downstream workflow's workflow_run completed event fires and the workflow
+  starts, but every job with a success/failure/cancelled equality check is silently
+  skipped. A CD pipeline gated on CI success may appear to trigger but produce no
+  deployment with no error surfaced to the developer.
+
+  This can also silently allow deployment jobs protected by
+  conclusion != 'failure' to run when the upstream was an early cancellation.
+fix: |
+  Treat workflow_run.conclusion as nullable. Always verify it is not null before
+  comparing to an expected value:
+
+  Option A — Explicit null check (most readable):
+    if: github.event.workflow_run.conclusion != null && github.event.workflow_run.conclusion == 'success'
+
+  Option B — contains() with fromJSON allowlist (handles null gracefully; null is
+  not in the list, so the condition evaluates false without error):
+    if: contains(fromJSON('["success"]'), github.event.workflow_run.conclusion)
+
+  Option C — Guard step that fails fast and visibly when conclusion is unexpected,
+  so silent skips become explicit failures:
+    - run: |
+        if [ "$CONCLUSION" != "success" ]; then
+          echo "Upstream conclusion was: $CONCLUSION"
+          exit 1
+        fi
+      env:
+        CONCLUSION: ${{ github.event.workflow_run.conclusion }}
+fix_code:
+  - language: yaml
+    label: 'Use contains() with fromJSON to handle null conclusion safely'
+    code: |
+      on:
+        workflow_run:
+          workflows: ['CI']
+          types: [completed]
+
+      jobs:
+        deploy:
+          # contains() returns false when conclusion is null — no null-equality error
+          if: |
+            contains(fromJSON('["success"]'), github.event.workflow_run.conclusion) &&
+            github.event.workflow_run.head_branch == 'main'
+          runs-on: ubuntu-latest
+          steps:
+            - name: Deploy
+              run: echo "Deploying after confirmed CI success"
+
+  - language: yaml
+    label: 'Guard step that fails visibly on null or unexpected conclusion'
+    code: |
+      on:
+        workflow_run:
+          workflows: ['CI']
+          types: [completed]
+
+      jobs:
+        verify-conclusion:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Check upstream conclusion
+              env:
+                CONCLUSION: ${{ github.event.workflow_run.conclusion }}
+              run: |
+                echo "Upstream workflow conclusion: $CONCLUSION"
+                if [ "$CONCLUSION" != "success" ]; then
+                  echo "Expected 'success', got '$CONCLUSION' (possibly null if cancelled before job start)"
+                  exit 1
+                fi
+
+        deploy:
+          needs: verify-conclusion
+          runs-on: ubuntu-latest
+          steps:
+            - name: Deploy
+              run: echo "Deploying"
+prevention:
+  - 'Always treat workflow_run.conclusion as nullable — a run cancelled while queued has conclusion: null, not "cancelled"'
+  - 'Use contains(fromJSON(...), github.event.workflow_run.conclusion) instead of == equality — contains() handles null safely'
+  - 'Add a guard step that prints the actual conclusion value to make silent skips visible during debugging'
+  - 'Prefer repository_dispatch for cross-workflow chaining when you need explicit control over the payload and conclusion semantics'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_run'
+    label: 'GitHub Docs: workflow_run event — conclusion field behavior'
+  - url: 'https://docs.github.com/en/rest/actions/workflow-runs?apiVersion=2022-11-28#get-a-workflow-run'
+    label: 'GitHub REST API: Workflow run — conclusion is nullable'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/contexts#github-context'
+    label: 'GitHub Docs: github.event.workflow_run context properties'

package/errors/yaml-syntax/yaml-syntax-036.yml

@@ -0,0 +1,100 @@
+id: yaml-syntax-036
+title: 'run-name: using github.event.head_commit.message shows "undefined" for schedule and workflow_dispatch events'
+category: yaml-syntax
+severity: warning
+tags:
+  - run-name
+  - head-commit-message
+  - schedule
+  - workflow-dispatch
+  - null-property
+  - expression
+patterns:
+  - regex: 'run-name:.*head_commit\.message'
+    flags: 'i'
+error_messages:
+  - "(Run title in the UI displays 'undefined' or 'Deploy by @actor from undefined' — no log error is emitted)"
+root_cause: |
+  The run-name: workflow key (introduced October 2022) lets you set a custom title
+  for each workflow run using GitHub Actions expressions. The GitHub Docs examples
+  include the pattern:
+
+    run-name: Deploy by @${{ github.actor }} from ${{ github.event.head_commit.message }}
+
+  However, github.event.head_commit is ONLY populated for on: push events. For
+  on: schedule, on: workflow_dispatch, on: pull_request, on: release, and most other
+  event types, the head_commit object is absent from the event payload. Accessing
+  github.event.head_commit.message on a null object evaluates to '' in some contexts
+  but renders as "undefined" in the Actions UI run title.
+
+  The result is a workflow run title like:
+    "Deploy by @octocat from undefined"
+  or simply "undefined" — confusing in the Actions tab and audit logs.
+
+  The workflow parses without error because the expression is syntactically valid.
+  The problem only surfaces at runtime when a non-push event triggers the workflow.
+  This is especially common in workflows that have both on: push and on: schedule or
+  on: workflow_dispatch triggers.
+fix: |
+  Use the || short-circuit operator to provide fallback values for event types where
+  head_commit is absent. GitHub Actions expressions treat || as a null/false fallback:
+
+    run-name: "${{ github.event.head_commit.message || github.event.inputs.reason || 'Scheduled run' }}"
+
+  Prefer contexts that are populated for ALL event types:
+  - github.actor — always set (the user or app that triggered the run)
+  - github.ref_name — always set (branch or tag short name)
+  - github.run_number — always set (monotonically increasing per workflow)
+  - github.event.inputs.* — set for workflow_dispatch when inputs are defined
+fix_code:
+  - language: yaml
+    label: 'Add || fallback so run-name is readable for all trigger types'
+    code: |
+      name: Deploy
+      # Without || fallback, schedule and workflow_dispatch show "undefined"
+      # github.event.head_commit is ONLY available on push events
+      run-name: "${{ github.event.head_commit.message || github.event.inputs.reason || 'Scheduled run' }}"
+      on:
+        push:
+          branches: [main]
+        schedule:
+          - cron: '0 8 * * 1'
+        workflow_dispatch:
+          inputs:
+            reason:
+              description: 'Reason for manual trigger'
+              required: false
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+  - language: yaml
+    label: 'Use always-populated contexts for a universally safe run-name'
+    code: |
+      name: Deploy
+      # github.actor, github.ref_name, and github.run_number are set for every event
+      run-name: '${{ github.actor }} on ${{ github.ref_name }} (#${{ github.run_number }})'
+      on:
+        push:
+        schedule:
+          - cron: '0 8 * * 1'
+        workflow_dispatch:
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+prevention:
+  - 'Test run-name expressions against every trigger in your on: block — head_commit is only available for push events'
+  - 'Always provide a || fallback: github.event.head_commit.message || ''Scheduled run'' handles both push and non-push'
+  - 'Prefer github.actor, github.ref_name, and github.run_number — these are populated for every event type'
+  - 'Check context availability in the GitHub Docs contexts reference before using event-specific properties in run-name'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#run-name'
+    label: 'GitHub Docs: Workflow syntax — run-name'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/contexts#github-context'
+    label: 'GitHub Docs: github context — event-specific property availability'
+  - url: 'https://github.blog/changelog/2022-10-05-github-actions-run-name-and-workflow-run-title/'
+    label: 'GitHub Changelog: run-name and workflow run title (October 2022)'

package/package.json

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