@htekdev/actions-debugger 1.0.114 → 1.0.116

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/arc-ephemeral-runner-oom-kill-session-conflict.yml

@@ -0,0 +1,129 @@
+id: runner-environment-203
+title: 'ARC EphemeralRunner Stuck in Running State After OOM Kill — Scale Set Blocked'
+category: runner-environment
+severity: error
+tags:
+  - arc
+  - actions-runner-controller
+  - ephemeral-runner
+  - oomkill
+  - kubernetes
+  - scale-set
+  - session-conflict
+  - stuck
+  - self-hosted
+patterns:
+  - regex: 'RunnerScaleSetSessionConflictException'
+    flags: 'i'
+  - regex: 'TaskAgentSessionConflictException'
+    flags: 'i'
+  - regex: 'A session for this runner already exists'
+    flags: 'i'
+  - regex: 'Runner connect error: Error: Conflict\. Retrying until reconnected'
+    flags: 'i'
+error_messages:
+  - 'RunnerScaleSetSessionConflictException: there is already an active session'
+  - 'TaskAgentSessionConflictException: Error: Conflict'
+  - 'A session for this runner already exists.'
+  - '2026-XX-XX HH:MM:SSZ: Runner connect error: Error: Conflict. Retrying until reconnected.'
+root_cause: |
+  When an ARC (Actions Runner Controller) ephemeral runner pod is OOM-killed by the
+  Kubernetes kubelet (memory limit exceeded), the pod terminates abruptly without going
+  through the runner's graceful shutdown path. The runner never sends a "job completed" or
+  "runner offline" signal to the GitHub broker.
+
+  As a result:
+  1. The EphemeralRunner custom resource stays in phase `Running` indefinitely.
+  2. The ARC scale-set controller still counts the dead runner as "in use", so it does not
+     spin up a replacement pod to service the next queued job.
+  3. New jobs remain stuck at "Waiting for a runner to pick up this job..." until the
+     stale EphemeralRunner CR is manually deleted.
+
+  When ARC tries to restart the runner (either via a controller health check or manually),
+  the new runner pod connects to the GitHub broker using the same JIT token/session, and
+  the broker responds HTTP 409 Conflict because the old session is still registered:
+
+    TaskAgentSessionConflictException: Error: Conflict
+    A session for this runner already exists.
+    Runner connect error: Error: Conflict. Retrying until reconnected.
+
+  The runner retries every 30 seconds. After the broker's session lease expires (~2-3 min
+  in most cases), the conflict resolves and the runner connects — but the session timeout
+  window varies and can leave the scale set blocked for longer periods.
+
+  Versions affected:
+  - Reproducible across ARC v0.9.x - v0.12.x; partial mitigation added in ARC v0.12.0
+    (stale EphemeralRunner detection), but OOM kills on active runners can still bypass it.
+  - Frequently triggered by Vitest --coverage, Jest with large test suites, or any
+    memory-intensive build tool running without memory limits in the runner container.
+fix: |
+  Immediate recovery: delete the stuck EphemeralRunner CR to release the scale-set slot:
+
+    kubectl delete ephemeralrunner -n <namespace> <runner-name>
+
+  After deletion, ARC will spin up a new runner pod and pick up the queued job.
+
+  Root fix (prevent recurrence):
+  1. Set memory limits on runner containers that match actual job requirements with headroom.
+  2. Add workflow-level `timeout-minutes:` to ensure jobs terminate and release the runner
+     if they run too long.
+  3. Upgrade ARC to v0.12.0+ for improved stale EphemeralRunner detection.
+  4. Configure `terminationGracePeriodSeconds: 90` (or longer) on runner pods to give the
+     runner process time to deregister gracefully before the kubelet force-kills it.
+fix_code:
+  - language: yaml
+    label: 'Set memory limits and timeout on runner pods to prevent OOM kills'
+    code: |
+      # In your HelmRelease / values.yaml for actions-runner-controller
+      githubConfigUrl: "https://github.com/your-org/your-repo"
+      maxRunners: 4
+      minRunners: 0
+      template:
+        spec:
+          terminationGracePeriodSeconds: 90
+          containers:
+            - name: runner
+              image: ghcr.io/actions/actions-runner:latest
+              resources:
+                requests:
+                  memory: "2Gi"
+                  cpu: "500m"
+                limits:
+                  memory: "4Gi"   # Set appropriate limit; OOM kill occurs when exceeded
+                  cpu: "2"
+  - language: yaml
+    label: 'Add workflow timeout to guarantee runner release even on hang'
+    code: |
+      jobs:
+        test:
+          runs-on: arc-runner-set
+          timeout-minutes: 30   # Runner is released after 30 min even if job hangs
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm test -- --coverage
+  - language: yaml
+    label: 'Manual recovery: delete stuck EphemeralRunner CR'
+    code: |
+      # List stuck EphemeralRunners
+      kubectl get ephemeralrunner -n arc-systems
+
+      # Delete the stuck one (ARC will create a new pod automatically)
+      kubectl delete ephemeralrunner -n arc-systems <stuck-runner-name>
+
+      # Alternatively, delete all stuck runners in a namespace
+      kubectl delete ephemeralrunner -n arc-systems --field-selector='status.phase=Running'
+prevention:
+  - 'Always set memory limits on ARC runner containers; without limits, a single job can consume all node memory and OOM-kill other runners.'
+  - 'Set timeout-minutes: at the job level for all ARC-backed workflows to guarantee the runner is eventually released.'
+  - 'Upgrade ARC to v0.12.0+ for automatic stale EphemeralRunner cleanup.'
+  - 'Monitor EphemeralRunner phase distribution; a growing count of Running CRs with no corresponding pods is a leading indicator of this issue.'
+  - 'Add terminationGracePeriodSeconds: 90+ to runner pod templates so gradual shutdown signals have time to deregister the runner.'
+docs:
+  - url: 'https://github.com/actions/actions-runner-controller/issues/4155'
+    label: 'EphemeralRunner and its pods left stuck Running after runner OOMKILL (15 reactions)'
+  - url: 'https://github.com/actions/actions-runner-controller/issues/3922'
+    label: 'Scaleset controllers stuck with RunnerScaleSetSessionConflictException (12 reactions)'
+  - url: 'https://github.com/actions/runner/issues/4312'
+    label: 'Self-hosted runner gets stuck in active state, blocking queued jobs across multiple repositories'
+  - url: 'https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller'
+    label: 'Managing self-hosted runners with Actions Runner Controller'

package/errors/runner-environment/macos-26-homebrew-python313-removed-stdlib-modules.yml

@@ -0,0 +1,113 @@
+id: runner-environment-201
+title: 'macOS 26 Homebrew python@3 ships Python 3.13 — removed stdlib modules (cgi, imghdr, aifc, telnetlib) cause ModuleNotFoundError'
+category: runner-environment
+severity: error
+tags:
+  - macos
+  - macos-26
+  - python
+  - homebrew
+  - stdlib
+  - runner-image
+  - breaking-change
+patterns:
+  - regex: 'ModuleNotFoundError: No module named ''(cgi|imghdr|aifc|chunk|nntplib|telnetlib|uu|xdrlib|sndhdr|sunau|mailcap|msilib|pipes|crypt|spwd|ossaudiodev)'''
+    flags: 'i'
+  - regex: 'ImportError.*No module named.*cgi|No module named.*imghdr|No module named.*telnetlib'
+    flags: 'i'
+  - regex: 'python.*3\.13.*deprecated.*module|removed.*python.*3\.13'
+    flags: 'i'
+error_messages:
+  - 'ModuleNotFoundError: No module named ''cgi'''
+  - 'ModuleNotFoundError: No module named ''imghdr'''
+  - 'ModuleNotFoundError: No module named ''aifc'''
+  - 'ModuleNotFoundError: No module named ''telnetlib'''
+  - 'ModuleNotFoundError: No module named ''chunk'''
+  - 'ModuleNotFoundError: No module named ''nntplib'''
+root_cause: |
+  macOS 26 runner images ship Homebrew python@3 pointing to Python 3.13.x. Python
+  3.13 removed the following stdlib modules that were deprecated since Python 3.11:
+
+    cgi, cgitb, aifc, chunk, crypt, imghdr, mailcap, msilib (Windows only),
+    nntplib, ossaudiodev, pipes, sndhdr, spwd, sunau, telnetlib, uu, xdrlib
+
+  Workflows that call bare python3 (resolved to Homebrew Python 3.13 on macOS 26)
+  and import any of these modules fail with ModuleNotFoundError at runtime.
+
+  This affects:
+  - Scripts using cgi or cgitb for HTTP form parsing
+  - Image-type detection using imghdr (commonly used with Pillow-based workflows)
+  - Legacy FTP/NNTP clients using nntplib or telnetlib
+  - Audio file handling using aifc, sunau, or sndhdr
+
+  Workflows that previously ran on macos-14 or macos-15 (Homebrew Python 3.11/3.12)
+  are affected when the job label is macos-26 or when macos-latest migrates to
+  macOS 26. The failure is not immediately obvious because the error occurs at
+  import time inside Python, not at the runner level, and the runner step exits
+  with a non-zero code that may be mistaken for a test failure rather than an
+  environment regression.
+
+  Note: actions/setup-python@v5+ with an explicit python-version is unaffected —
+  this issue only affects scripts that rely on the system/Homebrew python3 binary.
+fix: |
+  Option 1 (recommended) — Pin Python with actions/setup-python:
+    Always use actions/setup-python with an explicit version to get the exact
+    Python version your code requires. This bypasses the Homebrew python@3 symlink.
+
+  Option 2 — Replace removed modules with modern equivalents:
+    - cgi        → urllib.parse + email.parser (or the 3rd-party 'cgi' backport)
+    - imghdr     → imghdr is available as the 3rd-party 'imghdr' backport on PyPI,
+                   or use python-magic / filetype for image detection
+    - telnetlib  → use telnetlib3 (PyPI) or asyncio-based Telnet
+    - aifc/sunau → use soundfile or wave for audio I/O
+
+  Option 3 — Pin Homebrew Python to 3.12 on macos-26 (temporary):
+    brew install python@3.12
+    brew link python@3.12 --force
+    echo "/usr/local/opt/python@3.12/bin" >> $GITHUB_PATH
+fix_code:
+  - language: yaml
+    label: 'Fix: pin Python version with actions/setup-python to avoid Homebrew python@3'
+    code: |
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'   # pins to 3.12; immune to Homebrew python@3 upgrade
+
+      - name: Install dependencies
+        run: pip install -r requirements.txt
+
+      - name: Run script
+        run: python script.py   # uses setup-python's 3.12, not Homebrew 3.13
+  - language: yaml
+    label: 'Fix: install removed modules from PyPI backports'
+    code: |
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+      - name: Install backported removed modules
+        run: |
+          pip install imghdr       # PyPI backport of imghdr for Python 3.13+
+          # pip install telnetlib3 # if using Telnet
+      - name: Run script
+        run: python script.py
+  - language: yaml
+    label: 'Temporary: install and use python@3.12 from Homebrew on macos-26'
+    code: |
+      - name: Pin Homebrew Python to 3.12
+        run: |
+          brew install python@3.12
+          echo "/usr/local/opt/python@3.12/libexec/bin" >> $GITHUB_PATH
+      - name: Verify Python version
+        run: python3 --version   # should print Python 3.12.x
+prevention:
+  - 'Always use actions/setup-python with an explicit version — never rely on bare python3 pointing to Homebrew python@3'
+  - 'Audit scripts for imports of modules removed in Python 3.13: cgi, imghdr, aifc, telnetlib, nntplib, chunk, uu'
+  - 'Run pyupgrade --py313-plus locally before the macos-26 migration to catch deprecated imports'
+  - 'Add python --version to diagnostic steps to catch unexpected Python version changes early'
+docs:
+  - url: 'https://docs.python.org/3/whatsnew/3.13.html#removed-modules'
+    label: 'Python 3.13: Removed modules (official docs)'
+  - url: 'https://peps.python.org/pep-0594/'
+    label: 'PEP 594: Removing dead batteries from the standard library'
+  - url: 'https://github.com/actions/setup-python'
+    label: 'actions/setup-python: Pin a specific Python version'