@htekdev/actions-debugger 1.0.43 → 1.0.45

package/errors/known-unsolved/environment-matrix-one-review-per-job.yml

@@ -0,0 +1,100 @@
+id: known-unsolved-034
+title: 'environment deployment protection with required reviewers creates one review request per matrix job — no batch approval'
+category: known-unsolved
+severity: limitation
+tags:
+  - environment
+  - matrix
+  - deployment
+  - required-reviewers
+  - approvals
+  - no-fix
+patterns:
+  - regex: 'Waiting for.*review'
+    flags: 'i'
+  - regex: 'Review required before this job runs'
+    flags: 'i'
+error_messages:
+  - 'Waiting for a reviewer'
+  - 'Review required before this job runs'
+root_cause: |
+  GitHub Actions environments with required reviewers enforce approval at the
+  individual job level. When a job using environment: with required reviewers
+  also uses strategy: matrix, each matrix cell creates a separate deployment
+  instance requiring its own approval.
+
+  A 3x3 matrix (os x environment) produces 9 separate "Waiting for reviewer"
+  prompts in the GitHub Actions UI — one for each matrix combination. Each
+  must be approved individually; there is no "approve all" button for
+  matrix deployments.
+
+  This behavior stems from GitHub's deployment model: each job run creates a
+  discrete deployment record in the repository's deployment history. Matrix
+  jobs are independent job runs, so each creates its own deployment record
+  and independently triggers the environment protection review gate.
+
+  This is confirmed expected behavior per GitHub staff in community discussions.
+  There is no configuration option to batch or group matrix job deployment approvals.
+fix: |
+  There is no supported way to batch-approve matrix jobs targeting a protected
+  environment. The workaround is architectural: separate the build/test matrix
+  from the deployment job, using a single non-matrix deploy job that depends
+  on all matrix results via needs:.
+
+  This "build in matrix, deploy once" pattern also aligns with security best
+  practice — production deployments should be a single auditable event.
+fix_code:
+  - language: yaml
+    label: 'Anti-pattern — matrix job with protected environment (creates N review requests)'
+    code: |
+      jobs:
+        deploy:
+          strategy:
+            matrix:
+              region: [us-east-1, eu-west-1, ap-southeast-1]
+          environment: production   # 3 separate review requests
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "deploying to ${{ matrix.region }}"
+  - language: yaml
+    label: 'Workaround — single non-matrix deploy job collects matrix artifacts and deploys once'
+    code: |
+      jobs:
+        build:
+          strategy:
+            matrix:
+              region: [us-east-1, eu-west-1, ap-southeast-1]
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - name: Build for region
+              run: make build REGION=${{ matrix.region }}
+            - uses: actions/upload-artifact@v4
+              with:
+                name: build-${{ matrix.region }}
+                path: dist/
+
+        deploy:
+          needs: build
+          runs-on: ubuntu-latest
+          environment: production   # Single review request for all regions
+          steps:
+            - uses: actions/download-artifact@v4
+              with:
+                pattern: build-*
+                merge-multiple: true
+                path: all-dist/
+            - name: Deploy all regions
+              run: make deploy-all ARTIFACTS_DIR=all-dist/
+prevention:
+  - 'Design deployment workflows so the job with environment: protection is never a matrix job'
+  - 'Use build-in-matrix, deploy-once pattern: matrix for build/test, single serial job for protected deploy'
+  - 'If per-region deployments must be parallel and require environment protection, accept the N-approvals UX'
+  - 'Document this limitation in team runbooks before adopting matrix + environment patterns in production pipelines'
+docs:
+  - url: 'https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-deployments/managing-environments-for-deployment'
+    label: 'GitHub Docs — Managing environments for deployment'
+  - url: 'https://github.com/orgs/community/discussions/15690'
+    label: 'GitHub Community — Matrix deployment creates multiple approval requests'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-a-matrix-for-your-workflow'
+    label: 'GitHub Docs — Using a matrix for your workflow'

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

@@ -0,0 +1,97 @@
+id: known-unsolved-035
+title: "workflow_run trigger only fires for same-repo workflows — cross-repo chaining not supported"
+category: known-unsolved
+severity: limitation
+tags:
+  - workflow_run
+  - cross-repo
+  - triggers
+  - repository-dispatch
+  - known-limitation
+  - event-chaining
+patterns:
+  - regex: 'workflow_run.*never.*trigger|on.*workflow_run.*different.*repo'
+    flags: "i"
+  - regex: 'cross.repo.*workflow.run|workflow_run.*external.*repo'
+    flags: "i"
+error_messages:
+  - "workflow_run trigger does not fire for workflows in a different repository"
+root_cause: |
+  The on: workflow_run trigger only listens to workflow completion events in the same
+  repository. It cannot subscribe to events from workflows in external repositories,
+  even within the same organization or enterprise. Teams building cross-repository
+  CI/CD chains (e.g., "when repo-A build finishes, trigger repo-B deploy") discover
+  that the downstream workflow simply never starts — there is no error, just silence.
+
+  This is a platform design decision: workflow_run was built for intra-repo fan-out
+  (e.g., running security scans after CI passes) and not for cross-repo event routing.
+
+  Common scenarios where this limitation is hit:
+  - Platform team repo triggering deploy workflows in service repos
+  - Shared library repo signaling consumers after a release
+  - Monorepo-to-polyrepo migration preserving CI event chains
+  - Organization-wide rollout pipelines spanning multiple repositories
+fix: |
+  Use repository_dispatch for cross-repo event chaining. The upstream workflow sends
+  a POST to the GitHub REST API to create a repository_dispatch event in the downstream
+  repo. The downstream workflow listens on on: repository_dispatch: types: [...].
+
+  This requires a PAT (classic) with repo scope, or a GitHub App token with contents:
+  write or actions: write on the downstream repository. The peter-evans/repository-dispatch
+  action is the most widely used wrapper.
+fix_code:
+  - language: yaml
+    label: "Upstream (repo-A): dispatch event to repo-B on workflow completion"
+    code: |
+      # .github/workflows/build.yml in repo-A
+      on:
+        push:
+          branches: [main]
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Build
+              run: make build
+
+            - name: Trigger deployment in repo-B
+              uses: peter-evans/repository-dispatch@v3
+              with:
+                token: ${{ secrets.CROSS_REPO_PAT }}
+                repository: my-org/repo-B
+                event-type: repo-a-build-complete
+                client-payload: >-
+                  {"sha": "${{ github.sha }}", "ref": "${{ github.ref }}",
+                   "run_id": "${{ github.run_id }}"}
+  - language: yaml
+    label: "Downstream (repo-B): receive repository_dispatch from repo-A"
+    code: |
+      # .github/workflows/deploy.yml in repo-B
+      on:
+        repository_dispatch:
+          types: [repo-a-build-complete]
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Deploy
+              run: |
+                echo "Triggered by SHA: ${{ github.event.client_payload.sha }}"
+                echo "Source run: ${{ github.event.client_payload.run_id }}"
+                # deploy steps here
+prevention:
+  - "Use repository_dispatch for cross-repository event chaining — workflow_run is same-repo only"
+  - "Document this limitation in workflow comments so future maintainers don't spend time debugging non-firing triggers"
+  - "Consider reusable workflows (workflow_call) for sharing logic within an org instead of cross-repo triggers"
+  - "For org-wide fan-out, a central platform repo dispatching to all downstream repos is a common pattern"
+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 trigger"
+  - 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://github.com/peter-evans/repository-dispatch"
+    label: "peter-evans/repository-dispatch action"
+  - url: "https://github.com/orgs/community/discussions/26323"
+    label: "GitHub Community #26323: workflow_run cross-repo limitation confirmed"

package/errors/permissions-auth/attest-build-provenance-missing-attestations-write.yml

@@ -0,0 +1,100 @@
+id: permissions-auth-035
+title: 'actions/attest-build-provenance fails with 403 — missing attestations: write permission'
+category: permissions-auth
+severity: error
+tags:
+  - attestations
+  - attest-build-provenance
+  - GITHUB_TOKEN
+  - permissions
+  - 403
+  - supply-chain
+patterns:
+  - regex: 'HttpError.*403.*attestation'
+    flags: 'i'
+  - regex: 'Resource not accessible by integration'
+    flags: 'i'
+  - regex: 'Failed to create attestation'
+    flags: 'i'
+error_messages:
+  - 'HttpError: 403 — Resource not accessible by integration'
+  - 'Failed to create attestation'
+  - 'Error: Resource not accessible by integration'
+root_cause: |
+  actions/attest-build-provenance (introduced GitHub Changelog, May 2024) requires
+  the GITHUB_TOKEN to have the attestations: write scope. This permission did not
+  exist before the attestations feature was released and is NOT included in the
+  GitHub Actions default token permissions, nor in commonly used broad permission
+  sets like contents: write or id-token: write.
+
+  When the workflow omits attestations: write from its permissions block, the
+  action fails with a 403 "Resource not accessible by integration" error. The
+  error message does not explicitly mention "attestations: write" as the missing
+  scope, making the root cause difficult to identify.
+
+  Common mistake: developers copy the attest-build-provenance action from
+  documentation examples or third-party tutorials that may not include the full
+  permissions block, or they use a minimal permissions block that covers other
+  needs (contents: read, packages: write) without adding attestations: write.
+
+  Organization policy note: if the organization has disabled the attestations
+  feature, even a correctly-permissioned workflow will fail. Check org-level
+  Actions settings under Settings > Actions > General.
+fix: |
+  Add attestations: write to the permissions block of the job (or workflow)
+  that runs actions/attest-build-provenance. If using OIDC for cloud auth,
+  id-token: write is also required for the attestation signature.
+fix_code:
+  - language: yaml
+    label: 'Add attestations: write to job permissions'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          permissions:
+            contents: read
+            attestations: write   # Required for attest-build-provenance
+            id-token: write       # Required for OIDC-based attestation signing
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Build artifact
+              run: make build
+
+            - uses: actions/attest-build-provenance@v2
+              with:
+                subject-path: dist/my-artifact
+  - language: yaml
+    label: 'Container registry publish with attestation'
+    code: |
+      jobs:
+        publish:
+          runs-on: ubuntu-latest
+          permissions:
+            contents: read
+            packages: write
+            attestations: write   # Required
+            id-token: write       # Required
+          steps:
+            - uses: actions/checkout@v4
+            - uses: docker/build-push-action@v6
+              id: push
+              with:
+                push: true
+                tags: ghcr.io/${{ github.repository }}:latest
+            - uses: actions/attest-build-provenance@v2
+              with:
+                subject-name: ghcr.io/${{ github.repository }}
+                subject-digest: ${{ steps.push.outputs.digest }}
+prevention:
+  - 'Always include both attestations: write and id-token: write when using attest-build-provenance'
+  - 'Check action release notes when adding actions that use newer GitHub platform features'
+  - 'The missing scope is not always named in 403 error messages — cross-reference the action docs for required permissions'
+  - 'Enable required_workflows or org-level policies to verify attestation is permitted before deploying'
+docs:
+  - url: 'https://docs.github.com/en/actions/security-for-github-actions/using-artifact-attestations/using-artifact-attestations-to-establish-provenance-for-builds'
+    label: 'GitHub Docs — Using artifact attestations to establish provenance'
+  - url: 'https://github.com/actions/attest-build-provenance'
+    label: 'actions/attest-build-provenance repository'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/controlling-permissions-for-github_token'
+    label: 'GitHub Docs — Controlling permissions for GITHUB_TOKEN'

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

@@ -0,0 +1,69 @@
+id: runner-environment-100
+title: "ubuntu-24.04 libmysqlclient-dev renamed to default-libmysqlclient-dev — apt install fails"
+category: runner-environment
+severity: error
+tags:
+  - ubuntu-24.04
+  - apt
+  - mysql
+  - libmysqlclient
+  - migration
+  - package-rename
+patterns:
+  - regex: 'Package .libmysqlclient-dev. has no installation candidate'
+    flags: "i"
+  - regex: 'Unable to locate package openjdk-8|libmysqlclient-dev.*no installation'
+    flags: "i"
+error_messages:
+  - "E: Package 'libmysqlclient-dev' has no installation candidate"
+  - "Package 'libmysqlclient-dev' has no installation candidate"
+root_cause: |
+  In Ubuntu 24.04 (Noble Numbat), the libmysqlclient-dev package was removed from
+  the default apt repositories. MySQL 8.x development headers are now provided by
+  default-libmysqlclient-dev (a metapackage resolving to MySQL or MariaDB headers)
+  or the MariaDB-specific libmariadb-dev. Workflows migrating from ubuntu-22.04
+  (which carried libmysqlclient-dev) to ubuntu-24.04 fail at the apt-get install
+  step. This affects Django (mysqlclient), Ruby on Rails (mysql2 gem), PHP (mysqli
+  extension compile), and Go applications using CGO MySQL bindings.
+fix: |
+  Replace libmysqlclient-dev with default-libmysqlclient-dev, which resolves to
+  the correct MySQL or MariaDB dev headers on Ubuntu 22.04 and 24.04. For projects
+  strictly requiring Oracle MySQL headers, add the official MySQL APT repository
+  before installing.
+fix_code:
+  - language: yaml
+    label: "Replace libmysqlclient-dev with default-libmysqlclient-dev"
+    code: |
+      - name: Install MySQL development headers
+        run: |
+          sudo apt-get update
+          # libmysqlclient-dev removed in Ubuntu 24.04 — use default-libmysqlclient-dev
+          sudo apt-get install -y default-libmysqlclient-dev
+  - language: yaml
+    label: "Alternative: MariaDB headers explicitly"
+    code: |
+      - name: Install MariaDB development headers
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libmariadb-dev pkg-config
+  - language: yaml
+    label: "Alternative: Oracle MySQL APT repo for strict MySQL requirement"
+    code: |
+      - name: Add Oracle MySQL APT repository
+        run: |
+          wget https://dev.mysql.com/get/mysql-apt-config_0.8.33-1_all.deb
+          sudo dpkg -i mysql-apt-config_0.8.33-1_all.deb
+          sudo apt-get update
+          sudo apt-get install -y libmysqlclient-dev
+prevention:
+  - "Grep workflow files for libmysqlclient-dev before migrating from ubuntu-22.04 to ubuntu-24.04"
+  - "Use default-libmysqlclient-dev in all new workflows — it works on both Ubuntu 22.04 and 24.04"
+  - "Pin MySQL client library versions in requirements.txt or Gemfile rather than relying on system headers"
+  - "Add an ubuntu-24.04 job to the matrix before retiring ubuntu-22.04 to catch apt package renames early"
+docs:
+  - url: "https://packages.ubuntu.com/noble/default-libmysqlclient-dev"
+    label: "Ubuntu Noble: default-libmysqlclient-dev"
+  - url: "https://dev.mysql.com/doc/refman/8.0/en/linux-installation-apt-repo.html"
+    label: "MySQL APT Repository Guide"
+  - url: "https://github.com/actions/runner-images/issues/9932"
+    label: "runner-images #9932: Ubuntu 24.04 MySQL package rename"

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

@@ -0,0 +1,73 @@
+id: runner-environment-101
+title: "ubuntu-24.04 openjdk-8-jdk unavailable via apt — must use actions/setup-java"
+category: runner-environment
+severity: error
+tags:
+  - ubuntu-24.04
+  - java
+  - openjdk
+  - apt
+  - migration
+  - jdk8
+patterns:
+  - regex: 'Package .openjdk-8-(jdk|jre|jre-headless). has no installation candidate'
+    flags: "i"
+  - regex: 'Unable to locate package openjdk-8'
+    flags: "i"
+error_messages:
+  - "E: Package 'openjdk-8-jdk' has no installation candidate"
+  - "E: Unable to locate package openjdk-8-jdk"
+  - "E: Package 'openjdk-8-jre-headless' has no installation candidate"
+root_cause: |
+  Ubuntu 24.04 (Noble) dropped OpenJDK 8 from its official apt repositories because
+  OpenJDK 8 reached end-of-life upstream. Workflows that install Java via
+  apt-get install -y openjdk-8-jdk succeed on ubuntu-22.04 but fail immediately on
+  ubuntu-24.04 with "no installation candidate". Common affected scenarios include:
+
+  - Legacy Android builds requiring Java 8 compile target
+  - Apache Ant or Maven builds with a Java 8 minimum
+  - Older Spring Boot projects targeting Java 8
+  - Workflows that manually set JAVA_HOME after apt-get install
+
+  The actions/setup-java action with the temurin distribution still supports Java 8
+  and is the recommended cross-platform replacement.
+fix: |
+  Replace apt-get install openjdk-8-jdk with actions/setup-java using the temurin
+  (Eclipse Adoptium, formerly AdoptOpenJDK) distribution. This resolves correctly
+  on ubuntu-22.04, ubuntu-24.04, macOS, and Windows runners. Migrate to Java 11 or
+  17 LTS if the project allows — Java 8 is past end-of-life.
+fix_code:
+  - language: yaml
+    label: "Replace apt install with actions/setup-java for JDK 8"
+    code: |
+      - name: Set up Java 8
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin   # Eclipse Adoptium (formerly AdoptOpenJDK)
+          java-version: '8'
+          # Prefer java-version: '17' or '21' where the project allows
+  - language: yaml
+    label: "Matrix: test multiple Java versions"
+    code: |
+      strategy:
+        matrix:
+          java: ['8', '11', '17', '21']
+      steps:
+        - uses: actions/setup-java@v4
+          with:
+            distribution: temurin
+            java-version: ${{ matrix.java }}
+prevention:
+  - "Prefer actions/setup-java over apt-get for Java in all workflows — explicit version pinning works cross-platform"
+  - "Upgrade to Java 11 or 17 LTS where feasible — Java 8 is EOL"
+  - "Search workflow files for openjdk-8 before migrating the runner label to ubuntu-24.04"
+  - "Use distribution: zulu as an alternative Azul OpenJDK distribution if Temurin is not suitable"
+docs:
+  - url: "https://github.com/actions/setup-java"
+    label: "actions/setup-java — supported distributions and versions"
+  - url: "https://adoptium.net/temurin/releases/?version=8"
+    label: "Eclipse Temurin Java 8 Releases"
+  - url: "https://packages.ubuntu.com/search?keywords=openjdk-8"
+    label: "Ubuntu Package Search: openjdk-8 availability"
+  - url: "https://github.com/actions/runner-images/issues/9848"
+    label: "runner-images #9848: openjdk-8 missing on Ubuntu 24.04"

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

@@ -0,0 +1,89 @@
+id: runner-environment-102
+title: "macOS 14+ xcrun altool removed — notarization workflows fail with 'unable to find utility'"
+category: runner-environment
+severity: error
+tags:
+  - macos
+  - xcode
+  - notarization
+  - altool
+  - notarytool
+  - codesign
+  - migration
+patterns:
+  - regex: 'xcrun: error: unable to find utility .altool.'
+    flags: "i"
+  - regex: 'altool.*has been deprecated and is no longer supported|unable to find utility .altool.'
+    flags: "i"
+error_messages:
+  - "xcrun: error: unable to find utility \"altool\", not a developer tool or in PATH"
+  - "altool has been deprecated and is no longer supported"
+root_cause: |
+  xcrun altool was Apple's original notarization CLI tool. Apple deprecated it in
+  Xcode 13 (WWDC 2021) and removed it entirely in Xcode 15 (September 2023).
+  GitHub's macOS 14, macOS 15, and macOS 26 runners ship Xcode 15 or later, so
+  altool is not present on these runners.
+
+  Workflows that use any of the following commands fail immediately on macos-14+:
+    xcrun altool --notarize-app ...
+    xcrun altool --notarization-info ...
+    xcrun altool --staple-archive ...
+    xcrun altool --notarization-history ...
+
+  This is a runner image migration break: workflows working on macos-12 or macos-13
+  (Xcode 14) silently stop working when the runner label switches to macos-14 or
+  macos-latest, which ships Xcode 15+. The failure is loud (non-zero exit from
+  xcrun) but easy to miss if teams assume the mac runner version did not change.
+fix: |
+  Migrate to xcrun notarytool, the replacement for altool since Xcode 13. Notarytool
+  accepts the same Apple ID + app-specific password credentials or the more secure
+  App Store Connect API key (recommended for CI — avoids 2FA issues). Submissions
+  complete synchronously with --wait, replacing the polling loop previously required
+  by altool.
+fix_code:
+  - language: yaml
+    label: "Migrate from altool to notarytool (Apple ID auth)"
+    code: |
+      - name: Notarize app
+        env:
+          APPLE_ID: ${{ secrets.APPLE_ID }}
+          APPLE_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
+          TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+        run: |
+          xcrun notarytool submit MyApp.zip \
+            --apple-id "$APPLE_ID" \
+            --password "$APPLE_PASSWORD" \
+            --team-id "$TEAM_ID" \
+            --wait
+
+      - name: Staple notarization ticket
+        run: xcrun stapler staple MyApp.app
+  - language: yaml
+    label: "Preferred: App Store Connect API key auth (no 2FA issues)"
+    code: |
+      - name: Notarize with App Store Connect API key
+        env:
+          API_KEY_ID: ${{ secrets.AC_API_KEY_ID }}
+          API_KEY_ISSUER: ${{ secrets.AC_API_KEY_ISSUER }}
+          API_KEY_PATH: /tmp/AuthKey.p8
+        run: |
+          printf '%s' "${{ secrets.AC_API_KEY }}" > "$API_KEY_PATH"
+          xcrun notarytool submit MyApp.zip \
+            --key "$API_KEY_PATH" \
+            --key-id "$API_KEY_ID" \
+            --issuer "$API_KEY_ISSUER" \
+            --wait
+prevention:
+  - "Migrate all xcrun altool commands to xcrun notarytool — altool is gone on any Xcode 15+ runner"
+  - "Prefer App Store Connect API key authentication in CI — avoids 2FA prompts and app-specific password rotation"
+  - "Search workflow files for altool before updating the macos runner label from macos-13 to macos-14 or macos-latest"
+  - "Test notarization on macos-14 alongside macos-13 before fully retiring the older runner label"
+docs:
+  - url: "https://developer.apple.com/documentation/notaryapi"
+    label: "Apple: Notary API (notarytool)"
+  - url: "https://developer.apple.com/news/releases/xcode-15-release-notes/"
+    label: "Xcode 15 Release Notes — altool removal"
+  - url: "https://developer.apple.com/documentation/security/notarizing-macos-software-before-distribution/customizing-the-notarization-workflow"
+    label: "Apple: Customizing the notarization workflow"
+  - url: "https://github.com/actions/runner-images/discussions/7505"
+    label: "runner-images: macOS 14 Xcode 15 notarization migration"

package/errors/runner-environment/setup-python-version-range-resolves-to-313-distutils-removed.yml

@@ -0,0 +1,107 @@
+id: runner-environment-099
+title: "setup-python python-version '3' resolves to Python 3.13 — distutils and other removed modules cause ImportError"
+category: runner-environment
+severity: error
+tags:
+  - setup-python
+  - python-3-13
+  - distutils
+  - breaking-change
+  - version-pinning
+patterns:
+  - regex: 'ModuleNotFoundError.*distutils'
+    flags: 'i'
+  - regex: 'No module named .distutils.'
+    flags: 'i'
+  - regex: 'ImportError.*distutils'
+    flags: 'i'
+error_messages:
+  - "ModuleNotFoundError: No module named 'distutils'"
+  - "No module named 'distutils'"
+  - "error: can't find distutils"
+root_cause: |
+  Python 3.12 moved distutils into setuptools (no longer stdlib), and Python 3.13
+  fully removed it from the standard library (PEP 632, deprecated since 3.10).
+
+  GitHub Actions workflows using a floating python-version constraint:
+    python-version: '3'
+    python-version: '3.x'
+    python-version: 'latest'
+  ...resolved to Python 3.13 when it became the latest stable release (October 2024).
+  Runner images updated to include 3.13 as the available version for these constraints.
+
+  Any project that imports distutils directly (setup.py, older NumPy, Cython, some
+  SWIG bindings) or tools that internally import it will fail with:
+    ModuleNotFoundError: No module named 'distutils'
+
+  Additional modules removed in Python 3.12-3.13 that break CI:
+  - cgi, imghdr (removed 3.13)
+  - aifc, sunau, chunk, crypt (removed 3.13)
+  - imp module (removed 3.12)
+  - asynchat, asyncore (removed 3.12)
+
+  The failure is from the floating version constraint resolving higher than intended,
+  not from the runner image itself. Pinned workflows on 3.11 or 3.12 are unaffected.
+fix: |
+  Pin python-version to a specific minor version instead of using a floating
+  constraint. If distutils is required, use the setuptools-provided shim.
+
+  Migration options for distutils usage:
+  - Replace distutils.core.setup with setuptools.setup
+  - Replace distutils.util.strtobool with a custom bool parser
+  - Replace distutils.version.LooseVersion with packaging.version.Version
+  - Install setuptools on Python 3.13 to restore the distutils shim
+fix_code:
+  - language: yaml
+    label: 'Pin to specific minor version to avoid 3.13+ resolution'
+    code: |
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'   # Pinned — won't resolve to 3.13+
+          # OR: '3.12'  (distutils still available via setuptools shim)
+  - language: yaml
+    label: 'Use setuptools shim on Python 3.13'
+    code: |
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+      - name: Install setuptools for distutils compatibility
+        run: pip install setuptools   # Restores distutils shim on 3.13+
+  - language: yaml
+    label: 'Pin version via .python-version file'
+    code: |
+      # .python-version file in repo root:
+      # 3.11.9
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version-file: '.python-version'   # Reads from repo file
+  - language: yaml
+    label: 'Matrix across versions to catch breakage early'
+    code: |
+      jobs:
+        test:
+          strategy:
+            matrix:
+              python-version: ['3.11', '3.12', '3.13']
+          steps:
+            - uses: actions/setup-python@v5
+              with:
+                python-version: ${{ matrix.python-version }}
+            - run: pip install setuptools   # Shim for 3.13
+            - run: pip install -e .
+            - run: pytest
+prevention:
+  - 'Never use python-version: 3 or python-version: 3.x in production workflows without testing each new minor release'
+  - 'Pin to a specific minor version (3.11, 3.12) or use a .python-version file in the repo'
+  - 'Run CI on a matrix of python versions to catch version-specific breakage early'
+  - 'Audit setup.py for direct distutils imports and replace with setuptools equivalents before upgrading to 3.13'
+docs:
+  - url: 'https://docs.python.org/3/whatsnew/3.13.html#removed-modules'
+    label: 'Python 3.13 — Removed Modules'
+  - url: 'https://peps.python.org/pep-0632/'
+    label: 'PEP 632 — Deprecate distutils'
+  - url: 'https://github.com/actions/setup-python'
+    label: 'actions/setup-python repository'
+  - url: 'https://docs.github.com/en/actions/use-cases-and-examples/building-and-testing/building-and-testing-python'
+    label: 'GitHub Docs — Building and testing Python'

package/errors/silent-failures/github-output-heredoc-delimiter-collision.yml

@@ -0,0 +1,83 @@
+id: silent-failures-049
+title: 'GITHUB_OUTPUT multiline heredoc value silently truncated when content contains the delimiter string'
+category: silent-failures
+severity: silent-failure
+tags:
+  - GITHUB_OUTPUT
+  - multiline
+  - heredoc
+  - delimiter-collision
+  - environment-files
+patterns:
+  - regex: 'echo\s+\"\w+<<EOF\"'
+    flags: 'i'
+error_messages: []
+root_cause: |
+  GitHub Actions environment files (GITHUB_OUTPUT, GITHUB_ENV, GITHUB_STEP_SUMMARY)
+  use a heredoc-style syntax for multiline values:
+
+    echo "BODY<<EOF" >> $GITHUB_OUTPUT
+    echo "first line" >> $GITHUB_OUTPUT
+    echo "second line" >> $GITHUB_OUTPUT
+    echo "EOF" >> $GITHUB_OUTPUT
+
+  If the multiline content itself contains the exact delimiter string ("EOF" in
+  the example above) on a line by itself, the runner stops reading at that point
+  and silently truncates the value. No error is raised and the step exits 0.
+
+  Common scenarios:
+  1. A release body or commit message that happens to contain "EOF" on its own line.
+  2. A generated file that includes shell script snippets (which often use EOF).
+  3. A changelog that uses EOF as a delimiter in a code example.
+
+  The delimiter collision causes the output variable to contain only the content
+  up to (but not including) the first occurrence of the delimiter string, with
+  no indication that truncation occurred.
+fix: |
+  Use a randomly-generated or sufficiently unique delimiter that will not
+  appear in the content. Common approaches:
+
+  1. Generate a UUID or random hex string at runtime and use it as the delimiter.
+  2. Use a very long, unusual string that is unlikely to appear in content.
+
+  The GitHub documentation explicitly recommends a random delimiter to avoid
+  this collision:
+    https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#multiline-strings
+fix_code:
+  - language: yaml
+    label: 'Unsafe — static delimiter may collide with content'
+    code: |
+      - name: Set multiline output (unsafe)
+        run: |
+          echo "BODY<<EOF" >> $GITHUB_OUTPUT
+          echo "${{ steps.notes.outputs.content }}" >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
+  - language: yaml
+    label: 'Safe — random delimiter prevents collision'
+    code: |
+      - name: Set multiline output (safe random delimiter)
+        run: |
+          DELIM="ghadelim_$(head -c 16 /dev/urandom | base64 | tr -dc 'a-zA-Z0-9' | head -c 16)"
+          echo "BODY<<${DELIM}" >> $GITHUB_OUTPUT
+          echo "${{ steps.notes.outputs.content }}" >> $GITHUB_OUTPUT
+          echo "${DELIM}" >> $GITHUB_OUTPUT
+  - language: yaml
+    label: 'Windows — PowerShell random delimiter'
+    code: |
+      - name: Set multiline output (PowerShell)
+        shell: pwsh
+        run: |
+          $delim = "ghadelim_$([System.Guid]::NewGuid().ToString('N').Substring(0, 16))"
+          "BODY<<$delim" | Out-File -FilePath $env:GITHUB_OUTPUT -Append -Encoding utf8
+          $releaseNotes | Out-File -FilePath $env:GITHUB_OUTPUT -Append -Encoding utf8
+          $delim | Out-File -FilePath $env:GITHUB_OUTPUT -Append -Encoding utf8
+prevention:
+  - 'Never use a simple static delimiter like EOF, END, or DONE for multiline GITHUB_OUTPUT values'
+  - 'Always use a random or UUID-based delimiter when the content could be dynamic or user-provided'
+  - 'Test multiline output steps with content that deliberately contains common delimiter strings'
+  - 'GitHub docs recommend randomly generated delimiters for all multiline environment file writes'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#multiline-strings'
+    label: 'GitHub Docs — Workflow commands: multiline strings'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables'
+    label: 'GitHub Docs — Store information in variables'

package/package.json

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