@htekdev/actions-debugger 1.0.120 → 1.0.122

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

@@ -0,0 +1,114 @@
+id: caching-artifacts-071
+title: 'actions/cache Fails on Self-Hosted Runner with IPv6 Cache Server URL'
+category: caching-artifacts
+severity: error
+tags:
+  - cache
+  - ipv6
+  - self-hosted
+  - getaddrinfo
+  - ENOTFOUND
+  - internal-cache
+patterns:
+  - regex: 'getaddrinfo ENOTFOUND \[[\da-fA-F:]+\]'
+    flags: 'i'
+  - regex: 'getCacheEntry failed.*getaddrinfo ENOTFOUND'
+    flags: 'i'
+  - regex: 'reserveCache failed.*getaddrinfo ENOTFOUND.*\['
+    flags: 'i'
+error_messages:
+  - "::warning::Failed to restore: getCacheEntry failed: getaddrinfo ENOTFOUND [2001:bc8:1d90:1fc1:dc00:ff:fe2b:3f97]"
+  - "::warning::Failed to save: reserveCache failed: getaddrinfo ENOTFOUND [2001:db8::1]"
+root_cause: |
+  When GitHub Actions self-hosted runner infrastructure uses an IPv6 address for
+  the internal cache service URL (ACTIONS_CACHE_URL), the @actions/http-client
+  in the toolkit fails to connect because it treats the bracketed IPv6 literal
+  as a hostname string instead of an address.
+
+  DNS resolution of `[2001:bc8:...]` fails with ENOTFOUND because the brackets
+  are IANA-standard URL notation for IPv6 literals in HTTP URLs
+  (RFC 2732 / RFC 3986 section 3.2.2), but the toolkit's Node.js http-client
+  was passing the bracketed string directly to `getaddrinfo()` without stripping
+  the brackets first. getaddrinfo does not accept bracket-wrapped IPv6 literals
+  and returns ENOTFOUND.
+
+  This affects any self-hosted runner environment where:
+  - The cache service is configured with an IPv6 address directly in the URL
+    (e.g., ACTIONS_CACHE_URL=http://[2001:bc8::1]:3000/)
+  - This includes ARC (Actions Runner Controller) on IPv6-only Kubernetes clusters,
+    enterprise GitHub Actions server deployments, and any on-prem cache proxy
+    bound to an IPv6 interface
+
+  The fix (strip brackets before passing to http-client) was submitted as PR
+  actions/toolkit#2298. Until merged and released in a new version of actions/cache,
+  the bug is present in actions/cache@v3, v4, and v5.
+fix: |
+  Short-term workarounds (choose one):
+
+  1. Configure the internal cache service to also listen on an IPv4 address or
+     hostname and set ACTIONS_CACHE_URL to use the IPv4 address or hostname:
+       export ACTIONS_CACHE_URL=http://cache.internal:3000/
+       export ACTIONS_CACHE_URL=http://192.168.1.10:3000/
+
+  2. Set ACTIONS_CACHE_URL to use the hostname that resolves to the IPv6 address
+     (DNS-based resolution of the hostname works; the issue is only with bare
+     IPv6 literals in brackets):
+       export ACTIONS_CACHE_URL=http://cache-server.local:3000/
+
+  3. Add the cache service IPv6 address to /etc/hosts with a hostname alias on
+     the runner and use that hostname in ACTIONS_CACHE_URL.
+
+  Long-term: Track actions/toolkit#2298 for the upstream fix. Once merged and
+  actions/cache releases a new version using the patched toolkit, upgrade to
+  that version.
+fix_code:
+  - language: yaml
+    label: 'Broken — ACTIONS_CACHE_URL with IPv6 literal causes ENOTFOUND'
+    code: |
+      # Runner environment configuration (runsvc.sh or .env file):
+      # ACTIONS_CACHE_URL=http://[2001:bc8:1d90:1fc1:dc00:ff:fe2b:3f97]:3000/
+      #
+      # Workflow sees:
+      # ::warning::Failed to restore: getCacheEntry failed: getaddrinfo ENOTFOUND [2001:bc8:...]
+
+      - uses: actions/cache@v5
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-npm-${{ hashFiles('package-lock.json') }}
+      # Warning: cache restore/save fails silently with ENOTFOUND
+
+  - language: yaml
+    label: 'Fixed — set ACTIONS_CACHE_URL to hostname or IPv4 instead of IPv6 literal'
+    code: |
+      # Runner environment configuration — use hostname instead of IPv6 literal:
+      # ACTIONS_CACHE_URL=http://cache.internal:3000/
+      # -or-
+      # ACTIONS_CACHE_URL=http://192.168.1.10:3000/
+      #
+      # The cache action now resolves the hostname normally:
+      - uses: actions/cache@v5
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-npm-${{ hashFiles('package-lock.json') }}
+
+  - language: yaml
+    label: 'Diagnostic — detect IPv6 ENOTFOUND cache failures in workflow output'
+    code: |
+      - name: Check cache URL for IPv6 literal
+        run: |
+          if [[ "${ACTIONS_CACHE_URL:-}" =~ ^\[.*\] ]] || [[ "${ACTIONS_CACHE_URL:-}" == *"["* ]]; then
+            echo "::warning::ACTIONS_CACHE_URL contains an IPv6 literal: ${ACTIONS_CACHE_URL}"
+            echo "::warning::Cache actions will fail with ENOTFOUND. Use a hostname or IPv4 address instead."
+          fi
+
+prevention:
+  - 'Always configure ACTIONS_CACHE_URL with a hostname or IPv4 address, not a bare IPv6 literal in brackets.'
+  - 'When deploying ARC or enterprise runner infrastructure on IPv6-only Kubernetes nodes, set up a hostname alias for the cache service.'
+  - 'Test cache operations with a simple cache-hit workflow on a new self-hosted runner before deploying to production.'
+docs:
+  - url: 'https://github.com/actions/cache/issues/1718'
+    label: 'actions/cache#1718 — Caching fails on IPv6 cache server'
+  - url: 'https://github.com/actions/toolkit/pull/2298'
+    label: 'actions/toolkit#2298 — Fix: correctly handle IPv6 literals in http-client'
+  - url: 'https://www.rfc-editor.org/rfc/rfc3986#section-3.2.2'
+    label: 'RFC 3986 §3.2.2 — IPv6 literals in URL host component (bracket notation)'

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

@@ -0,0 +1,120 @@
+id: runner-environment-219
+title: 'pnpm/action-setup@v6.0.0 Always Installs pnpm v11 Regardless of Requested Version'
+category: runner-environment
+severity: error
+tags:
+  - pnpm
+  - action-setup
+  - pnpm-v11
+  - version-mismatch
+  - path-priority
+  - lockfile
+patterns:
+  - regex: 'ERR_PNPM_UNSUPPORTED_ENGINE.*Unsupported environment'
+    flags: 'i'
+  - regex: 'Expected version:.*Got:.*11\.'
+    flags: 'i'
+  - regex: 'ERR_PNPM_LOCKFILE_CONFIG_MISMATCH.*frozen installation'
+    flags: 'i'
+  - regex: 'ERR_PNPM_BROKEN_LOCKFILE.*expected a single document'
+    flags: 'i'
+error_messages:
+  - "ERR_PNPM_UNSUPPORTED_ENGINE  Unsupported environment (bad pnpm and/or Node.js version)"
+  - "Expected version: 10\n  Got: 11.0.0-beta.4-1"
+  - "ERR_PNPM_LOCKFILE_CONFIG_MISMATCH  Cannot proceed with the frozen installation. The current \"overrides\" configuration doesn't match the value found in the lockfile"
+  - "ERR_PNPM_BROKEN_LOCKFILE  The lockfile at \"<path>/pnpm-lock.yaml\" is broken: expected a single document in the stream, but found more"
+root_cause: |
+  pnpm/action-setup@v6.0.0 introduced a "self-managed" bootstrap mechanism where
+  pnpm installs itself using pnpm. The action downloads a bootstrap binary (pnpm v11)
+  and uses it to self-update to the requested version. However, in v6.0.0 through
+  v6.0.7, a PATH priority bug caused the bootstrap binary to shadow the correctly
+  installed version at runtime:
+
+    addPath(path.join(pnpmHome, 'bin'))  // correct binary installed here
+    addPath(pnpmHome)                    // bootstrap v11 binary lives here
+
+  Because addPath prepends in reverse call order, PNPM_HOME (containing the bootstrap
+  v11 binary) was always first on PATH, shadowing PNPM_HOME/bin (containing the
+  self-updated target version). Any workflow step that ran `pnpm` therefore used v11
+  regardless of the `version:` input.
+
+  Side effects of this bug:
+  1. workflows specifying `version: 10` run with pnpm v11, triggering
+     ERR_PNPM_UNSUPPORTED_ENGINE if engines.pnpm is set in package.json
+  2. pnpm v11 writes `configDependencies` blocks into pnpm-lock.yaml during any
+     install, corrupting the lockfile from pnpm v10's perspective; subsequent
+     `--frozen-lockfile` installs fail with ERR_PNPM_LOCKFILE_CONFIG_MISMATCH
+  3. When using `package_json_file:` input, the wrong version is read because pnpm
+     v11 changed lockfile format, causing ERR_PNPM_BROKEN_LOCKFILE when the v11
+     bootstrap writes partial YAML to the lockfile before the correct version takes
+     over
+
+  The fix (addPath call order swap) was merged in PR #230 and released in v6.0.1.
+  A separate bootstrap bundle update for pnpm 11.0.0-rc.2 was released in v6.0.3.
+  Full stability for most scenarios reached v6.0.8.
+fix: |
+  Upgrade to pnpm/action-setup@v6.0.8 or later. The PATH priority bug and
+  configDependencies lockfile corruption are fixed in v6.0.1+.
+
+  If you cannot upgrade, pin back to v5:
+
+    - uses: pnpm/action-setup@v5
+      with:
+        version: 10
+
+  If you are on v6 and seeing lockfile corruption: delete the corrupted
+  pnpm-lock.yaml and regenerate it with the correct pnpm version locally
+  before re-running CI. Do NOT run pnpm install in the corrupted-lockfile
+  state as it will write a v11 lockfile into your repo.
+fix_code:
+  - language: yaml
+    label: 'Broken — pnpm/action-setup@v6.0.0 installs v11 regardless of version input'
+    code: |
+      - uses: pnpm/action-setup@v6      # v6.0.0: PATH bug installs v11 always
+        with:
+          version: 10                   # Ignored — v11 ends up on PATH
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'pnpm'
+      - run: pnpm install --frozen-lockfile
+        # Fails: ERR_PNPM_LOCKFILE_CONFIG_MISMATCH or ERR_PNPM_UNSUPPORTED_ENGINE
+
+  - language: yaml
+    label: 'Fixed — upgrade to v6.0.8+ (PATH priority bug resolved)'
+    code: |
+      - uses: pnpm/action-setup@v6.0.8  # v6.0.8: PATH priority fixed, stable
+        with:
+          version: 10
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'pnpm'
+      - run: pnpm install --frozen-lockfile
+
+  - language: yaml
+    label: 'Alternative fix — pin back to v5 until v6 is stable for your project'
+    code: |
+      - uses: pnpm/action-setup@v5
+        with:
+          version: 10
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'pnpm'
+      - run: pnpm install --frozen-lockfile
+
+prevention:
+  - 'Pin pnpm/action-setup to a specific minor/patch version (e.g. @v6.0.8) rather than @v6 to avoid silent major-bump breakage from Dependabot.'
+  - 'After upgrading pnpm/action-setup, verify `pnpm --version` in the first step matches the requested version before running install.'
+  - 'If pnpm-lock.yaml is corrupted by this bug, delete it and regenerate locally with the correct pnpm version — do not attempt to fix by re-running CI.'
+  - 'Set `engines.pnpm` in package.json to detect unexpected version mismatches early with ERR_PNPM_UNSUPPORTED_ENGINE rather than silent wrong-behavior.'
+docs:
+  - url: 'https://github.com/pnpm/action-setup/issues/225'
+    label: 'pnpm/action-setup#225 — v6.0.0 always installs v11 (51 reactions)'
+  - url: 'https://github.com/pnpm/action-setup/issues/226'
+    label: 'pnpm/action-setup#226 — v6.0.0 modifies pnpm-lock.yaml (lockfile corruption)'
+  - url: 'https://github.com/pnpm/action-setup/pull/230'
+    label: 'pnpm/action-setup#230 — Fix: swap addPath call order (merged)'
+  - url: 'https://github.com/pnpm/action-setup/releases'
+    label: 'pnpm/action-setup releases — v6.0.1 contains the PATH fix'

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

@@ -0,0 +1,123 @@
+id: runner-environment-220
+title: 'Node.js 20 JavaScript Actions Runtime Deprecated — Forced Migration to Node.js 24 (June 2026)'
+category: runner-environment
+severity: warning
+tags:
+  - nodejs
+  - node20
+  - node24
+  - javascript-actions
+  - deprecation
+  - runtime
+  - actions-upgrade
+patterns:
+  - regex: 'Node\.js 20 actions are deprecated'
+    flags: 'i'
+  - regex: 'running on Node\.js 20 and may not work as expected'
+    flags: 'i'
+  - regex: 'Actions will be forced to run with Node\.js 24 by default'
+    flags: 'i'
+  - regex: 'FORCE_JAVASCRIPT_ACTIONS_TO_NODE24'
+    flags: 'i'
+error_messages:
+  - "Node.js 20 actions are deprecated. The following actions are running on Node.js 20 and may not work as expected: actions/deploy-pages@v4."
+  - "Actions will be forced to run with Node.js 24 by default starting June 2nd, 2026."
+  - "Please check if updated versions of these actions are available that support Node.js 24."
+root_cause: |
+  GitHub Actions JavaScript action runtimes follow Node.js LTS lifecycle.
+  Node.js 20 reached end-of-life in April 2026, and GitHub deprecated it as a
+  supported JavaScript actions runtime in September 2025:
+
+  - Sept 2025: Deprecation announced. Warning annotation added to workflow runs.
+  - Feb 2026: Runner v2.322+ begins emitting "Node.js 20 actions are deprecated"
+    annotation for any action whose package.json specifies "main" with runs.using: node20.
+  - June 2, 2026: Forced migration. Actions using node20 runtime are automatically
+    upgraded to run on Node.js 24 unless ACTIONS_ALLOW_USE_UNSECURE_NODE_VERSION=true
+    is set.
+
+  Actions affected are those that declare `runs.using: node20` in their action.yml.
+  This is a property of the action itself, not the workflow caller. Common examples
+  that shipped with node20 and required major version bumps:
+    - actions/deploy-pages@v4 → upgrade to @v5
+    - actions/upload-pages-artifact@v3 → upgrade to @v4
+    - Third-party actions on older major versions
+
+  The warning does NOT cause workflow failures in most cases — the runner upgrades
+  the action to run under Node.js 24 automatically starting June 2, 2026. However:
+  1. Actions using APIs removed or changed between Node.js 20 and 24 (e.g., internal
+     crypto or buffer APIs) may silently produce wrong results or throw runtime errors
+  2. The warning annotation shows up in every workflow run's annotation panel,
+     cluttering the UI and masking real warnings
+  3. Some security-conscious pipelines treat any annotation as a build failure
+     via fail-on-annotations settings
+fix: |
+  1. Identify which actions in your workflow are still on node20 runtime:
+     Look for "Node.js 20 actions are deprecated" annotations in the Workflow Annotations
+     panel (gear icon next to workflow run summary).
+
+  2. Upgrade the pinned version of the affected action to a release that uses node24:
+       - actions/deploy-pages@v4 → @v5
+       - actions/upload-pages-artifact@v3 → @v4
+       - For third-party actions: check their releases for "node24" or "Node.js 24" mentions
+
+  3. If no node24 version of a required action exists yet, set the opt-out env var
+     as a temporary measure (not recommended for production):
+       env:
+         ACTIONS_ALLOW_USE_UNSECURE_NODE_VERSION: 'true'
+
+  4. To opt into Node.js 24 early for a specific workflow (before June 2 deadline):
+       env:
+         FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: 'true'
+fix_code:
+  - language: yaml
+    label: 'Broken — actions/deploy-pages@v4 uses node20 runtime (shows deprecation warning)'
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Deploy to GitHub Pages
+              uses: actions/deploy-pages@v4    # node20 runtime — triggers deprecation warning
+
+  - language: yaml
+    label: 'Fixed — upgrade to v5 which uses node24 runtime'
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Deploy to GitHub Pages
+              uses: actions/deploy-pages@v5    # node24 runtime — no deprecation warning
+
+  - language: yaml
+    label: 'Temporary opt-out — allow node20 actions to run (not recommended long-term)'
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          env:
+            ACTIONS_ALLOW_USE_UNSECURE_NODE_VERSION: 'true'   # Suppresses forced upgrade
+          steps:
+            - uses: actions/deploy-pages@v4    # Still runs on node20 (insecure)
+
+  - language: yaml
+    label: 'Find all node20 actions in your workflow via actionlint annotation grep'
+    code: |
+      # Run actionlint locally or in CI to list all outdated action runtimes:
+      # actionlint .github/workflows/*.yml | grep "node20"
+      #
+      # Or use gh CLI to scan your workflow annotation after a run:
+      # gh run view <run-id> --json annotations --jq '.annotations[] | select(.message | contains("Node.js 20"))'
+
+prevention:
+  - 'Subscribe to the GitHub Actions changelog (https://github.blog/changelog/label/github-actions/) to catch runtime deprecation announcements early.'
+  - 'Use Dependabot for GitHub Actions to get automatic PRs when new major versions of actions are released with updated runtimes.'
+  - 'Run actionlint in CI — it can detect actions using deprecated node runtime versions.'
+  - 'When pinning third-party actions to SHA hashes, periodically check if newer major versions with updated runtimes have been released.'
+docs:
+  - url: 'https://github.blog/changelog/2025-09-19-deprecation-of-node-20-on-github-actions-runners/'
+    label: 'GitHub Changelog — Deprecation of Node.js 20 on GitHub Actions runners (Sept 2025)'
+  - url: 'https://github.com/actions/deploy-pages/issues/410'
+    label: 'actions/deploy-pages#410 — Support Node.js 24 (36 reactions)'
+  - url: 'https://docs.github.com/en/actions/sharing-automations/creating-actions/metadata-syntax-for-github-actions#runsusing'
+    label: 'GitHub Docs — runs.using in action.yml (supported runtime versions)'

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

@@ -0,0 +1,145 @@
+id: runner-environment-221
+title: 'actions/checkout@v6 Hangs at git-credential-osxkeychain on macOS Self-Hosted Runners with Concurrent Jobs'
+category: runner-environment
+severity: error
+tags:
+  - checkout
+  - macos
+  - osxkeychain
+  - credential-helper
+  - deadlock
+  - self-hosted
+  - concurrent
+  - v6
+  - hang
+patterns:
+  - regex: 'trace: start_command:.*git-credential-osxkeychain store'
+    flags: 'i'
+  - regex: 'trace: run_command: .?git credential-osxkeychain store.?$'
+    flags: 'im'
+  - regex: 'credential-osxkeychain store.*\n.*\n.*\n.*\n.*checkout.*hang'
+    flags: 'im'
+error_messages:
+  - "trace: run_command: 'git credential-osxkeychain store'"
+  - "trace: start_command: /bin/sh -c 'git credential-osxkeychain store' 'git credential-osxkeychain store'"
+  - "trace: exec: git-credential-osxkeychain store"
+  - "trace: start_command: /opt/homebrew/opt/git/libexec/git-core/git-credential-osxkeychain store"
+root_cause: |
+  On macOS self-hosted runners, Git uses git-credential-osxkeychain as the default
+  credential helper. When actions/checkout@v6 runs with persist-credentials: true
+  (the default), it stores the GITHUB_TOKEN in the macOS Keychain via the osxkeychain
+  credential helper.
+
+  The macOS Keychain grants exclusive write locks to one process at a time. When two or
+  more jobs run actions/checkout@v6 concurrently on the same self-hosted runner machine,
+  both jobs attempt to call `git credential-osxkeychain store` simultaneously. One process
+  acquires the Keychain lock and proceeds; the other blocks indefinitely waiting for the
+  lock to be released — which never happens because the macOS Keychain's IPC mechanism
+  can deadlock under concurrent access from multiple git processes sharing the same runner
+  session.
+
+  The hung checkout step produces no error output — the last visible log lines are the
+  `git-credential-osxkeychain store` trace entries. The job appears to be running but
+  makes no progress. Without a step-level timeout, GitHub's 6-hour job timeout eventually
+  cancels it.
+
+  Affected environment:
+  - actions/checkout@v6 (v6.0.x, the version that changed credential handling)
+  - macOS self-hosted runners, including macOS 26 Tahoe (runner 2.331.0+)
+  - Reproduced when ≥2 jobs on the same runner machine execute checkout concurrently
+  - Not specific to runner 2.331.0 — also reported on earlier macOS self-hosted setups
+    since checkout@v2, but became more frequent with v6's credential handling changes
+
+  Distinct from runner-environment-032 (persist-credentials: false breaks subsequent
+  git push auth — the opposite direction: fixing the push but needing credentials).
+fix: |
+  Two workarounds — try Option 1 first, fall back to Option 2 if the deadlock persists:
+
+  Option 1 — Disable credential persistence for checkout (avoids Keychain writes):
+
+    - uses: actions/checkout@v6
+      with:
+        persist-credentials: false
+
+  This prevents checkout from calling `git credential-osxkeychain store` entirely,
+  eliminating the deadlock. Note: if your workflow's later steps need to push changes
+  to the repo using git directly (not via GH_TOKEN env var), you must pass the token
+  explicitly in the remote URL or use a separate authentication step.
+
+  Option 2 — Clean workspace before checkout (forces clean lock state):
+
+    - name: Clean workspace before checkout
+      run: |
+        find "$GITHUB_WORKSPACE" -mindepth 1 -maxdepth 1 -exec rm -rf {} + \
+          || echo "::warning::Workspace cleanup had warnings (non-fatal)"
+    - uses: actions/checkout@v6
+
+  This removes any pre-existing files that might be holding Git process locks
+  from a previous job, allowing checkout to complete cleanly. This is an uglier
+  workaround but more effective when persist-credentials: false alone does not help.
+
+  Option 3 — Disable the macOS credential helper globally for CI git operations:
+
+    - name: Disable osxkeychain credential helper for CI
+      run: git config --global credential.helper ''
+    - uses: actions/checkout@v6
+
+  For git push steps that use an explicit token URL, also set GIT_TERMINAL_PROMPT=0:
+
+    - name: Push changes
+      env:
+        GIT_TERMINAL_PROMPT: '0'
+      run: |
+        git -c credential.helper='' push --force \
+          "https://x-access-token:${GITHUB_TOKEN}@github.com/${{ github.repository }}.git" \
+          HEAD:gh-pages
+fix_code:
+  - language: yaml
+    label: 'Fix 1 — persist-credentials: false prevents Keychain write (preferred)'
+    code: |
+      steps:
+        - uses: actions/checkout@v6
+          with:
+            persist-credentials: false  # Avoids git-credential-osxkeychain store call
+
+  - language: yaml
+    label: 'Fix 2 — clean workspace before checkout to resolve concurrent lock conflicts'
+    code: |
+      steps:
+        - name: Clean workspace before checkout
+          run: |
+            find "$GITHUB_WORKSPACE" -mindepth 1 -maxdepth 1 -exec rm -rf {} + \
+              || echo "::warning::Cleanup warnings are non-fatal"
+
+        - uses: actions/checkout@v6
+
+  - language: yaml
+    label: 'Fix 3 — disable osxkeychain globally and use explicit token for git push'
+    code: |
+      steps:
+        - name: Disable macOS keychain credential helper for CI
+          run: git config --global credential.helper ''
+
+        - uses: actions/checkout@v6
+
+        # Later, for git push steps:
+        - name: Push to gh-pages
+          env:
+            GIT_TERMINAL_PROMPT: '0'
+          run: |
+            git -c credential.helper='' push --force \
+              "https://x-access-token:${GITHUB_TOKEN}@github.com/${{ github.repository }}.git" \
+              HEAD:gh-pages
+
+prevention:
+  - 'Always set persist-credentials: false on actions/checkout@v6 for macOS self-hosted runners if your jobs do not need subsequent git operations using the GITHUB_TOKEN credential helper.'
+  - 'Add a timeout-minutes: on checkout steps on macOS self-hosted runners to bound hang duration (e.g., timeout-minutes: 5) rather than waiting for the 6-hour job timeout.'
+  - 'Serialize concurrent jobs on the same macOS runner using a concurrency group, or ensure jobs that checkout concurrently run on different runner instances.'
+  - 'Set GIT_TERMINAL_PROMPT=0 in macOS self-hosted runner environments to prevent git from waiting for interactive input from any credential helper.'
+docs:
+  - url: 'https://github.com/actions/checkout/issues/550'
+    label: 'actions/checkout#550 — Actions checkout gets stuck forever randomly (open, 2021–2026)'
+  - url: 'https://stackoverflow.com/questions/79881327/github-actions-self-hosted-runner-on-macos-tries-to-checkout-repository-forever'
+    label: 'SO q/79881327 — Github Actions self hosted runner on macOS tries to checkout repository forever (Feb 2026)'
+  - url: 'https://github.com/actions/checkout#usage'
+    label: 'actions/checkout README — persist-credentials input documentation'

package/errors/triggers/triggers-071.yml

@@ -0,0 +1,117 @@
+id: triggers-071
+title: 'on: branches: Filter with Only Negation Patterns Silently Never Triggers'
+category: triggers
+severity: silent-failure
+tags:
+  - branches-filter
+  - push
+  - pull_request
+  - negation
+  - glob
+  - workflow-not-triggering
+patterns:
+  - regex: 'branches:\s*\n(\s+-\s+[''"]?!)'
+    flags: 'm'
+  - regex: 'branches:\s*\[\s*[''"]?!'
+    flags: 'i'
+error_messages:
+  - "# No error message — workflow simply never appears in the Actions run queue"
+root_cause: |
+  GitHub Actions branch filters evaluate patterns sequentially against the ref name. The
+  documented rule is: "the workflow only runs if at least one pattern matches the ref name."
+
+  When a branches: (or branches-ignore's inverse: branches:) filter list contains ONLY
+  negation patterns (entries starting with !), no positive match is ever established.
+  Negation patterns can only EXCLUDE from an existing positive match set — they cannot
+  create a match on their own. The evaluation starts with zero matches, negations find
+  nothing to remove, and the result is always "no match" → workflow never fires.
+
+  This is a silent failure: no error is raised, no annotation appears, and the workflow
+  simply never shows up in the Actions tab when the target branch is pushed to. It is
+  especially confusing because the workflow file is syntactically valid and GitHub accepts it.
+
+  Common mistake patterns:
+    branches:
+      - '!main'            # ← Only a negation — zero positive matches → never triggers
+
+    branches:
+      - '!master'          # ← Same problem — always zero triggers
+      - '!release/**'
+
+  The branches-ignore filter does NOT have this problem because it operates on the
+  complement: it matches everything EXCEPT the listed patterns. Use branches-ignore when
+  you want to exclude specific branches.
+
+  Source: SO q/57699839 (144 votes) "GitHub Actions: how to target all branches EXCEPT
+  master?" — accepted answer (242 votes) documents the required positive+negative combo.
+fix: |
+  To target all branches EXCEPT specific ones, choose one of two approaches:
+
+  Option 1 — Add wildcard positive patterns before the negation (order matters):
+
+    on:
+      push:
+        branches:
+          - '*'         # matches every branch without a '/' (e.g. main, develop)
+          - '*/*'       # matches single-slash branches (e.g. feature/x)
+          - '**'        # matches all remaining branches
+          - '!main'     # now excludes main from the positive matches above
+
+  Option 2 — Use branches-ignore instead (simpler and cleaner):
+
+    on:
+      push:
+        branches-ignore:
+          - main
+          - 'release/**'
+
+  Do NOT combine branches: and branches-ignore: on the same event — GitHub rejects that
+  combination with a YAML validation error.
+fix_code:
+  - language: yaml
+    label: 'Broken — only negation in branches: filter, workflow never runs'
+    code: |
+      # This workflow NEVER triggers for any branch push — negation-only matches nothing:
+      on:
+        push:
+          branches:
+            - '!main'        # WRONG: no positive pattern to negate from
+
+  - language: yaml
+    label: 'Fixed — positive wildcard patterns before negation'
+    code: |
+      # Correct approach: include positive patterns first, then exclude specific branches:
+      on:
+        push:
+          branches:
+            - '*'            # matches branches without '/' in name
+            - '*/*'          # matches single-level slash branches
+            - '**'           # matches all remaining branches
+            - '!main'        # now excludes main from the above positive matches
+
+  - language: yaml
+    label: 'Alternative fix — use branches-ignore (simplest for exclusion only)'
+    code: |
+      # Use branches-ignore when you want to exclude specific branches entirely:
+      on:
+        push:
+          branches-ignore:
+            - main
+            - 'release/**'
+            - 'hotfix/**'
+        pull_request:
+          branches-ignore:
+            - main
+
+prevention:
+  - 'When you want to exclude branches, prefer branches-ignore: over branches: with negation — it is simpler and has no positive-pattern requirement.'
+  - 'If you must use branches: with negation, always include at least one positive glob (like ** or *) before the negation patterns.'
+  - 'Remember that pattern order matters: a positive match AFTER a negative pattern re-includes the ref; a negative match AFTER a positive match excludes it.'
+  - 'Use actionlint or act --list to verify your workflow would trigger before relying on pushes to test it.'
+docs:
+  - url: 'https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#onpushbranchestagsbranches-ignoretags-ignore'
+    label: 'GitHub Docs — on.push.branches filter syntax and negation patterns'
+  - url: 'https://stackoverflow.com/questions/57699839/github-actions-how-to-target-all-branches-except-master'
+    label: 'SO q/57699839 (144 votes) — GitHub Actions: how to target all branches EXCEPT master?'
+  - url: 'https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#filter-pattern-cheat-sheet'
+    label: 'GitHub Docs — Filter pattern cheat sheet (glob syntax reference)'

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

@@ -0,0 +1,130 @@
+id: yaml-syntax-074
+title: 'Workflow YAML File in Nested Subdirectory of .github/workflows/ Is Silently Ignored'
+category: yaml-syntax
+severity: silent-failure
+tags:
+  - workflow-placement
+  - subdirectory
+  - nested-folder
+  - file-location
+  - workflow-not-appearing
+  - silent-failure
+patterns:
+  - regex: '\.github/workflows/[^/\s]+/[^/\s]+\.ya?ml'
+    flags: 'i'
+error_messages:
+  - "# No error — workflow YAML in .github/workflows/subdir/name.yml is silently ignored"
+  - "# Workflow never appears in Actions tab; no annotation is created"
+root_cause: |
+  GitHub Actions only scans for workflow files in the DIRECT children of
+  `.github/workflows/` — it does NOT recurse into subdirectories. Files placed in
+  nested paths such as:
+
+    .github/workflows/ci/build.yml
+    .github/workflows/scripts/deploy.yaml
+    .github/workflows/reusable/my-caller.yml
+
+  are completely invisible to GitHub Actions. The runner does not parse them, does not
+  validate them, and emits no error or warning of any kind. The workflow simply never
+  appears in the repository's Actions tab, regardless of how correct the YAML content is.
+
+  This is a documented but easy-to-overlook constraint in the GitHub Actions architecture.
+  The scanner uses a shallow file glob equivalent to `.github/workflows/*.yml` and
+  `.github/workflows/*.yaml` — NOT `.github/workflows/**/*.yml`.
+
+  Common causes:
+  1. Developers organize workflows into subdirectories for clarity (e.g., `ci/`, `deploy/`),
+     not realizing GitHub won't pick them up.
+  2. Copy-pasting a workflow into a folder that already holds related shell scripts or
+     configuration files, creating an unintended nested path.
+  3. Renaming or restructuring the .github directory and accidentally moving workflow files
+     one level too deep.
+  4. Reusable workflow files placed in a `reusable/` or `shared/` subdirectory under
+     workflows/ — these also won't be discovered by GitHub as callable workflows.
+
+  Note: This affects ALL workflow types — regular workflows, reusable workflows
+  (workflow_call), scheduled workflows, and manually dispatched workflows alike.
+
+  Source: SO q/61989951 answer (score 9, from the 158-vote "GitHub Action workflow not
+  running" thread) and GitHub Actions documentation.
+fix: |
+  Move all workflow YAML files directly into `.github/workflows/` (one level deep).
+  Do not create subdirectories inside `.github/workflows/` for workflow YAML files.
+
+  If you want to organize workflows logically, use naming prefixes instead of folders:
+
+    .github/workflows/ci-build.yml
+    .github/workflows/ci-test.yml
+    .github/workflows/deploy-staging.yml
+    .github/workflows/deploy-production.yml
+
+  For scripts, configs, and helper files that are referenced by workflows, place them
+  in a separate directory OUTSIDE `.github/workflows/`, for example:
+    .github/scripts/
+    .github/actions/my-local-action/
+
+  Note: Local composite actions (in `.github/actions/`) CAN be in subdirectories — the
+  subdirectory restriction only applies to workflow YAML files inside `.github/workflows/`.
+fix_code:
+  - language: yaml
+    label: 'Broken — workflow file in nested subdirectory (silently ignored)'
+    code: |
+      # .github/workflows/ci/build.yml  ← WRONG LOCATION, never discovered
+      name: Build CI
+
+      on:
+        push:
+          branches: ['**']
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm ci && npm run build
+
+  - language: yaml
+    label: 'Fixed — workflow file at root of .github/workflows/'
+    code: |
+      # .github/workflows/ci-build.yml  ← CORRECT LOCATION, discovered by GitHub
+      name: Build CI
+
+      on:
+        push:
+          branches: ['**']
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm ci && npm run build
+
+  - language: yaml
+    label: 'Organization pattern — use prefixes instead of subdirectories'
+    code: |
+      # Use name prefixes to group related workflows at the root level:
+      # .github/workflows/ci-build.yml
+      # .github/workflows/ci-lint.yml
+      # .github/workflows/ci-test.yml
+      # .github/workflows/deploy-staging.yml
+      # .github/workflows/deploy-production.yml
+      # .github/workflows/release-tag.yml
+      #
+      # Helper scripts/configs can be in subdirectories outside workflows/:
+      # .github/scripts/deploy.sh
+      # .github/actions/my-composite-action/action.yml  ← composite actions CAN be nested
+
+prevention:
+  - 'Keep all workflow YAML files (.yml / .yaml) directly in .github/workflows/ — never in subdirectories of that folder.'
+  - 'For workflow organization, use descriptive filename prefixes (ci-, deploy-, release-) instead of subdirectories.'
+  - 'Place helper shell scripts in .github/scripts/ and composite actions in .github/actions/<name>/ — subdirectories are fine there but not for workflow files.'
+  - 'After creating a new workflow file, immediately check that it appears in the repository Actions tab before relying on it for CI.'
+  - 'Use actionlint or the GitHub Actions VS Code extension to validate placement — both tools warn about unrecognized workflow file locations.'
+docs:
+  - url: 'https://docs.github.com/en/actions/using-workflows/about-workflows#workflow-basics'
+    label: 'GitHub Docs — About workflows: file placement requirements'
+  - url: 'https://stackoverflow.com/questions/61989951/github-action-workflow-not-running'
+    label: 'SO q/61989951 (158 votes) — GitHub Action workflow not running (answer: nested subfolder not recognized)'
+  - url: 'https://docs.github.com/en/actions/creating-actions/creating-a-composite-action'
+    label: 'GitHub Docs — Composite actions (can be in .github/actions/ subdirectories)'

package/package.json

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