@htekdev/actions-debugger 1.0.50 → 1.0.52

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

@@ -0,0 +1,155 @@
+id: caching-artifacts-036
+title: 'actions/cache post step skips save when job is cancelled — cache never populated after cancellation'
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - actions-cache
+  - job-cancellation
+  - post-step
+  - cache-save
+  - cancel-in-progress
+  - concurrency
+  - always
+patterns:
+  - regex: 'Post\s+Run\s+actions/cache.*skipped|Cache\s+save\s+skipped'
+    flags: 'i'
+  - regex: 'uses:\s*actions/cache@'
+    flags: 'i'
+error_messages:
+  - 'Post Run actions/cache@v4 skipped'
+  - 'Cache save skipped'
+  - '##[warning]Cache save skipped.'
+  - 'Warning: Cache save failed.'
+root_cause: |
+  The actions/cache action saves the cache in a lifecycle "post" step that runs
+  automatically after the main job steps complete. When a job is cancelled — via
+  the Actions UI, concurrency cancel-in-progress, or exceeding job timeout-minutes
+  — post steps do NOT execute.
+
+  This creates a cache starvation loop:
+  1. Job starts with cache miss — slow dependency installation begins (minutes)
+  2. A new push triggers another workflow run while the first is still installing
+  3. concurrency: cancel-in-progress terminates the first run mid-install
+  4. The first run never reaches its post step — cache is not saved
+  5. The second run also sees a cache miss — the same slow install repeats
+  6. Repeated cancellations mean the cache is never populated
+
+  This is invisible in workflow logs: cancelled jobs simply show as cancelled with
+  no specific warning about the cache post step being skipped. Teams diagnose it
+  as "caching isn't working" without realizing cancellation is the root cause.
+
+  Affected workflows:
+  - Any workflow with concurrency: cancel-in-progress that also uses actions/cache
+  - Workflows with aggressive job timeout-minutes that expire during installs
+  - Flaky workflows that are frequently manually cancelled and re-run
+  - Matrix workflows where one failing matrix branch cancels siblings
+
+  When a job fails (but is not cancelled), post steps DO run normally — the issue
+  is specific to cancellations and hard timeouts.
+fix: |
+  Use the split actions/cache/restore + actions/cache/save pattern with
+  if: always() on the save step. This gives explicit control over cache saving
+  independent of the job lifecycle hooks:
+
+    - uses: actions/cache/restore@v4
+      id: cache-restore
+      with:
+        key: ...
+        path: ...
+
+    # ... install and build steps ...
+
+    - uses: actions/cache/save@v4
+      if: always()
+      with:
+        key: ${{ steps.cache-restore.outputs.cache-primary-key }}
+        path: ...
+
+  The split restore/save pattern (available since actions/cache v3.3.0 in 2023)
+  runs the save as an explicit step with if: always(), which executes during the
+  graceful shutdown window even when the job is being cancelled.
+
+  Important caveat: if the runner process is killed with SIGKILL (hard preemption,
+  host failure), no steps including if: always() will run — this is a
+  platform-level constraint outside GitHub Actions' control.
+fix_code:
+  - language: yaml
+    label: 'Split restore/save pattern with unconditional save to survive cancellation'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          # Even with cancel-in-progress, the explicit save step will run
+          concurrency:
+            group: ${{ github.workflow }}-${{ github.ref }}
+            cancel-in-progress: true
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Restore cached dependencies
+              uses: actions/cache/restore@v4
+              id: cache-restore
+              with:
+                path: ~/.npm
+                key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
+                restore-keys: |
+                  ${{ runner.os }}-npm-
+
+            - name: Install dependencies
+              if: steps.cache-restore.outputs.cache-hit != 'true'
+              run: npm ci
+
+            - name: Run tests
+              run: npm test
+
+            - name: Save cache
+              uses: actions/cache/save@v4
+              if: always()   # Runs during graceful cancellation shutdown window
+              with:
+                path: ~/.npm
+                key: ${{ steps.cache-restore.outputs.cache-primary-key }}
+
+  - language: yaml
+    label: 'Python pip cache with split save pattern'
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Restore pip cache
+              uses: actions/cache/restore@v4
+              id: pip-cache
+              with:
+                path: ~/.cache/pip
+                key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements*.txt') }}
+                restore-keys: |
+                  ${{ runner.os }}-pip-
+
+            - name: Install Python dependencies
+              run: pip install -r requirements.txt
+
+            - name: Run pytest
+              run: pytest
+
+            - name: Save pip cache
+              uses: actions/cache/save@v4
+              if: always()
+              with:
+                path: ~/.cache/pip
+                key: ${{ steps.pip-cache.outputs.cache-primary-key }}
+prevention:
+  - 'Prefer the split actions/cache/restore + actions/cache/save pattern over the combined actions/cache action for any workflow using concurrency: cancel-in-progress'
+  - 'Always add if: always() to explicit cache save steps so they execute regardless of upstream step failure or cancellation signal'
+  - 'Monitor workflow logs for "Post Run actions/cache skipped" messages — this is a reliable indicator that cache is never being populated after cancellations'
+  - 'Use actions/cache v3.3.0 or later — the split restore/save subactions were introduced in that release'
+docs:
+  - url: 'https://github.com/actions/cache/blob/main/save/README.md'
+    label: 'actions/cache: Explicit save action documentation'
+  - url: 'https://github.com/actions/cache#save-action'
+    label: 'actions/cache: Split restore and save usage pattern'
+  - url: 'https://github.com/orgs/community/discussions/47469'
+    label: 'GitHub Community #47469: Cache not saved when workflow is cancelled'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-syntax-for-github-actions#jobsjob_idstepsif'
+    label: 'GitHub Docs: Using conditions to control job execution'

package/errors/permissions-auth/permissions-auth-038.yml

@@ -0,0 +1,148 @@
+id: permissions-auth-038
+title: 'secrets: inherit does not propagate environment-scoped secrets to reusable workflows'
+category: permissions-auth
+severity: silent-failure
+tags:
+  - secrets-inherit
+  - reusable-workflows
+  - environment-secrets
+  - workflow-call
+  - empty-secret
+  - deployment-environment
+patterns:
+  - regex: 'secrets:\s*inherit'
+    flags: 'i'
+  - regex: 'uses:\s*[./\w@-]+\.ya?ml\b'
+    flags: 'i'
+error_messages:
+  - 'Error: Input required and not supplied'
+  - 'Secret value is empty in reusable workflow'
+  - '##[error]The secret variable name is invalid'
+root_cause: |
+  When a caller workflow uses secrets: inherit to call a reusable workflow
+  (on.workflow_call), GitHub passes repository-level and organization-level
+  secrets to the called workflow. However, environment-scoped secrets are NOT
+  inherited — they arrive as empty strings with no error or warning.
+
+  Environment secrets are tied to a named deployment environment (e.g.,
+  "production", "staging") and are only accessible to jobs that declare
+  environment: <name> in their configuration. The secrets: inherit mechanism
+  operates at the repository/org secret scope level. It cannot bridge environment
+  context to a called workflow's jobs because those jobs run in a separate
+  workflow execution context and do not inherit the caller job's environment
+  declaration.
+
+  Failure scenario:
+  1. Caller job declares environment: production (activates env secrets in the caller)
+  2. Caller job uses secrets: inherit to call ./reusable.yml
+  3. Reusable workflow job reads secrets.PROD_DB_PASSWORD (an environment secret)
+  4. Reusable workflow job sees PROD_DB_PASSWORD as empty string
+  5. No error is thrown — the secret silently resolves to ""
+
+  This is documented as a GitHub platform limitation in the reusable workflows
+  documentation. GitHub Community discussion #26671 has many reports of this
+  surprising behavior.
+
+  Distinction from permissions-auth-037 (environment-secrets-job-scope):
+  - permissions-auth-037 covers jobs in the SAME workflow that lack environment:
+    declarations failing to access environment secrets.
+  - This entry covers the cross-workflow boundary where secrets: inherit does not
+    transfer environment secrets from caller to called workflow at all.
+fix: |
+  Explicitly declare and map environment secrets at the workflow_call boundary.
+  In the reusable workflow, declare each secret in the on.workflow_call.secrets
+  block. At the call site, explicitly pass each environment secret using the
+  secrets: mapping block (not secrets: inherit):
+
+  In the reusable workflow (workflow_call trigger):
+    on:
+      workflow_call:
+        secrets:
+          db_password:
+            required: true
+          api_key:
+            required: false
+
+  In the calling workflow:
+    jobs:
+      deploy:
+        environment: production
+        uses: ./.github/workflows/deploy.yml
+        secrets:
+          db_password: ${{ secrets.PROD_DB_PASSWORD }}
+          api_key: ${{ secrets.PROD_API_KEY }}
+
+  Alternatively, if the reusable workflow is in the same repository and the
+  environment name is fixed, you can declare environment: production on the job
+  inside the reusable workflow directly. This makes environment secrets accessible
+  in the called workflow at the cost of coupling it to a specific environment name.
+
+  Note: secrets: inherit and explicit secrets: mapping cannot be combined on the
+  same uses: step. Choose one approach: either inherit all repo/org secrets, or
+  map explicitly (which also allows passing environment secrets).
+fix_code:
+  - language: yaml
+    label: 'Reusable workflow — declare required secrets in workflow_call trigger'
+    code: |
+      # .github/workflows/deploy-reusable.yml
+      on:
+        workflow_call:
+          secrets:
+            db_password:
+              required: true
+            api_key:
+              required: true
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Deploy application
+              env:
+                DB_PASSWORD: ${{ secrets.db_password }}
+                API_KEY: ${{ secrets.api_key }}
+              run: ./scripts/deploy.sh
+
+  - language: yaml
+    label: 'Caller workflow — explicitly map environment secrets (not secrets: inherit)'
+    code: |
+      # .github/workflows/deploy-caller.yml
+      jobs:
+        call-deploy:
+          environment: production       # Activates environment secrets in this calling job
+          uses: ./.github/workflows/deploy-reusable.yml
+          # WRONG: secrets: inherit     -- passes repo/org secrets but NOT environment secrets
+          secrets:
+            db_password: ${{ secrets.PROD_DB_PASSWORD }}    # Environment secret — must be explicit
+            api_key: ${{ secrets.PROD_API_KEY }}            # Environment secret — must be explicit
+
+  - language: yaml
+    label: 'Alternative — declare environment inside the reusable workflow job'
+    code: |
+      # .github/workflows/deploy-reusable.yml (alternative approach)
+      on:
+        workflow_call: {}
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          environment: production       # Directly activates environment secrets here
+          steps:                        # Couples reusable workflow to environment name
+            - name: Deploy application
+              env:
+                DB_PASSWORD: ${{ secrets.PROD_DB_PASSWORD }}
+              run: ./scripts/deploy.sh
+prevention:
+  - 'Never rely on secrets: inherit to pass environment-scoped secrets — always map them explicitly in the secrets: block of the workflow_call invocation'
+  - 'In reusable workflows, declare all required secrets in on.workflow_call.secrets with required: true so missing secrets fail loudly rather than silently resolving to empty strings'
+  - 'Document which secrets in your reusable workflow are environment-scoped vs repository-scoped so callers know the correct passing strategy'
+  - 'Test reusable workflows end-to-end from a caller workflow before deploying to production — secrets: inherit working in testing does not guarantee environment secrets work correctly'
+docs:
+  - url: 'https://docs.github.com/en/actions/sharing-automations/reusing-workflows#passing-secrets-to-called-workflows'
+    label: 'GitHub Docs: Passing secrets to called workflows'
+  - url: 'https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-an-environment'
+    label: 'GitHub Docs: Creating secrets for an environment'
+  - url: 'https://github.com/orgs/community/discussions/26671'
+    label: 'GitHub Community #26671: secrets: inherit not passing environment secrets'
+  - url: 'https://docs.github.com/en/actions/sharing-automations/reusing-workflows#limitations'
+    label: 'GitHub Docs: Reusable workflows — limitations'

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/runner-environment/runner-environment-110.yml

@@ -0,0 +1,113 @@
+id: runner-environment-110
+title: 'actions/checkout default fetch-depth:1 shallow clone breaks git describe and changelog generation'
+category: runner-environment
+severity: error
+tags:
+  - checkout
+  - fetch-depth
+  - shallow-clone
+  - git-describe
+  - versioning
+  - changelog
+  - tags
+  - release
+patterns:
+  - regex: 'fatal:\s*No names found.*cannot describe|No tag can describe'
+    flags: 'i'
+  - regex: 'fetch-depth:\s*[01]\b'
+    flags: 'i'
+error_messages:
+  - 'fatal: No names found, cannot describe anything.'
+  - 'fatal: No tags can describe ''HEAD''.'
+  - 'error: No annotated tags can describe'
+  - '##[error]fatal: no tag exactly matches'
+root_cause: |
+  actions/checkout defaults to fetch-depth: 1 — a shallow clone that downloads
+  only the single most recent commit. This optimizes CI download speed but breaks
+  any operation that requires commit history or reachable tag ancestry:
+
+  - git describe --tags: requires a tag somewhere in the commit ancestry chain.
+    With depth 1, no ancestor commits exist, so no tags are reachable unless the
+    HEAD commit IS exactly the tagged commit. Returns "fatal: No names found,
+    cannot describe anything."
+
+  - Changelog generators (conventional-changelog, release-please, git-cliff,
+    semantic-release): need commit history to determine what changed since the
+    last release. With depth 1, they see zero commits and produce empty changelogs.
+
+  - Semantic versioning tools that count commits since last tag always return 0
+    because no prior commits (and thus no tags) are in the shallow history.
+
+  - Branch comparison and merge-base operations: git merge-base fails or produces
+    incorrect results with no shared history available.
+
+  A common workaround attempt — using fetch-tags: true with fetch-depth: 1 —
+  fetches tag objects but NOT the commits they point to in history, so
+  git describe still fails. The tags exist as objects but are not reachable from
+  HEAD via the commit graph.
+
+  This is one of the most-discussed GitHub Community topics: the checkout step
+  looks correct, CI succeeds, but release version numbers or changelogs are
+  unexpectedly empty or wrong, often discovered only after a real release attempt.
+fix: |
+  Set fetch-depth: 0 to fetch complete commit history including all tags:
+
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+
+  For large repositories where full history is prohibitively slow, use targeted
+  approaches:
+  - fetch-depth: 50 covers the last 50 commits — sufficient for active repos
+    that tag frequently, but risky for repos with infrequent tagging.
+  - fetch-depth: 0 combined with --filter=blob:none (partial clone) gets history
+    metadata without full file blobs — not directly configurable in the action but
+    achievable via fetch options in post-checkout scripts for advanced cases.
+
+  For changelog and release tools (release-please, git-cliff, semantic-release,
+  conventional-changelog), always use fetch-depth: 0. These tools explicitly
+  require full history and their documentation states this requirement.
+fix_code:
+  - language: yaml
+    label: 'Full history checkout for git describe and changelog generation tools'
+    code: |
+      jobs:
+        release:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                fetch-depth: 0   # Full history required for version detection and changelogs
+                # Default fetch-depth: 1 (shallow) causes "No names found, cannot describe"
+
+            - name: Generate changelog
+              uses: orhun/git-cliff-action@v3
+              with:
+                config: cliff.toml
+
+  - language: yaml
+    label: 'Partial depth with fetch-tags for large repos — use with caution'
+    code: |
+      jobs:
+        version:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                fetch-depth: 100   # Last 100 commits — sufficient for frequently-tagged repos
+                fetch-tags: true   # Fetch tag objects so they appear in tag list
+                # WARNING: fetch-tags: true with a shallow clone fetches tag OBJECTS
+                # but NOT their commit ancestors — git describe may still fail if
+                # the tag is older than fetch-depth commits. Use fetch-depth: 0 to be safe.
+prevention:
+  - 'Set fetch-depth: 0 in any workflow that uses git describe, generates a changelog, or computes a semantic version from commit history'
+  - 'Document in your workflow why fetch-depth: 0 is required so future maintainers do not revert it to the shallow default'
+  - 'Do not assume fetch-tags: true solves shallow clone limitations for git describe — the tag objects must be reachable in the commit graph'
+  - 'Keep the default fetch-depth: 1 only for workflows that never need commit history — pure build and test jobs with no versioning or history analysis'
+docs:
+  - url: 'https://github.com/actions/checkout#usage'
+    label: 'actions/checkout: fetch-depth parameter documentation'
+  - url: 'https://github.com/orgs/community/discussions/25702'
+    label: 'GitHub Community: git describe fails with actions/checkout shallow clone'
+  - url: 'https://github.com/actions/checkout/issues/701'
+    label: 'actions/checkout #701: fetch-tags does not help with git describe on shallow clone'

package/errors/silent-failures/silent-failures-053.yml

@@ -0,0 +1,111 @@
+id: silent-failures-053
+title: 'workflow_dispatch boolean inputs arrive as strings — if: inputs.flag is always truthy'
+category: silent-failures
+severity: silent-failure
+tags:
+  - workflow-dispatch
+  - boolean-inputs
+  - type-coercion
+  - inputs-context
+  - string-comparison
+  - if-condition
+patterns:
+  - regex: 'inputs\.\w+\s*==\s*true\b'
+    flags: 'i'
+  - regex: 'if:\s*inputs\.\w+'
+    flags: 'i'
+error_messages:
+  - 'Step always runs even when boolean input is set to false'
+  - 'Boolean workflow_dispatch input behaves as truthy regardless of value'
+root_cause: |
+  GitHub Actions workflow_dispatch inputs defined with type: boolean are passed
+  to the workflow as strings ("true" or "false"), not as JavaScript/YAML booleans.
+
+  This means three common patterns silently misbehave:
+  - if: inputs.dry_run                      evaluates to always truthy (non-empty string)
+  - if: inputs.dry_run == true              always false (string "true" != boolean true)
+  - if: inputs.dry_run == false             always false (string "false" != boolean false)
+
+  The GitHub Actions expression evaluator converts the inputs context to strings
+  at the boundary between the event payload and the workflow context. Even though
+  the UI renders a checkbox, the underlying value is the literal string "true" or
+  "false". This behavior is consistent across workflow_dispatch and workflow_call
+  inputs of type boolean.
+
+  GitHub Community discussion #51504 documents this as expected behavior, but
+  thousands of developers are surprised by the mismatch between the checkbox UI
+  and the string runtime value.
+
+  Affected patterns:
+  - if: inputs.dry_run (truthy check — always true for any non-empty string value)
+  - if: inputs.flag == true (boolean comparison — always false for string "true")
+  - Ternary: ${{ inputs.flag && 'yes' || 'no' }} returns "yes" even when flag is "false"
+fix: |
+  Always compare workflow_dispatch boolean inputs to the string literal 'true'
+  or 'false':
+
+  - if: inputs.dry_run == 'true'       correct
+  - if: inputs.dry_run != 'true'       correct negation (catches "false" and "")
+  - if: inputs.dry_run == true         WRONG — string never equals boolean
+  - if: inputs.dry_run                 WRONG — always truthy for non-empty string
+
+  For workflow_call with boolean inputs, the same string coercion applies when
+  the calling workflow passes the value via the inputs: block.
+
+  The fromJSON() function converts the string to a real boolean if needed for
+  complex conditions: fromJSON(inputs.dry_run) returns actual true/false booleans.
+fix_code:
+  - language: yaml
+    label: 'Correct boolean input comparison using string equality'
+    code: |
+      on:
+        workflow_dispatch:
+          inputs:
+            dry_run:
+              description: 'Run without making changes'
+              type: boolean
+              default: false
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Deploy (skip if dry run)
+              # WRONG: if: inputs.dry_run          -- always truthy (non-empty string)
+              # WRONG: if: inputs.dry_run == true   -- string never equals boolean
+              if: inputs.dry_run != 'true'
+              run: echo "Deploying..."
+
+            - name: Dry run notice
+              if: inputs.dry_run == 'true'
+              run: echo "Dry run mode — no changes made"
+
+  - language: yaml
+    label: 'Use fromJSON() to convert to real boolean for complex conditions'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Conditional step using fromJSON conversion
+              if: fromJSON(inputs.dry_run) == false
+              run: echo "Not a dry run — proceeding"
+
+            - name: Set environment variable from boolean input
+              env:
+                # fromJSON converts "true"/"false" string to actual boolean
+                DRY_RUN: ${{ fromJSON(inputs.dry_run) }}
+              run: |
+                echo "Dry run mode: $DRY_RUN"
+prevention:
+  - 'Always compare workflow_dispatch boolean inputs to the string literal ''true'' or ''false'', not to boolean true/false'
+  - 'Never use ''if: inputs.flag'' alone as a boolean check — the non-empty string "false" is truthy in GitHub Actions expressions'
+  - 'Use fromJSON(inputs.flag) when you need a real boolean value in expressions or env: context'
+  - 'Add a comment in your workflow noting that boolean dispatch inputs are strings at runtime to warn future maintainers'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-syntax-for-github-actions#onworkflow_dispatchinputs'
+    label: 'GitHub Docs: workflow_dispatch inputs syntax'
+  - url: 'https://github.com/orgs/community/discussions/51504'
+    label: 'GitHub Community #51504: Boolean inputs in workflow_dispatch are strings'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/evaluate-expressions-in-workflows-and-actions#fromjson'
+    label: 'GitHub Docs: fromJSON expression function'

package/package.json

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