@htekdev/actions-debugger 1.0.114 → 1.0.115

package/errors/concurrency-timing/concurrency-timing-053.yml

@@ -0,0 +1,83 @@
+id: concurrency-timing-053
+title: 'Concurrency pending slot overflow: third concurrent run silently cancels the already-queued second run when cancel-in-progress is false'
+category: concurrency-timing
+severity: silent-failure
+tags:
+  - concurrency
+  - cancel-in-progress
+  - pending
+  - queue
+  - silent-cancellation
+  - overflow
+patterns:
+  - regex: 'Canceling since a higher priority waiting run was found'
+    flags: 'i'
+  - regex: 'This run was automatically cancelled'
+    flags: 'i'
+error_messages:
+  - 'Canceling since a higher priority waiting run was found'
+  - 'This run was automatically cancelled'
+root_cause: |
+  GitHub Actions concurrency groups with cancel-in-progress: false allow at most one
+  run to be in-progress and one run to be pending (queued) simultaneously per group.
+  This queue depth is exactly 1, not unlimited.
+
+  When a third run arrives while run 1 is in-progress and run 2 is pending:
+    - Run 2 (the pending run) is immediately and silently cancelled
+    - Run 3 takes run 2's pending slot
+
+  The user who triggered run 2 typically sees it flip from "Queued" to "Cancelled"
+  with no notification and no failure alert. From their perspective their commit's CI
+  simply disappeared.
+
+  This behavior is documented in GitHub docs but surprises teams that expect a FIFO
+  queue of unlimited depth. The concurrency feature is a mutex with a single
+  waiting-room slot, not a job scheduler queue.
+
+  Common scenarios where this causes silent data loss:
+    - Rapid-fire merges to a protected branch with slow integration tests
+    - Multiple developers pushing within seconds of each other to the same branch
+    - Automated commits (dependency updates, release bots) arriving while CI runs
+fix: |
+  Option 1 — Accept the overflow: intended behavior for fast-merge scenarios where only
+  the LATEST commit needs CI. No change needed.
+
+  Option 2 — Widen the concurrency key so each commit gets its own slot:
+    group: ${{ github.workflow }}-${{ github.sha }}
+  This disables cancellation entirely; every run completes regardless of newer pushes.
+
+  Option 3 — Use cancel-in-progress: true explicitly if "latest wins" is the desired
+  semantics. In-progress runs cancel rather than queued runs disappearing silently.
+
+  Option 4 — Queue at the runner group level by using a self-hosted runner group with
+  a concurrency limit to provide true multi-run queuing.
+fix_code:
+  - language: yaml
+    label: 'Common mistake: expecting cancel-in-progress: false to queue all pending runs indefinitely'
+    code: |
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.ref }}
+        cancel-in-progress: false
+      # Only 1 run can be pending; a 3rd arriving run silently cancels the queued 2nd
+  - language: yaml
+    label: 'Option A: per-commit group key — every run completes, no cancellation at all'
+    code: |
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.sha }}
+        cancel-in-progress: false
+  - language: yaml
+    label: 'Option B: cancel-in-progress: true — explicit latest-wins, in-progress runs cancelled not pending ones'
+    code: |
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.ref }}
+        cancel-in-progress: true
+prevention:
+  - 'Understand that cancel-in-progress: false does not create an unlimited queue — it allows exactly one pending run per concurrency group key'
+  - 'For deployment workflows where no commit should be skipped, use per-commit group keys (${{ github.sha }}) to guarantee every run completes'
+  - 'Monitor the Actions tab during rapid-push periods to verify queued runs are completing, not silently disappearing'
+  - 'Prefer cancel-in-progress: true when only the latest result matters; the cancellation is explicit and visible rather than silent'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-concurrency'
+    label: 'GitHub Docs: Using concurrency'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-concurrency#example-only-cancel-in-progress-jobs-or-runs-for-the-current-workflow'
+    label: 'GitHub Docs: Concurrency — one pending slot per group'

package/errors/known-unsolved/known-unsolved-062.yml

@@ -0,0 +1,87 @@
+id: known-unsolved-062
+title: 'workflow_run chains are limited to one level — a workflow_run-triggered workflow cannot trigger another downstream workflow via workflow_run'
+category: known-unsolved
+severity: limitation
+tags:
+  - workflow-run
+  - chaining
+  - pipeline
+  - limitation
+  - no-fix
+  - event-trigger
+patterns:
+  - regex: 'on:\s*\n\s+workflow_run:'
+    flags: 'i'
+error_messages: []
+root_cause: |
+  GitHub Actions explicitly prevents workflow_run events from chaining more than one
+  level deep. A workflow triggered by workflow_run CANNOT itself use workflow_run as
+  an on: trigger to fire a third downstream workflow.
+
+  From GitHub documentation: "A workflow triggered by a workflow_run event can only
+  be triggered by a workflow that is not itself triggered by a workflow_run event."
+
+  This restriction prevents infinite trigger loops but also prevents building linear
+  CI/CD pipelines using workflow_run chaining alone. Multi-stage pipelines of the form
+  Build (push) → Test (workflow_run) → Deploy (workflow_run) → Notify (workflow_run)
+  fail silently at the second hop: the Deploy and Notify workflows never appear in the
+  Actions tab and no error is raised anywhere.
+
+  There is no runtime error, no annotation, and no warning. The on: workflow_run
+  trigger on the downstream workflow is simply never evaluated.
+fix: |
+  Replace the second-hop workflow_run trigger with an explicit dispatch from the
+  first downstream workflow:
+
+  Option 1 — repository_dispatch: use the GitHub REST API from a job step in workflow
+  B to POST to /repos/{owner}/{repo}/dispatches with a custom event_type. Workflow C
+  listens on on: repository_dispatch with a matching types: filter.
+
+  Option 2 — workflow_dispatch: use gh workflow run from a step in workflow B to
+  directly trigger workflow C by filename. Requires a GitHub token with actions:write.
+
+  Option 3 — Consolidate: merge the second and third workflows into a single workflow
+  with job dependencies (needs:) eliminating the cross-workflow hop entirely.
+fix_code:
+  - language: yaml
+    label: 'Does NOT work: workflow_run cannot chain more than one level deep'
+    code: |
+      # Workflow C — this trigger is never evaluated when Workflow B is
+      # itself triggered by workflow_run
+      on:
+        workflow_run:
+          workflows: ["B - Integration Tests"]
+          types: [completed]
+  - language: yaml
+    label: 'Fix: dispatch workflow C via repository_dispatch from workflow B'
+    code: |
+      # In workflow B (intermediate workflow, triggered by workflow_run):
+      jobs:
+        dispatch-downstream:
+          runs-on: ubuntu-latest
+          if: ${{ github.event.workflow_run.conclusion == 'success' }}
+          steps:
+            - name: Trigger workflow C via repository_dispatch
+              run: |
+                gh api repos/${{ github.repository }}/dispatches \
+                  --method POST \
+                  --field event_type=run-deploy \
+                  --field client_payload='{"run_id":"${{ github.event.workflow_run.id }}"}'
+              env:
+                GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      # In workflow C:
+      on:
+        repository_dispatch:
+          types: [run-deploy]
+prevention:
+  - 'Design CI/CD pipelines assuming workflow_run allows only one hop; use repository_dispatch or workflow_dispatch for any second-level chaining'
+  - 'Prefer consolidating multi-stage pipelines into a single workflow with job dependencies (needs:) when the stages always execute in sequence'
+  - 'When a downstream workflow never appears in the Actions tab after merging, verify whether its on: trigger is workflow_run and whether its upstream workflow is also workflow_run-triggered'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_run'
+    label: 'GitHub Docs: workflow_run event — one-level-deep restriction'
+  - url: 'https://docs.github.com/en/rest/repos/repos#create-a-repository-dispatch-event'
+    label: 'GitHub REST API: Create a repository dispatch event'
+  - url: 'https://cli.github.com/manual/gh_workflow_run'
+    label: 'GitHub CLI: gh workflow run (alternative dispatch method)'

package/errors/known-unsolved/runner-rest-api-busy-false-broker-state-desync.yml

@@ -0,0 +1,102 @@
+id: known-unsolved-063
+title: 'REST API reports runner busy:false while broker shows runner actively executing a job'
+category: known-unsolved
+severity: silent-failure
+tags:
+  - self-hosted
+  - runner
+  - autoscaler
+  - rest-api
+  - broker
+  - state-desync
+  - v2-flow
+  - job-killed
+patterns:
+  - regex: 'busy.*false.*runner.*executing|runner.*busy.*false.*job'
+    flags: 'i'
+  - regex: '"busy"\s*:\s*false'
+    flags: 'i'
+error_messages:
+  - '"busy": false'
+  - 'GET /repos/{owner}/{repo}/actions/runners/{id} → {"busy": false}'
+root_cause: |
+  On non-ephemeral self-hosted runners using the V2 broker flow
+  (`broker.actions.githubusercontent.com`), a state desynchronization exists between
+  the broker service and the GitHub REST API:
+
+  - The broker correctly tracks runner state in real-time: after picking up Job B, the
+    runner reports `JobState: Busy` to the broker and renews its job lease every 60s.
+  - However, `GET /repos/{owner}/{repo}/actions/runners/{runner_id}` (the public REST
+    API) continues to return `"busy": false` during the early phase of job execution.
+    The REST API state may only update after the runner's next periodic sync, which
+    can lag 30–120 seconds behind the broker state.
+
+  Auto-scaling tools that rely on the REST API to identify idle runners (e.g.,
+  `github-aws-runners/terraform-aws-github-runner`, KEDA GitHub Actions scaler,
+  custom Lambda/CloudFunction scalers) interpret `busy: false` as "runner is idle and
+  safe to terminate." This causes the autoscaler to terminate an EC2/GCE/Azure instance
+  mid-job — killing the runner process with no Actions-level error and marking the job
+  as failed with a runner disconnection error.
+
+  From the affected job's perspective, the log ends mid-step with "The runner has
+  received a shutdown signal" or the job times out. There is no annotation indicating
+  the root cause was an autoscaler decision based on stale REST API data.
+
+  No GitHub-side fix is available as of June 2026. The REST API does not expose a
+  real-time busy status consistent with the broker. Open at actions/runner#4422.
+fix: |
+  There is no complete fix — this is a known state inconsistency in the GitHub platform.
+
+  Workarounds (choose one based on your autoscaling setup):
+
+  1. **Switch to ephemeral JIT runners (recommended)**: Use JIT tokens and terminate
+     runners after exactly one job. There is no window for autoscalers to misidentify
+     a running job as idle because the runner is registered and deregistered atomically.
+
+  2. **Add a grace period before termination**: When your autoscaler sees `busy: false`,
+     wait 2–3 minutes and re-poll before actually terminating. This covers the lag
+     between broker state and REST API state.
+
+  3. **Poll job status instead of runner status**: Use
+     `GET /repos/{owner}/{repo}/actions/runs` to check for `in_progress` workflow runs
+     before terminating any runner, rather than relying on per-runner `busy` status.
+
+  4. **Use runner labels + job assignment**: If your autoscaler assigns specific runners
+     to specific jobs via labels, you can cross-reference queued/in-progress job
+     assignments against runner IDs before terminating.
+fix_code:
+  - language: yaml
+    label: 'Example: Switch to ephemeral JIT runners (removes the desync window entirely)'
+    code: |
+      # Use JIT runner registration in your autoscaler
+      # Each runner handles exactly one job — busy/idle desync cannot occur
+      # See: https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions#using-just-in-time-runners
+
+      # In your autoscaler provisioning logic:
+      #   POST /repos/{owner}/{repo}/actions/runners/generate-jit-config
+      #   → Use the returned jit_config to start an ephemeral runner
+      #   → Runner auto-deregisters after job completes — no stale REST state possible
+  - language: yaml
+    label: 'Example: Grace period before termination (Terraform-style pseudocode)'
+    code: |
+      # In your autoscaler Lambda/script, before terminating an instance:
+      # 1. GET /repos/{owner}/{repo}/actions/runners/{runner_id}
+      # 2. If busy == false, wait 2 minutes
+      # 3. Re-poll: GET /repos/{owner}/{repo}/actions/runners/{runner_id}
+      # 4. Only terminate if STILL busy == false after the grace period
+
+      # This covers the broker→REST lag window (~30-120s observed in practice)
+prevention:
+  - "Prefer ephemeral JIT runners for any workload where mid-job termination would be costly; the broker-REST desync window is zero for single-job-per-runner setups."
+  - "Never terminate a runner instance based solely on a single REST API `busy: false` reading — always double-check with a grace period or secondary signal."
+  - "Monitor for jobs that end with 'runner has received a shutdown signal' — this is a reliable indicator that a runner was terminated externally mid-job."
+  - "If using terraform-aws-github-runner or similar, check whether the tool version has built-in grace periods for the busy-state lag."
+docs:
+  - url: 'https://github.com/actions/runner/issues/4422'
+    label: 'actions/runner#4422 — /runners REST API reports busy:false for active runner'
+  - url: 'https://docs.github.com/en/rest/actions/self-hosted-runners'
+    label: 'REST API: Self-hosted runners'
+  - url: 'https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions#using-just-in-time-runners'
+    label: 'Just-in-time runners documentation'
+  - url: 'https://github.com/github-aws-runners/terraform-aws-github-runner'
+    label: 'terraform-aws-github-runner (commonly affected autoscaler)'

package/errors/permissions-auth/upload-code-coverage-missing-code-quality-write-permission.yml

@@ -0,0 +1,94 @@
+id: permissions-auth-068
+title: 'upload-code-coverage action fails with 403 — missing code-quality:write permission'
+category: permissions-auth
+severity: error
+tags:
+  - permissions
+  - code-quality
+  - upload-code-coverage
+  - github-token
+  - 403
+  - fine-grained
+patterns:
+  - regex: 'Resource not accessible by integration'
+    flags: 'i'
+  - regex: 'Upload failed.*403|HTTP 403.*code.coverage|code.coverage.*403'
+    flags: 'i'
+  - regex: 'code-quality.*write|code_quality.*write'
+    flags: 'i'
+error_messages:
+  - '{"message":"Resource not accessible by integration","documentation_url":"https://docs.github.com/rest"}'
+  - 'Error: Upload failed: HTTP 403 Forbidden'
+  - 'HTTP Status: 403'
+root_cause: |
+  GitHub's code coverage upload API (introduced May 2026 as part of Code Quality for
+  pull requests) requires the new fine-grained permission `code-quality:write` on the
+  calling token. The default GITHUB_TOKEN in GitHub Actions workflows has this permission
+  set to `none` unless explicitly granted.
+
+  When `actions/upload-code-coverage` calls the coverage upload API without this
+  permission, GitHub returns HTTP 403 "Resource not accessible by integration". Because
+  `code-quality:write` is a newly introduced permission class (not present in older
+  workflow permission schemas), developers familiar with the standard permissions
+  (contents, issues, pull-requests, etc.) don't know to add it.
+
+  This affects all workflows that do not specify `permissions:` at all (which defaults to
+  `read-all` — but `code-quality` is still `none` for new permissions), as well as
+  workflows that explicitly set `permissions: {}` or use a restrictive block.
+fix: |
+  Add `code-quality: write` to the `permissions` block of the job that runs
+  `actions/upload-code-coverage`. This grants the GITHUB_TOKEN the required scope to
+  call the code coverage upload API.
+
+  Note: `code-quality:` is a job-level permission. It cannot be set as a global
+  `GITHUB_TOKEN` permission through repository settings — it must be declared in the
+  workflow YAML per-job.
+fix_code:
+  - language: yaml
+    label: 'Add code-quality:write to the coverage upload job'
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          permissions:
+            contents: read
+            code-quality: write    # Required for upload-code-coverage
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Run tests and generate coverage
+              run: pytest --cov=src --cov-report=xml
+
+            - name: Upload code coverage
+              uses: actions/upload-code-coverage@v1
+              with:
+                file: coverage.xml
+                language: Python
+  - language: yaml
+    label: 'Minimal permissions block if no others are needed'
+    code: |
+      jobs:
+        coverage:
+          runs-on: ubuntu-latest
+          permissions:
+            code-quality: write
+          steps:
+            - uses: actions/upload-code-coverage@v1
+              with:
+                file: cobertura.xml
+                language: Java
+                label: code-coverage/jacoco
+prevention:
+  - "Whenever you add actions/upload-code-coverage to a workflow, immediately add `code-quality: write` to the job's permissions block."
+  - "Use a linter or policy-as-code tool (e.g., Poutine, StepSecurity) that validates required permissions against known action requirements."
+  - "If your org uses required permissions: {} at the workflow level for security hardening, remember that code-quality: write must still be declared per-job."
+  - "Check the GitHub Changelog periodically — new actions introduce new permission classes that aren't reflected in older documentation or IDE auto-complete."
+docs:
+  - url: 'https://github.blog/changelog/2026-05-26-code-coverage-in-pull-requests-is-now-in-public-preview/'
+    label: 'GitHub Changelog: Code coverage in pull requests (May 26, 2026)'
+  - url: 'https://github.com/actions/upload-code-coverage'
+    label: 'actions/upload-code-coverage repository'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/controlling-permissions-for-github_token'
+    label: 'Controlling permissions for GITHUB_TOKEN'
+  - url: 'https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository'
+    label: 'GitHub Actions permissions documentation'

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/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/triggers/triggers-069.yml

@@ -0,0 +1,100 @@
+id: triggers-069
+title: 'push tags: filter silently stops all branch-push triggers — branches: filter must be added separately to also run on branch commits'
+category: triggers
+severity: silent-failure
+tags:
+  - push
+  - tags-filter
+  - branches
+  - silent-failure
+  - trigger-missing
+  - filter-whitelist
+patterns:
+  - regex: 'on:\s*\n\s+push:\s*\n\s+tags:'
+    flags: 'i'
+error_messages: []
+root_cause: |
+  When a workflow specifies on: push: with only a tags: filter and no branches: filter,
+  ALL branch push events are silently excluded. The workflow fires exclusively on tag
+  pushes matching the tags: pattern.
+
+  This contradicts the common mental model that tags: adds an extra "also trigger on
+  these tags" condition on top of the default "trigger on all branch pushes" behavior.
+  In reality, any filter key under on: push: (branches:, tags:, branches-ignore:,
+  tags-ignore:, paths:) replaces the implicit "trigger on everything" default with a
+  whitelist. Specifying tags: without branches: means only tags match.
+
+  A workflow with:
+    on:
+      push:
+        tags:
+          - 'v*'
+
+  will never fire when code is pushed to main, feature branches, or any other branch.
+  If the team also needs CI on commits to main or pull request merges, a separate
+  branches: filter is required in the same on: push: block.
+
+  This is the inverse of the documented "branches: filter does not block tag pushes"
+  behavior (triggers-055). Both stem from the same whitelist-per-filter-key design.
+fix: |
+  Add an explicit branches: filter alongside tags: to restore branch-push triggering:
+
+    on:
+      push:
+        branches:
+          - main
+        tags:
+          - 'v*'
+
+  If only tag-based triggering is intended (e.g., a release workflow), the original
+  configuration is correct. Document the intent clearly so future maintainers do not
+  accidentally add branches: thinking CI was "broken".
+
+  To trigger on ALL branch pushes plus specific tags, omit branches: from on: push:
+  and add a separate on: push: tags: entry — but note that on: push: without filters
+  and on: push: tags: cannot coexist in the same block; split into two trigger blocks
+  using pull_request for branch coverage and push: tags: for tags.
+fix_code:
+  - language: yaml
+    label: 'Bug: tags: filter silently excludes all branch-push events'
+    code: |
+      on:
+        push:
+          tags:
+            - 'v*'
+      # Workflow NEVER runs on branch pushes — only fires when a v* tag is pushed
+  - language: yaml
+    label: 'Fix: add branches: filter to also run on branch commits'
+    code: |
+      on:
+        push:
+          branches:
+            - main
+            - 'release/**'
+          tags:
+            - 'v*'
+
+      jobs:
+        ci:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: make test
+  - language: yaml
+    label: 'Intentional tag-only release workflow (correct if branch CI is handled in a separate workflow)'
+    code: |
+      # release.yml — intentionally runs only on release tags
+      on:
+        push:
+          tags:
+            - 'v[0-9]+.[0-9]+.[0-9]+'
+prevention:
+  - 'Remember that any filter key under on: push: creates a whitelist — adding tags: without branches: stops all branch-push triggers silently'
+  - 'Keep release tag workflows in a dedicated file (release.yml) separate from branch-CI workflows (ci.yml) to avoid accidentally merging their trigger logic'
+  - 'After adding a tags: filter to an existing workflow, push a test commit to a branch and verify the workflow appears in the Actions tab'
+  - 'Use nektos/act or GitHub Actions VS Code extension to preview which events match a workflow trigger before merging'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#push'
+    label: 'GitHub Docs: push event filters'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#onpushbranchestagsbranches-ignoretags-ignore'
+    label: 'GitHub Docs: Workflow syntax — on.push filter keys'

package/errors/yaml-syntax/continue-on-error-inputs-composite-action-unexpected-value.yml

@@ -0,0 +1,110 @@
+id: yaml-syntax-070
+title: "continue-on-error expression using inputs.* silently resolves null at composite action call site \u2014 \"Unexpected value ''\""
+category: yaml-syntax
+severity: error
+tags:
+  - continue-on-error
+  - composite-actions
+  - inputs-context
+  - expression-scoping
+  - template-validation
+patterns:
+  - regex: 'Unexpected value\s+''''$'
+    flags: 'i'
+  - regex: 'error.*determining.*continue on error'
+    flags: 'i'
+  - regex: 'The template is not valid.*Unexpected value\s+'''
+    flags: 'i'
+error_messages:
+  - "Error: .github/workflows/test.yml (Line: N, Col: N): Unexpected value ''"
+  - 'Error: The step failed and an error occurred when attempting to determine whether to continue on error.'
+  - "Error: The template is not valid. .github/workflows/test.yml (Line: N, Col: N): Unexpected value ''"
+root_cause: |
+  When continue-on-error on a uses: step that calls a composite action contains an
+  expression referencing inputs.*, the expression is evaluated inside the composite
+  action context — not the calling workflow context. Inside the composite action,
+  inputs refers to the composite action''s own declared inputs, not the caller''s
+  workflow_dispatch inputs or other workflow-level inputs.
+
+  If the composite action does not declare that input, inputs.my_flag resolves to
+  null, which becomes an empty string in the expression context. The runner then
+  tries to parse the empty string as a boolean and emits:
+
+    Error: Unexpected value ''
+
+  followed by:
+
+    Error: The step failed and an error occurred when attempting to determine
+    whether to continue on error.
+
+  The workflow then halts at that step regardless of what the caller intended.
+
+  This context-crossing is unique to uses: steps (composite actions). For run:
+  steps in the same job, inputs.my_flag evaluates in the workflow context and
+  works correctly with continue-on-error.
+fix: |
+  Replace inputs.* with github.event.inputs.* in the continue-on-error expression
+  when calling composite actions from a workflow_dispatch event. github.event.inputs
+  is evaluated in the workflow/runner context before the composite action is entered,
+  so it resolves correctly.
+
+  Alternatively, capture the input as a job-level env or step output and reference
+  the env var or step output in the continue-on-error expression.
+fix_code:
+  - language: yaml
+    label: 'Bug: inputs.continue resolves to null inside composite action context'
+    code: |
+      on:
+        workflow_dispatch:
+          inputs:
+            continue:
+              type: boolean
+              default: false
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: my-org/fail-action@main
+              # inputs.continue resolves to null here — "Unexpected value ''"
+              continue-on-error: ${{ github.event_name == 'workflow_dispatch' && inputs.continue }}
+  - language: yaml
+    label: 'Fix: use github.event.inputs.* instead of inputs.* in continue-on-error on uses: steps'
+    code: |
+      on:
+        workflow_dispatch:
+          inputs:
+            continue:
+              type: boolean
+              default: false
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: my-org/fail-action@main
+              # github.event.inputs evaluates in workflow context, not composite context
+              continue-on-error: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.continue == 'true' }}
+  - language: yaml
+    label: 'Alternative fix: pre-evaluate the flag into an env var'
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          env:
+            SHOULD_CONTINUE: ${{ inputs.continue }}
+          steps:
+            - uses: my-org/fail-action@main
+              continue-on-error: ${{ env.SHOULD_CONTINUE == 'true' }}
+prevention:
+  - 'Never reference inputs.* in continue-on-error on a uses: step — use github.event.inputs.* for workflow_dispatch inputs or env.* for pre-evaluated values'
+  - 'Remember that expression contexts differ between run: steps (workflow context) and uses: composite action steps (composite context)'
+  - 'Test continue-on-error with expressions locally using nektos/act before merging to catch context-crossing issues'
+  - 'If a composite action needs conditional behavior, declare it as an explicit composite input and pass the value from the caller'
+docs:
+  - url: 'https://github.com/actions/runner/issues/2418'
+    label: 'GitHub runner#2418: continue-on-error with inputs variables in composite actions (bug, 12 reactions)'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/evaluate-expressions-in-workflows-and-actions#context-availability'
+    label: 'GitHub Docs: Expression context availability'
+  - url: 'https://docs.github.com/en/actions/sharing-automations/creating-actions/creating-a-composite-action'
+    label: 'GitHub Docs: Creating a composite action'

package/package.json

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