@htekdev/actions-debugger 1.0.114 → 1.0.116

package/errors/runner-environment/macos-26-openssl3-legacy-cipher-p12-import-failure.yml

@@ -0,0 +1,102 @@
+id: runner-environment-200
+title: 'macOS 26 OpenSSL 3.x rejects legacy RC2 ciphers — p12 certificate import fails with inner_evp_generic_fetch unsupported'
+category: runner-environment
+severity: error
+tags:
+  - macos
+  - macos-26
+  - openssl
+  - code-signing
+  - certificate
+  - ios
+  - legacy-cipher
+patterns:
+  - regex: 'inner_evp_generic_fetch:unsupported'
+    flags: 'i'
+  - regex: 'Algorithm \(RC2-\d+-CBC.*\)'
+    flags: 'i'
+  - regex: 'Could not find certificate from.*stdin|Could not parse.*certificate'
+    flags: 'i'
+  - regex: 'openssl.*failed with return code:\s*1'
+    flags: 'i'
+error_messages:
+  - '40CBBC50F87F0000:error:0308010C:digital envelope routines:inner_evp_generic_fetch:unsupported:crypto/evp/evp_fetch.c:355:Global default library context, Algorithm (RC2-40-CBC : 0), Properties ()'
+  - 'Could not find certificate from <stdin>'
+  - '##[error]Error: /usr/local/bin/openssl failed with return code: 1'
+  - '##[warning]Error parsing certificate. This might be caused by an unsupported algorithm. If you''re using old certificate with a new OpenSSL version try to set -legacy flag in opensslPkcsArgs input.'
+root_cause: |
+  macOS 26 runner images ship OpenSSL 3.x (OpenSSL 3.6.x as of runner-images macOS 26
+  release notes). OpenSSL 3.x removed RC2-40-CBC, RC2-64-CBC, and RC2-128-CBC from
+  the default provider. These legacy ciphers were commonly used to encrypt PKCS#12
+  certificate bundles generated by macOS Keychain Access, Fastlane cert, older CI
+  pipelines, or Keychain import/export tools shipped before 2020.
+
+  When a workflow installs a p12 certificate using openssl pkcs12 (directly or via
+  apple-actions/import-codesign-certs@v1/v2), OpenSSL 3.x cannot decrypt the legacy
+  bundle and emits:
+
+    error:0308010C:digital envelope routines:inner_evp_generic_fetch:unsupported:
+    ...Algorithm (RC2-40-CBC : 0), Properties ()
+
+  followed by "Could not find certificate from <stdin>" and openssl exit code 1.
+
+  The code-signing step silently skips certificate import, causing downstream
+  codesign, xcodebuild archive, or notarytool steps to fail with "no identity found"
+  or "identity not in keychain" errors.
+
+  Workflows that ran successfully on macos-14 (OpenSSL 1.1.x) or macos-15
+  (OpenSSL 3.3.x with legacy provider enabled) may start failing when the job
+  label is macos-26 or when macos-latest migrates to macOS 26.
+fix: |
+  Option 1 (quickest) — Pass opensslPkcsArgs: -legacy to apple-actions/import-codesign-certs:
+    The -legacy flag activates OpenSSL's legacy provider which re-enables RC2 and
+    other deprecated algorithms. Supported in apple-actions/import-codesign-certs v2+.
+
+  Option 2 (permanent) — Re-encode the p12 with a modern cipher on your local machine
+  before uploading to GitHub Secrets:
+    openssl pkcs12 -in legacy.p12 -out certs.pem -nodes -passin pass:OLDPASSWORD
+    openssl pkcs12 -export -in certs.pem -out modern.p12 -passout pass:NEWPASSWORD \
+      -keypbe aes-256-cbc -certpbe aes-256-cbc -macalg sha256
+    base64 -w 0 modern.p12 > modern_b64.txt
+    # Upload content of modern_b64.txt as the new GitHub secret value
+
+  Option 3 — Regenerate certificates with modern tooling:
+    Use Fastlane match (>= 3.x) or Xcode 26 certificate export; both default to
+    AES-256-CBC which OpenSSL 3.x supports without -legacy.
+fix_code:
+  - language: yaml
+    label: 'Fix: pass opensslPkcsArgs: -legacy (apple-actions/import-codesign-certs)'
+    code: |
+      - uses: apple-actions/import-codesign-certs@v3
+        with:
+          p12-file-base64: ${{ secrets.IOS_DISTRIBUTION_P12 }}
+          p12-password: ${{ secrets.IOS_DISTRIBUTION_P12_PASSWORD }}
+          opensslPkcsArgs: -legacy   # required on macOS 26 / OpenSSL 3.x for RC2-encrypted p12
+  - language: yaml
+    label: 'Long-term fix: re-encode p12 with AES-256-CBC before updating the secret'
+    code: |
+      # Run these commands locally (not in CI) to produce a modern p12:
+      #
+      # openssl pkcs12 -in legacy.p12 -out certs.pem -nodes -passin pass:$OLD_PASS \
+      #   -legacy                          # may need -legacy on your local OpenSSL 3.x too
+      # openssl pkcs12 -export \
+      #   -in certs.pem -out modern.p12 \
+      #   -passout pass:$NEW_PASS \
+      #   -keypbe aes-256-cbc \
+      #   -certpbe aes-256-cbc \
+      #   -macalg sha256
+      # base64 -w 0 modern.p12 | pbcopy   # paste into GitHub Secrets
+      #
+      # After updating the secret, remove the opensslPkcsArgs: -legacy workaround.
+prevention:
+  - 'Re-encode all p12 certificate bundles with AES-256-CBC before migrating to macos-26'
+  - 'Audit p12 cipher with: openssl pkcs12 -in cert.p12 -info -noout -passin pass:X 2>&1 | grep -i cipher'
+  - 'Pin macos-15 temporarily as a fallback while re-encoding certificates'
+  - 'Test certificate import on macos-26 runners before macos-latest label migration completes'
+docs:
+  - url: 'https://github.com/actions/runner-images/issues/10934'
+    label: 'GitHub runner-images #10934: Intermittent SSL issue loading iOS certificates on macOS 26'
+  - url: 'https://www.openssl.org/docs/man3.0/man7/OSSL_PROVIDER-legacy.html'
+    label: 'OpenSSL 3.x legacy provider documentation'
+  - url: 'https://github.com/apple-actions/import-codesign-certs'
+    label: 'apple-actions/import-codesign-certs: opensslPkcsArgs input'

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

@@ -0,0 +1,93 @@
+id: runner-environment-199
+title: 'Windows self-hosted runner V2 broker listener stops polling after first job (2.334.0)'
+category: runner-environment
+severity: error
+tags:
+  - self-hosted
+  - windows
+  - runner-v2
+  - broker
+  - listener
+  - stuck
+  - message-queue
+  - v2-flow
+patterns:
+  - regex: 'Get messages has been cancelled using local token source\. Continue to get messages with new status'
+    flags: 'i'
+  - regex: 'BrokerMessageListener.*cancel|cancel.*BrokerMessageListener'
+    flags: 'i'
+error_messages:
+  - 'Get messages has been cancelled using local token source. Continue to get messages with new status.'
+root_cause: |
+  On Windows self-hosted runners running v2.334.0 with the V2 broker flow enabled
+  (`useV2Flow: true`, connecting to `broker.actions.githubusercontent.com`), the
+  `BrokerMessageListener` stops issuing GET /message requests after the first job
+  completes and the runner transitions from Busy→Online (idle).
+
+  The root cause is a race condition in the V2 state machine reset path: when the
+  Busy→Online transition fires, the existing `localTokenSource` for the polling loop
+  is cancelled (logging "Get messages has been cancelled using local token source.
+  Continue to get messages with new status."), but the replacement polling loop fails
+  to start due to a missing null-check or async continuation bug on Windows. OAuth
+  token refreshes continue normally (masking the hang — credentials are not the issue),
+  but no new GET /message requests are dispatched.
+
+  The runner UI shows the runner as "Idle" indefinitely. Any jobs queued after the
+  first run sit in "Queued" status and never start until the runner service is manually
+  restarted. The issue is specific to Windows (the identical code path on Linux/macOS
+  appears unaffected) and requires a service start + exactly one job completion to
+  trigger. Reproduced reliably across multiple self-hosted Windows environments.
+
+  Reported against runner v2.334.0, commit f1995ede5d885c997d13d8eca5467c4ce97fe69c.
+  No fix available as of June 2026. Open at actions/runner#4444.
+fix: |
+  Immediate workaround: restart the runner service after each job, or add an automated
+  watchdog that monitors the runner diagnostics log for the stale-listener pattern and
+  triggers a service restart.
+
+  Longer-term: downgrade to runner v2.333.x until actions/runner#4444 is resolved.
+  Check the runner release notes for a fix targeting the V2 BrokerMessageListener
+  state-reset path.
+fix_code:
+  - language: yaml
+    label: 'PowerShell watchdog snippet to restart runner service on listener hang (add to a monitoring script)'
+    code: |
+      # Watchdog: detect stale BrokerMessageListener and restart runner service
+      # Run this as a scheduled task every 5 minutes on the runner host
+
+      $diagDir = "C:\actions-runner\_diag"
+      $logFile = Get-ChildItem $diagDir -Filter "Runner_*.log" | Sort-Object LastWriteTime -Descending | Select-Object -First 1
+      $lastMsg = (Get-Content $logFile.FullName -Tail 200 | Select-String "BrokerMessageListener") | Select-Object -Last 1
+
+      # If the last BrokerMessageListener log entry is the cancellation message
+      # and it's more than 10 minutes old, restart the service
+      if ($lastMsg -match "cancelled using local token source") {
+        $entryTime = [datetime]::Parse(($lastMsg -split " ")[0])
+        if ((Get-Date) - $entryTime -gt [TimeSpan]::FromMinutes(10)) {
+          Restart-Service actions.runner.*
+        }
+      }
+  - language: yaml
+    label: 'Pin runner version to 2.333.x in ARC or self-hosted runner config'
+    code: |
+      # For ARC (Actions Runner Controller) — pin runner version in values.yaml
+      githubConfigSecret: pre-defined-secret
+      template:
+        spec:
+          containers:
+            - name: runner
+              env:
+                - name: RUNNER_VERSION
+                  value: "2.333.0"    # Pin below 2.334.0 until #4444 is fixed
+prevention:
+  - "Subscribe to the actions/runner release feed to catch regression fixes; downgrade immediately when a V2-flow listener regression is reported."
+  - "For Windows runner pools, add a service watchdog (Task Scheduler or Prometheus alert) that detects listener staleness via the _diag/Runner_*.log pattern."
+  - "Consider switching to ephemeral JIT runners on Windows — ephemeral runners cannot hit this bug because each runner handles exactly one job then exits."
+  - "Monitor runner queue depth in your autoscaler; an idle runner with > 0 queued jobs is a reliable signal the listener has stalled."
+docs:
+  - url: 'https://github.com/actions/runner/issues/4444'
+    label: 'actions/runner#4444 — Listener stops polling broker after first job (2.334.0, Windows, V2 flow)'
+  - url: 'https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners'
+    label: 'About self-hosted runners'
+  - url: 'https://github.com/actions/runner/releases'
+    label: 'Actions Runner release notes'

package/errors/runner-environment/runner-v2334-action-download-repeated-case-sensitivity.yml

@@ -0,0 +1,100 @@
+id: runner-environment-202
+title: 'Runner v2.334.0 "Download action repository" repeats for same action when references use different letter casing'
+category: runner-environment
+severity: warning
+tags:
+  - runner
+  - action-resolution
+  - performance
+  - v2.334
+  - composite-actions
+  - case-sensitivity
+patterns:
+  - regex: 'Download action repository.*already been downloaded'
+    flags: 'i'
+  - regex: 'Download action repository.*\d+\.\d+s.*Download action repository'
+    flags: 'i'
+  - regex: 'Resolving action.*batching.*dedup.*failed|action.*resolution.*duplicate.*case'
+    flags: 'i'
+error_messages:
+  - 'Download action repository ''actions/checkout@v4'' (SHA:abc123...) 18.35s'
+  - 'Download action repository ''Actions/Checkout@v4'' (SHA:abc123...) 19.12s'
+  - 'Download action repository ''ACTIONS/CHECKOUT@v4'' (SHA:abc123...) 17.88s'
+root_cause: |
+  Runner v2.334.0 introduced "batch and deduplicate action resolution across composite
+  depths" to speed up jobs with many actions. The deduplication logic uses a
+  case-sensitive equality check on the action reference string (owner/repo@ref). When
+  the same action is referenced with different capitalizations — for example,
+  actions/checkout@v4 in one workflow step and Actions/Checkout@v4 inside a composite
+  action — the deduplication logic treats them as distinct actions and downloads both.
+
+  This regression is tracked in actions/runner#3731. Each duplicate download takes
+  15-20 seconds, which multiplies across all case-variant references in a job. In
+  workflows with many composite actions or large action dependency trees, this can add
+  several minutes of silent overhead.
+
+  The issue does not cause a build failure — the downloads resolve to the same SHA
+  and the action runs once. The cost is purely in duplicate network traffic, API
+  calls, and elapsed time. Repeated downloads also count against GitHub API rate
+  limits for private runners or GHES installations.
+
+  Most commonly observed when:
+  - Composite actions use uppercase or title-case owners in their uses: fields
+  - Third-party actions internally call actions/core or actions/toolcache with
+    inconsistent casing
+  - Workflows mix community-contributed composite actions with differing conventions
+fix: |
+  Canonicalize all action references to lowercase owner/repo throughout your
+  workflow files and composite action.yml files. GitHub API lookups are
+  case-insensitive, so actions/checkout and Actions/Checkout resolve identically,
+  but the v2.334.0 deduplication cache is case-sensitive.
+
+  After fixing, run the job again to confirm "Download action repository" appears
+  only once per unique action in the logs.
+
+  A fix for the runner-side deduplication (case-insensitive cache key) is tracked
+  in actions/runner#3731 and may be included in a future runner release.
+fix_code:
+  - language: yaml
+    label: 'Bug: mixed-case action references cause repeated downloads'
+    code: |
+      # workflow.yml — uses lowercase
+      steps:
+        - uses: actions/checkout@v4
+
+      # internal/composite/action.yml — uses title-case (different casing)
+      runs:
+        using: composite
+        steps:
+          - uses: Actions/Checkout@v4   # triggers a second download in v2.334.0
+  - language: yaml
+    label: 'Fix: canonicalize to lowercase owner/repo in all workflow and composite action files'
+    code: |
+      # workflow.yml
+      steps:
+        - uses: actions/checkout@v4   # lowercase
+
+      # internal/composite/action.yml
+      runs:
+        using: composite
+        steps:
+          - uses: actions/checkout@v4   # lowercase matches — deduplicated correctly
+  - language: yaml
+    label: 'Diagnostic: detect duplicate downloads by searching job logs'
+    code: |
+      # In the Actions UI, open the job log and search for "Download action repository"
+      # If the same action appears more than once (even with different casing), you
+      # have duplicate downloads.
+      #
+      # CLI equivalent (with gh):
+      # gh run view <run-id> --log | grep "Download action repository" | sort | uniq -c
+prevention:
+  - 'Use consistent lowercase owner/repo for all action references across workflow files and composite actions'
+  - 'Add an actionlint check to CI; it flags inconsistent action reference casing'
+  - 'Audit composite action.yml files for uppercase uses: references, as they are the most common source'
+  - 'Pin runner version to v2.333.0 as a temporary workaround while waiting for runner#3731 fix'
+docs:
+  - url: 'https://github.com/actions/runner/issues/3731'
+    label: 'GitHub runner#3731: Download action repository called repeatedly for same action (case-sensitivity)'
+  - url: 'https://github.com/actions/runner/releases/tag/v2.334.0'
+    label: 'Runner v2.334.0 release notes: batch and deduplicate action resolution'

package/errors/runner-environment/setup-python-macos-self-hosted-symlink-permission-denied.yml

@@ -0,0 +1,94 @@
+id: runner-environment-198
+title: 'setup-python fails on macOS self-hosted runner with "ln: python3XX: Permission denied" — symlink created without sudo after sudo install'
+category: runner-environment
+severity: error
+tags:
+  - setup-python
+  - self-hosted
+  - macos
+  - symlink
+  - permissions
+  - sudo
+patterns:
+  - regex: 'ln:.*python3\d+.*Permission denied'
+    flags: 'i'
+  - regex: 'Error:.*ln:.*python.*Permission denied'
+    flags: 'i'
+error_messages:
+  - 'Error: ln: python314: Permission denied'
+  - 'Error: ln: python312: Permission denied'
+  - 'Error: ln: python313: Permission denied'
+root_cause: |
+  The setup-python macOS installer script (setup.sh) uses sudo to install the Python
+  framework into /Library/Frameworks/ — a root-owned directory. However, the
+  subsequent step that creates symlinks inside that directory (e.g., linking
+  python3.14 → python3) runs WITHOUT sudo, causing a permission error when the
+  runner''s CI user is a standard (non-root) account even if sudo is available for
+  the install step.
+
+  The error appears as:
+    Error: ln: python314: Permission denied
+
+  This affects macOS self-hosted runners (EC2, bare-metal, VM) where the runner
+  service is configured as a non-admin user. GitHub-hosted macOS runners are
+  unaffected because they grant passwordless sudo to the runner user.
+
+  A fix was proposed in actions/python-versions PR #384 to use sudo for the symlink
+  creation step as well, but is not yet merged/released as of mid-2026.
+fix: |
+  Short-term workaround: Grant the runner service user passwordless sudo on the
+  macOS runner machine, or run the runner as a user with write access to
+  /Library/Frameworks/ and /usr/local/bin.
+
+  Safer workaround: Pre-install Python on the macOS runner machine using the
+  official Python.org pkg installer (which creates symlinks correctly as root), then
+  rely on setup-python''s PATH-detection to use the pre-installed version without
+  invoking the installer.
+
+  Enterprise workaround: Use a custom RUNNER_TOOL_CACHE path that is owned by the
+  runner user and set python-version to a version already cached there, bypassing
+  the framework installer entirely.
+fix_code:
+  - language: yaml
+    label: 'Workaround: use pre-installed Python to avoid the installer'
+    code: |
+      jobs:
+        build:
+          runs-on: [self-hosted, macos]
+          steps:
+            # If Python 3.14 is pre-installed system-wide (via pkg installer as root),
+            # setup-python finds it in PATH without invoking setup.sh
+            - uses: actions/setup-python@v5
+              with:
+                python-version: '3.14'
+            - run: python3 --version
+  - language: yaml
+    label: 'Workaround: grant passwordless sudo to runner user via /etc/sudoers (NOT recommended for production)'
+    code: |
+      # Add to /etc/sudoers on the macOS runner machine (use visudo):
+      # runner-user ALL=(ALL) NOPASSWD: ALL
+      #
+      # This allows setup-python's installer to use sudo for both the framework
+      # install and symlink creation steps.
+      #
+      # In your workflow, no changes are needed — setup-python works normally once
+      # the runner user has the required sudo permissions.
+      jobs:
+        build:
+          runs-on: [self-hosted, macos]
+          steps:
+            - uses: actions/setup-python@v5
+              with:
+                python-version: '3.14'
+prevention:
+  - 'Use pre-installed Python on macOS self-hosted runners to avoid the setup.sh installer and its sudo/symlink requirements'
+  - 'When provisioning macOS self-hosted runners, ensure the runner user has passwordless sudo or pre-install all required Python versions'
+  - 'Track actions/python-versions#384 for an upstream fix that adds sudo to the symlink creation step'
+  - 'Test setup-python on macOS self-hosted runners in a staging environment before deploying to production'
+docs:
+  - url: 'https://github.com/actions/setup-python/issues/1301'
+    label: 'actions/setup-python#1301: Permission denied when creating symlinks on macOS self-hosted runners (2026)'
+  - url: 'https://github.com/actions/python-versions/pull/384'
+    label: 'actions/python-versions PR #384: fix symlink creation to use sudo (pending)'
+  - url: 'https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners#self-hosted-runner-security'
+    label: 'GitHub Docs: Self-hosted runner security'

package/errors/runner-environment/setup-python-windows-self-hosted-no-admin-install-fails.yml

@@ -0,0 +1,101 @@
+id: runner-environment-197
+title: 'setup-python fails on Windows self-hosted runner without administrator permissions — InstallAllUsers=1 MSI installer requires admin'
+category: runner-environment
+severity: error
+tags:
+  - setup-python
+  - self-hosted
+  - windows
+  - admin-permissions
+  - msi-installer
+patterns:
+  - regex: 'Error happened during Python installation'
+    flags: 'i'
+  - regex: 'InstallAllUsers=1'
+    flags: 'i'
+  - regex: 'setup-python.*self.hosted.*windows.*fail'
+    flags: 'i'
+error_messages:
+  - 'Error happened during Python installation'
+root_cause: |
+  The setup-python action installs Python using the official MSI installer with the
+  flag InstallAllUsers=1. This flag installs Python into the shared runner tool cache
+  (RUNNER_TOOL_CACHE) using the DefaultAllUsersTargetDir argument, which requires
+  administrator privileges to write to the shared system-level installation path.
+
+  When the GitHub Actions runner service is running under a standard user account
+  without local administrator permissions, the Python MSI installer fails because it
+  cannot write to the required system paths, resulting in:
+
+    Error happened during Python installation
+
+  This affects Windows self-hosted runners configured as a Windows service under a
+  non-admin account. GitHub-hosted Windows runners are unaffected because they run
+  as SYSTEM (full admin). Linux and macOS self-hosted runners are unaffected.
+
+  Note: this is by design per the action maintainers — InstallAllUsers=1 is required
+  to correctly populate the shared RUNNER_TOOL_CACHE. A per-user install mode
+  (InstallAllUsers=0) is under consideration as a future enhancement.
+fix: |
+  Primary fix: Configure the Windows runner service to run as a local administrator
+  account. In Windows Services (services.msc), change the "Log On" account for the
+  GitHub Actions Runner service to an account with local admin rights, or install the
+  runner using the .\config.cmd --runasservice flow with an admin account.
+
+  Workaround 1: Pre-install the required Python version system-wide on the runner
+  machine before workflows run. setup-python will use the pre-installed version from
+  PATH without invoking the MSI installer if the version matches.
+
+  Workaround 2: Ensure the runner is run interactively (not as a service) under an
+  account with admin rights during initial Python installation, then cache the tool.
+
+  Workaround 3: Use actions/setup-python''s uses: together with a self-hosted runner
+  image that already has Python pre-installed in RUNNER_TOOL_CACHE, bypassing the
+  MSI install step entirely.
+fix_code:
+  - language: yaml
+    label: 'Workflow: no changes needed — fix is on the runner machine configuration'
+    code: |
+      # Fix requires reconfiguring the Windows runner service account:
+      # 1. Open Services (services.msc) on the runner machine
+      # 2. Find "GitHub Actions Runner (<name>)"
+      # 3. Right-click → Properties → Log On tab
+      # 4. Change to an account with local administrator privileges
+      # 5. Restart the service
+      #
+      # After reconfiguring, setup-python works normally:
+      jobs:
+        build:
+          runs-on: [self-hosted, windows]
+          steps:
+            - uses: actions/setup-python@v5
+              with:
+                python-version: '3.12'
+            - run: python --version
+  - language: yaml
+    label: 'Workaround: use pre-installed Python from PATH if runner has it installed system-wide'
+    code: |
+      jobs:
+        build:
+          runs-on: [self-hosted, windows]
+          steps:
+            # Skip setup-python entirely if Python is pre-installed system-wide
+            - name: Verify Python available
+              run: python --version
+            # OR use setup-python only to add to PATH, not install:
+            - uses: actions/setup-python@v5
+              with:
+                python-version: '3.12'
+                # If Python 3.12 is already in RUNNER_TOOL_CACHE, no install occurs
+prevention:
+  - 'Always run Windows self-hosted runner services under a local administrator account — setup-python requires admin rights to install into the shared tool cache'
+  - 'Test setup-python on self-hosted runners with the same service account before deploying to production workloads'
+  - 'Use pre-installed Python on Windows self-hosted runners to avoid the MSI installer entirely when admin rights cannot be granted'
+  - 'Document the runner service account requirements in your team''s self-hosted runner setup guide'
+docs:
+  - url: 'https://github.com/actions/setup-python/issues/1308'
+    label: 'actions/setup-python#1308: fails on self-hosted runners without admin permissions (2026)'
+  - url: 'https://github.com/actions/setup-python/blob/main/docs/advanced-usage.md#windows'
+    label: 'setup-python docs: Windows advanced usage and self-hosted runner configuration'
+  - url: 'https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/configuring-the-self-hosted-runner-application-as-a-service'
+    label: 'GitHub Docs: Configuring the self-hosted runner as a service'

package/errors/silent-failures/paths-filter-before-field-missing-workflow-run.yml

@@ -0,0 +1,105 @@
+id: silent-failures-107
+title: "dorny/paths-filter Reports All Files Changed When 'before' Field Missing on workflow_run"
+category: silent-failures
+severity: silent-failure
+tags:
+  - paths-filter
+  - workflow_run
+  - before-field
+  - silent-failure
+  - fork-pr
+  - changed-files
+  - wrong-output
+patterns:
+  - regex: '''before'' field is missing in event payload'
+    flags: 'i'
+  - regex: 'changes will be detected from last commit'
+    flags: 'i'
+  - regex: 'paths-filter.*workflow.run'
+    flags: 'i'
+error_messages:
+  - "Warning: 'before' field is missing in event payload - changes will be detected from last commit"
+root_cause: |
+  `dorny/paths-filter` (v3 and earlier) contains an internal code path that requires a
+  `before` SHA field from the GitHub event payload to compute the diff base. When used in
+  a `workflow_run`-triggered workflow, the event payload does not contain a `before` field
+  (it only has `head_sha`, `head_branch`, etc.) — so the action falls into a fallback path
+  that calls `getChangesInLastCommit()` instead of performing a proper merge-base diff.
+
+  The result: **every file in the repository is reported as "changed"**, defeating any
+  attempt to use paths-filter as a change detection gate in `workflow_run` workflows.
+
+  Root cause in source code (paths-filter v3):
+  The action's `getChangedFilesFromGit()` logic normalizes both `base` and `head` to short
+  branch names. On `workflow_run`, `github.context.ref` resolves to the same ref as the
+  user-supplied `base:` (e.g. both become "main"). The `isBaseSameAsHead` check triggers
+  the fallback: if `base === head` AND `beforeSha` is null, the action emits the warning
+  and returns only the last commit's changes — which in a merge-queue or PR workflow is
+  completely wrong.
+
+  The same bug occurs when:
+  - Using paths-filter in a `workflow_run` workflow without explicitly passing `ref:` as a SHA.
+  - Running from a forked PR where the `before` field is absent from the push payload.
+  - Any workflow_run where `github.context.ref` resolves to the same branch name as the
+    `base:` input after short-name normalization.
+fix: |
+  Pass `ref:` explicitly as the HEAD SHA of the triggering workflow run. Using a full SHA
+  prevents the `isBaseSameAsHead` short-circuit because a SHA never equals a branch name
+  after normalization:
+
+    - uses: dorny/paths-filter@v3
+      with:
+        base: 'main'
+        ref: ${{ github.event.workflow_run.head_sha }}
+        filters: |
+          backend:
+            - 'src/**'
+
+  Also ensure the prior `actions/checkout` step uses `fetch-depth: 0` so the action has
+  both `base` and `ref` locally available for `getChangesSinceMergeBase`.
+
+  For fork PRs: use `ref: ${{ github.event.workflow_run.head_sha }}` and
+  `base: ${{ github.event.workflow_run.base_branch }}`.
+
+  Alternative: upgrade to dorny/paths-filter v4.0.1+ which adds native `merge_group`
+  support and has improved ref handling (check release notes for workflow_run fixes).
+fix_code:
+  - language: yaml
+    label: 'Pass ref as SHA to avoid isBaseSameAsHead false-positive on workflow_run'
+    code: |
+      on:
+        workflow_run:
+          workflows: ["CI"]
+          types: [completed]
+
+      jobs:
+        check-changes:
+          runs-on: ubuntu-latest
+          outputs:
+            backend: ${{ steps.filter.outputs.backend }}
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                ref: ${{ github.event.workflow_run.head_sha }}
+                fetch-depth: 0
+
+            - uses: dorny/paths-filter@v3
+              id: filter
+              with:
+                base: ${{ github.event.workflow_run.base_branch }}
+                # REQUIRED: pass ref as SHA, not branch name
+                # Without this, base == head after normalization → all files reported as changed
+                ref: ${{ github.event.workflow_run.head_sha }}
+                filters: |
+                  backend:
+                    - 'src/**'
+prevention:
+  - 'Always pass ref: ${{ github.event.workflow_run.head_sha }} when using paths-filter in workflow_run contexts.'
+  - 'Never rely on implicit ref resolution in workflow_run workflows — the context.ref is the default branch, not the PR head.'
+  - 'After fixing, add a smoke-test PR that changes only an unmonitored path and verify paths-filter returns false for the guarded path.'
+  - 'Consider tj-actions/changed-files as an alternative; check its workflow_run documentation before switching.'
+docs:
+  - url: 'https://github.com/dorny/paths-filter/issues/261'
+    label: "Bug: 'before' field is missing when it should not even be used (11 reactions, open)"
+  - url: 'https://github.com/dorny/paths-filter'
+    label: 'dorny/paths-filter — conditionally run actions based on modified files'