@htekdev/actions-debugger 1.0.19 → 1.0.21

package/errors/permissions-auth/fine-grained-pat-org-restricted-forbidden.yml

@@ -0,0 +1,104 @@
+id: permissions-auth-024
+title: "Fine-Grained PATs Blocked by Organization Policy — 'forbidden from accessing this repository'"
+category: permissions-auth
+severity: error
+tags:
+  - fine-grained-pat
+  - organization-policy
+  - personal-access-token
+  - authentication
+  - 403
+patterns:
+  - regex: "Fine-grained personal access tokens are forbidden from accessing this repository"
+    flags: "i"
+  - regex: "fine.grained.*forbidden|forbidden.*fine.grained"
+    flags: "i"
+  - regex: "personal access tokens.*not permitted|PAT.*restricted"
+    flags: "i"
+error_messages:
+  - "remote: Fine-grained personal access tokens are forbidden from accessing this repository."
+  - "fatal: unable to access 'https://github.com/org/repo.git/': The requested URL returned error: 403"
+  - "Fine-grained personal access tokens are forbidden from accessing this repository."
+root_cause: |
+  GitHub organizations can restrict which types of PATs are allowed to access their
+  resources. When an organization enables "Restrict access via fine-grained personal
+  access tokens" (or sets PAT policy to "Disable fine-grained personal access tokens"),
+  any fine-grained PAT — regardless of its scopes or permissions — will be rejected
+  with a 403 error containing the message "Fine-grained personal access tokens are
+  forbidden from accessing this repository."
+
+  This policy applies even if:
+  - The fine-grained PAT has all required permissions (contents: write, etc.)
+  - The PAT was created by an org owner
+  - The repository is public
+  - The user is an org admin
+
+  Common confusion: developers who switch from classic PATs to fine-grained PATs
+  for better security/granularity hit this org-level block and cannot understand
+  why a seemingly correct token still fails with 403.
+
+  Sources: stackoverflow.com/questions/79471500,
+           GitHub Docs on PAT policies for organizations
+fix: |
+  Option 1 (Immediate fix): Use a classic PAT with the required scopes instead of
+  a fine-grained PAT. Classic PATs are not subject to the fine-grained restriction.
+
+  Option 2 (Organization change — requires admin): Have an org admin update the
+  organization's PAT policy to allow fine-grained PATs:
+    Settings → Developer Settings → Personal access token policy
+    → Allow fine-grained personal access tokens
+    → (optionally require approval for each token)
+
+  Option 3 (Recommended long-term): Replace the PAT with a GitHub App token.
+  GitHub App tokens are not subject to org-level PAT restrictions and provide
+  better auditability and short-lived credentials.
+fix_code:
+  - language: yaml
+    label: "Use classic PAT (immediate workaround)"
+    code: |
+      # Replace the fine-grained PAT secret with a classic PAT:
+      # GitHub.com > Settings > Developer settings > Personal access tokens > Tokens (classic)
+      # Create new token with required scopes (e.g., repo)
+      # Add to repo secrets as CLASSIC_PAT
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                token: ${{ secrets.CLASSIC_PAT }}
+                # Classic PATs work even when org blocks fine-grained PATs
+  - language: yaml
+    label: "Use a GitHub App token (recommended)"
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Generate GitHub App token
+              id: app-token
+              uses: actions/create-github-app-token@v1
+              with:
+                app-id: ${{ vars.APP_ID }}
+                private-key: ${{ secrets.APP_PRIVATE_KEY }}
+                owner: ${{ github.repository_owner }}
+              # GitHub App tokens bypass org-level PAT restrictions entirely
+
+            - uses: actions/checkout@v4
+              with:
+                token: ${{ steps.app-token.outputs.token }}
+prevention:
+  - "Before using fine-grained PATs for org repositories, verify the org allows them via Settings → Third-party access → Personal access tokens."
+  - "Document the org's PAT policy in your CI/onboarding docs so contributors know which token types are accepted."
+  - "Prefer GitHub App tokens over any PAT type — they are not subject to PAT restriction policies and provide short-lived, auditable credentials."
+  - "When a PAT fails with 403, check if the error message contains 'fine-grained' before debugging scopes — the token type itself may be blocked."
+docs:
+  - url: "https://docs.github.com/en/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization"
+    label: "Setting a PAT policy for your organization"
+  - url: "https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens"
+    label: "Managing personal access tokens"
+  - url: "https://stackoverflow.com/questions/79471500/github-actions-authentication-failed-for-pushing-to-repository"
+    label: "SO: GitHub Actions — Authentication Failed for Pushing to Repository (fine-grained PAT forbidden)"
+  - url: "https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/making-authenticated-api-requests-with-a-github-app-in-a-github-actions-workflow"
+    label: "Using GitHub App tokens in GitHub Actions"

package/errors/permissions-auth/pat-sso-org-not-authorized-checkout-404.yml

@@ -0,0 +1,107 @@
+id: permissions-auth-023
+title: "PAT Fails with 'Not Found' on SSO-Protected Organization Repository"
+category: permissions-auth
+severity: error
+tags:
+  - personal-access-token
+  - saml-sso
+  - organization
+  - checkout
+  - authentication
+patterns:
+  - regex: "Not Found - https://docs\\.github\\.com/rest/repos/repos#get-a-repository"
+    flags: "i"
+  - regex: "fatal: unable to access.*403|Syncing repository.*Not Found"
+    flags: "i"
+  - regex: "could not read Username.*https://github\\.com"
+    flags: "i"
+error_messages:
+  - "Not Found - https://docs.github.com/rest/repos/repos#get-a-repository"
+  - "Retrieving the default branch name"
+  - "  Not Found - https://docs.github.com/rest/repos/repos#get-a-repository"
+  - "Error: Not Found - https://docs.github.com/rest/repos/repos#get-a-repository"
+root_cause: |
+  When a GitHub organization enforces SAML SSO (Single Sign-On), every PAT
+  (Personal Access Token) used to access that organization's resources must be
+  explicitly authorized for the SSO organization — even if the token has all the
+  correct scopes (repo, read:org, etc.).
+
+  A PAT that hasn't been authorized for the SSO org will receive a 404 "Not Found"
+  response when attempting to access org resources via the API or when cloning/
+  checking out a repository. The response is 404 (not 401/403) because GitHub
+  treats an unauthorized SSO request as "resource doesn't exist for this token."
+
+  Common symptoms:
+  - `actions/checkout` fails with "Not Found" on the default branch retrieval step
+  - The PAT works locally in a browser (which has an active SSO session) but fails
+    in GitHub Actions
+  - The token has `repo` scope or `contents: read` permission but still 404s
+
+  Sources: stackoverflow.com/questions/79874764,
+           stackoverflow.com/questions/77957649,
+           GitHub Docs on SAML SSO authorization
+fix: |
+  Authorize the PAT for the SSO organization:
+
+  1. Go to GitHub → Settings → Developer settings → Personal access tokens
+  2. Select the PAT used in the workflow
+  3. Click "Configure SSO" next to the token
+  4. Click "Authorize" next to the target organization
+  5. Complete any SSO prompts
+
+  The PAT is now authorized for that org and will work in Actions workflows.
+
+  For fine-grained PATs: ensure the token's "Resource owner" is the organization
+  (not your personal account) and that the org admin has approved it.
+fix_code:
+  - language: yaml
+    label: "Authorize the PAT for SSO org (no workflow change needed)"
+    code: |
+      # This is a GitHub settings action, not a workflow change.
+      # GitHub.com > Settings > Developer settings > Personal access tokens
+      # > (select token) > Configure SSO > Authorize > (org name)
+      #
+      # After authorizing, your workflow using the PAT will work:
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                repository: my-org/private-repo
+                token: ${{ secrets.MY_ORG_PAT }}
+                # MY_ORG_PAT must have 'repo' scope AND be SSO-authorized for my-org
+  - language: yaml
+    label: "Use a GitHub App token instead (recommended for SSO orgs)"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Generate GitHub App token
+              id: app-token
+              uses: actions/create-github-app-token@v1
+              with:
+                app-id: ${{ vars.APP_ID }}
+                private-key: ${{ secrets.APP_PRIVATE_KEY }}
+                owner: my-org
+                # GitHub App tokens for org installations are not subject to
+                # SAML SSO PAT authorization requirements
+            - uses: actions/checkout@v4
+              with:
+                repository: my-org/private-repo
+                token: ${{ steps.app-token.outputs.token }}
+prevention:
+  - "After creating a new PAT for use with an SSO-enforcing organization, always authorize it via Configure SSO before adding it to Actions secrets."
+  - "Test PAT access locally with `gh auth login --with-token` and `gh repo view my-org/repo` to confirm SSO authorization before using in CI."
+  - "Prefer GitHub App tokens over PATs for organization repositories — they are not subject to SAML SSO authorization requirements."
+  - "Document which secrets require SSO authorization in your repo's CONTRIBUTING or CI documentation to prevent the same issue for new contributors."
+docs:
+  - url: "https://docs.github.com/en/enterprise-cloud@latest/authentication/authenticating-with-saml-single-sign-on/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on"
+    label: "Authorizing a PAT for use with SAML SSO"
+  - url: "https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-saml-single-sign-on-for-your-organization/about-identity-and-access-management-with-saml-single-sign-on"
+    label: "About SAML SSO for organizations"
+  - url: "https://stackoverflow.com/questions/79874764/github-actions-checkout-fails-with-not-found-error-for-sso-protected-enterprise"
+    label: "SO: checkout fails with Not Found for SSO-protected enterprise repo"
+  - url: "https://stackoverflow.com/questions/77957649/repository-not-found-error-while-using-actions-checkoutv4-to-clone-a-private-re"
+    label: "SO: Repository not found error with actions/checkout@v4 on private repo"

package/errors/runner-environment/android-sdk-api37-hash-mismatch.yml

@@ -0,0 +1,97 @@
+id: runner-environment-055
+title: "Android SDK Platform 37 Installed as 'android-37.0' — Builds Fail Looking for 'android-37'"
+category: runner-environment
+severity: error
+tags:
+  - android
+  - android-sdk
+  - gradle
+  - ubuntu-2404
+  - sdk-platform
+  - hash-string
+patterns:
+  - regex: "Failed to find target with hash string 'android-37'"
+    flags: "i"
+  - regex: "Failed to find target.*android-37[^\\d]"
+    flags: "i"
+  - regex: "Could not determine.*dependencies.*android-37[^\\d]"
+    flags: "i"
+  - regex: "platforms/android-37\\.0.*android-37[^\\.]"
+    flags: "i"
+error_messages:
+  - "Failed to find target with hash string 'android-37' in: /usr/local/lib/android/sdk"
+  - "Could not determine the dependencies of task ':app:compileDebugJavaWithJavac'."
+  - "> Failed to find target with hash string 'android-37'"
+root_cause: |
+  On the Ubuntu 24.04 runner image (from approximately image version 20260323), the
+  Android SDK Platform 37 is installed under the directory name `android-37.0` rather
+  than the expected `android-37`. Gradle and the Android Gradle Plugin (AGP) look up
+  platform targets by their hash string (`android-37`), which must exactly match the
+  subdirectory name inside `$ANDROID_SDK_ROOT/platforms/`.
+
+  When `sdkmanager` installs `platforms;android-37.0`, it creates:
+    `/usr/local/lib/android/sdk/platforms/android-37.0/`
+
+  But AGP resolves `compileSdk = 37` (or `compileSdkVersion 37`) to hash string
+  `android-37`, not `android-37.0`. The lookup fails even though the SDK is physically
+  present on the runner (runner-images#13859).
+
+  Root cause in the runner image: the `platforms;android-37.0` package name was published
+  by Google with a `.0` version suffix in the SDK package path, causing a naming
+  inconsistency between the package identifier and the installed directory name expected
+  by build tools.
+fix: |
+  Add a workaround step that creates a symlink from `android-37` → `android-37.0` before
+  the Gradle build. This resolves the hash lookup without any source code changes.
+
+  Alternatively, pin `compileSdk` to 36 (which is installed normally) until the runner
+  image is fixed, or install `platforms;android-37` explicitly via sdkmanager — but note
+  that as of the time of writing the `android-37` (non-.0) package may not yet be
+  published to the official SDK registry.
+fix_code:
+  - language: yaml
+    label: "Symlink workaround — link android-37 to android-37.0 before build"
+    code: |
+      steps:
+        - uses: actions/checkout@v4
+
+        - name: Fix Android SDK 37 directory name mismatch
+          run: |
+            SDK_PLATFORMS="$ANDROID_SDK_ROOT/platforms"
+            if [ -d "$SDK_PLATFORMS/android-37.0" ] && [ ! -d "$SDK_PLATFORMS/android-37" ]; then
+              ln -s "$SDK_PLATFORMS/android-37.0" "$SDK_PLATFORMS/android-37"
+              echo "Symlinked android-37 -> android-37.0"
+            fi
+
+        - name: Build APK
+          run: ./gradlew assembleDebug
+  - language: yaml
+    label: "Pin compileSdk to 36 as temporary workaround"
+    code: |
+      # In app/build.gradle or build.gradle.kts:
+      android {
+          compileSdk = 36   # Use 36 until android-37 symlink issue is resolved
+          # compileSdk = 37  # <- caused 'android-37' hash mismatch
+      }
+  - language: yaml
+    label: "Install android-37 explicitly via sdkmanager"
+    code: |
+      steps:
+        - name: Install Android SDK Platform 37
+          run: |
+            echo "y" | $ANDROID_SDK_ROOT/cmdline-tools/latest/bin/sdkmanager \
+              "platforms;android-37" \
+              "build-tools;37.0.0"
+        - name: Build
+          run: ./gradlew assembleDebug
+prevention:
+  - "When upgrading `compileSdk` to a newly released Android API level, test against ubuntu-24.04 runners in a feature branch first before rolling out to all jobs."
+  - "Subscribe to runner-images releases for `ubuntu-24.04` to catch SDK directory naming changes early."
+  - "Add an explicit `sdkmanager` install step for the exact platform and build-tools version your project requires instead of relying on pre-installed SDKs."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/13859"
+    label: "runner-images#13859 — Ubuntu 24.04 installs API 37 as android-37.0; builds fail looking for android-37"
+  - url: "https://developer.android.com/studio/releases/platforms"
+    label: "Android SDK Platform releases — official platform package naming"
+  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources"
+    label: "GitHub Docs — GitHub-hosted runner software"

package/errors/runner-environment/android-sdk-platforms-v33-removed.yml

@@ -0,0 +1,120 @@
+id: runner-environment-056
+title: "Android SDK Platforms and Build Tools < v34 Removed from Runner Images (Jan 2026)"
+category: runner-environment
+severity: error
+tags:
+  - android
+  - android-sdk
+  - gradle
+  - runner-images
+  - ubuntu-2204
+  - macos-14
+  - windows-2022
+  - compile-sdk
+patterns:
+  - regex: "Failed to find target with hash string 'android-3[0-3]'"
+    flags: "i"
+  - regex: "Failed to find Build Tools revision 3[0-3]\\."
+    flags: "i"
+  - regex: "Build Tools revision.*not installed|not installed.*Build Tools"
+    flags: "i"
+  - regex: "compileSdkVersion.*3[0-3].*not found|SDK Platform.*3[0-3].*not installed"
+    flags: "i"
+error_messages:
+  - "Failed to find target with hash string 'android-33' in: /usr/local/lib/android/sdk"
+  - "Failed to find Build Tools revision 33.0.2"
+  - "SDK Platform '33' is not installed."
+  - "Failed to find target with hash string 'android-32'"
+root_cause: |
+  Starting January 12, 2026, GitHub removed pre-installed Android SDK platforms and build
+  tools older than version 34 from the following runner images (runner-images#13469):
+
+  - Ubuntu 22.04
+  - macOS 14 (and macOS 14 Arm64)
+  - Windows Server 2022
+
+  Affected toolchain components:
+  - SDK Platforms: android-33 and older (Android 13 / API 33, API 32, etc.)
+  - Build Tools: versions older than 34.0.0
+
+  The removal was motivated by freeing up disk space. Projects that reference
+  `compileSdkVersion 33` (or lower) in their Gradle configuration, or that install
+  specific old build-tools versions, fail immediately because the expected directories are
+  absent from `$ANDROID_SDK_ROOT/platforms/` and `$ANDROID_SDK_ROOT/build-tools/`.
+
+  Note: Ubuntu 24.04, macOS 15, and Windows Server 2025 images were not affected because
+  they never carried the older SDK platforms.
+fix: |
+  Option A — Upgrade compileSdk and targetSdk to 34 or higher (recommended):
+    Updating to a supported API level removes the dependency on removed SDK packages.
+    API 34 (Android 14) is widely available and well-tested.
+
+  Option B — Install the required SDK platform at runtime:
+    Use `sdkmanager` in a workflow step to download and install the exact platform and
+    build tools version before the Gradle build runs. This adds ~30-60 seconds to the job.
+fix_code:
+  - language: yaml
+    label: "Upgrade compileSdk to 35 (recommended long-term fix)"
+    code: |
+      # In app/build.gradle.kts:
+      android {
+          compileSdk = 35        # upgraded from 33 — no SDK install step needed
+          targetSdk = 35
+          minSdk = 21
+      }
+  - language: yaml
+    label: "Install removed SDK platform at runtime (keeps compileSdk 33)"
+    code: |
+      steps:
+        - uses: actions/checkout@v4
+
+        - name: Install Android SDK Platform 33 and Build Tools 33.0.2
+          run: |
+            echo "y" | $ANDROID_SDK_ROOT/cmdline-tools/latest/bin/sdkmanager \
+              "platforms;android-33" \
+              "build-tools;33.0.2"
+
+        - name: Build
+          run: ./gradlew assembleDebug
+  - language: yaml
+    label: "Install SDK using android-actions/setup-android"
+    code: |
+      steps:
+        - uses: actions/checkout@v4
+        - uses: android-actions/setup-android@v3
+          with:
+            packages: >
+              platforms;android-33
+              build-tools;33.0.2
+        - run: ./gradlew assembleRelease
+  - language: yaml
+    label: "Matrix build: validate migration to newer API level"
+    code: |
+      jobs:
+        build:
+          strategy:
+            matrix:
+              compile-sdk: [33, 34, 35]
+          runs-on: ubuntu-22.04
+          steps:
+            - uses: actions/checkout@v4
+            - name: Install required SDK (only needed for API < 34)
+              if: matrix.compile-sdk < 34
+              run: |
+                echo "y" | $ANDROID_SDK_ROOT/cmdline-tools/latest/bin/sdkmanager \
+                  "platforms;android-${{ matrix.compile-sdk }}"
+            - run: ./gradlew assembleDebug
+              env:
+                COMPILE_SDK_VERSION: ${{ matrix.compile-sdk }}
+prevention:
+  - "Target `compileSdk` and `targetSdk` at API 34 or higher; Google Play requires API 35+ for new app submissions as of August 2025."
+  - "Audit your `build.gradle` files for hard-coded old `compileSdkVersion` values and migrate proactively during the announcement window."
+  - "Subscribe to runner-images GitHub Issues to see SDK removal announcements before they hit production workflows."
+  - "Add an explicit `sdkmanager` install step for any SDK version your build requires so the workflow is portable regardless of what's pre-installed."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/13469"
+    label: "runner-images#13469 — Android SDK platforms and build tools < v34 removed on Jan 12, 2026"
+  - url: "https://developer.android.com/tools/sdkmanager"
+    label: "Android Docs — sdkmanager command-line tool"
+  - url: "https://developer.android.com/google/play/requirements/target-sdk"
+    label: "Google Play — target API level requirements"

package/errors/runner-environment/docker-buildx-matrix-platform-tag-overwrite.yml

@@ -0,0 +1,143 @@
+id: runner-environment-052
+title: "Docker Multi-Platform Build Uses Matrix per Platform — Tags Overwrite Each Other"
+category: runner-environment
+severity: silent-failure
+tags:
+  - docker
+  - buildx
+  - multi-platform
+  - matrix
+  - ghcr
+  - manifest
+patterns:
+  - regex: "no matching manifest for .* in the manifest list entries"
+    flags: "i"
+  - regex: "image operating system .* does not match host operating system"
+    flags: "i"
+  - regex: "manifest unknown"
+    flags: "i"
+error_messages:
+  - "no matching manifest for linux/amd64 in the manifest list entries"
+  - "Error response from daemon: manifest unknown: manifest unknown"
+  - "image operating system \"linux\" does not match host operating system \"linux\""
+root_cause: |
+  A common pattern for multi-platform Docker images in GitHub Actions is to use
+  `strategy.matrix` with one platform per job and `docker/build-push-action` in
+  each job. This approach is incorrect: each job pushes a single-platform image
+  to the same tag, and each push *overwrites* the previous one. There is no merging
+  of single-platform images into a multi-platform manifest list.
+
+  After all matrix jobs complete, the tag only contains the image from the last
+  job to push — typically whichever platform finished last. All other platforms are
+  silently lost.
+
+  When another host tries to pull the image on a different architecture (e.g.,
+  linux/arm64 pulling after linux/amd64 was last to write), they receive:
+  "no matching manifest for linux/arm64 in the manifest list entries"
+
+  The workflow itself reports success — all matrix jobs push successfully. The
+  failure is silent until image consumers on other architectures try to pull.
+
+  Sources: stackoverflow.com/questions/79315376,
+           Docker multi-platform build documentation
+fix: |
+  Use a single `docker/build-push-action` step with comma-separated platforms
+  instead of a matrix. Docker Buildx handles building all platforms in one job
+  and pushes a proper multi-platform manifest list.
+
+  If you need dedicated builders for each platform (e.g., native ARM runners),
+  use the "bake + merge manifest" pattern with `docker buildx imagetools create`
+  to merge per-platform digests into a single manifest after all builds complete.
+fix_code:
+  - language: yaml
+    label: "Single buildx job with comma-separated platforms (recommended)"
+    code: |
+      jobs:
+        build-and-push:
+          runs-on: ubuntu-latest
+          permissions:
+            packages: write
+            contents: read
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Set up QEMU
+              uses: docker/setup-qemu-action@v3
+
+            - name: Set up Docker Buildx
+              uses: docker/setup-buildx-action@v3
+
+            - name: Login to GHCR
+              uses: docker/login-action@v3
+              with:
+                registry: ghcr.io
+                username: ${{ github.actor }}
+                password: ${{ secrets.GITHUB_TOKEN }}
+
+            - name: Build and push multi-platform image
+              uses: docker/build-push-action@v6
+              with:
+                push: true
+                platforms: linux/amd64,linux/arm64,linux/arm/v7
+                # All platforms in one step → proper manifest list created
+                tags: ghcr.io/${{ github.repository_owner }}/myapp:latest
+  - language: yaml
+    label: "Native-builder pattern: build per platform, merge manifest (advanced)"
+    code: |
+      # Build per-platform in parallel jobs, then merge into a manifest list
+      jobs:
+        build:
+          strategy:
+            matrix:
+              include:
+                - platform: linux/amd64
+                  runner: ubuntu-latest
+                - platform: linux/arm64
+                  runner: ubuntu-24.04-arm  # native ARM runner
+          runs-on: ${{ matrix.runner }}
+          outputs:
+            digest: ${{ steps.push.outputs.digest }}
+          steps:
+            - uses: actions/checkout@v4
+            - uses: docker/setup-buildx-action@v3
+            - uses: docker/login-action@v3
+              with:
+                registry: ghcr.io
+                username: ${{ github.actor }}
+                password: ${{ secrets.GITHUB_TOKEN }}
+            - name: Build and push by digest (no tag yet)
+              id: push
+              uses: docker/build-push-action@v6
+              with:
+                push: true
+                platforms: ${{ matrix.platform }}
+                # Push by digest only — do NOT set a tag here
+                outputs: type=image,name=ghcr.io/${{ github.repository_owner }}/myapp,push-by-digest=true,name-canonical=true
+
+        merge:
+          needs: build
+          runs-on: ubuntu-latest
+          steps:
+            - uses: docker/login-action@v3
+              with:
+                registry: ghcr.io
+                username: ${{ github.actor }}
+                password: ${{ secrets.GITHUB_TOKEN }}
+            - name: Create and push multi-platform manifest
+              run: |
+                docker buildx imagetools create \
+                  -t ghcr.io/${{ github.repository_owner }}/myapp:latest \
+                  ${{ needs.build.outputs.digest }}
+                  # Merges per-platform digests into one manifest list
+prevention:
+  - "Never use strategy.matrix to build separate platforms and push to the same tag — each push overwrites the previous."
+  - "Use a single build-push-action step with comma-separated platforms for most multi-platform use cases."
+  - "Validate multi-platform images after push with `docker buildx imagetools inspect ghcr.io/owner/image:tag` to confirm all platforms are present."
+  - "When matrix builds are needed for native performance, use push-by-digest and a fan-in merge job."
+docs:
+  - url: "https://docs.docker.com/build/ci/github-actions/multi-platform/"
+    label: "Docker: Multi-platform image with GitHub Actions"
+  - url: "https://github.com/docker/build-push-action"
+    label: "docker/build-push-action — multi-platform examples"
+  - url: "https://stackoverflow.com/questions/79315376/docker-multiplatform-image-pushed-successfully-to-ghcr-but-pulling-image-result"
+    label: "SO: Docker multiplatform image pushed successfully but pulling results in manifest not found"

package/errors/runner-environment/node24-action-self-hosted-runner-too-old.yml

@@ -0,0 +1,93 @@
+id: runner-environment-053
+title: "Node 24 Action Fails on Self-Hosted Runner — 'using: node24 is not supported'"
+category: runner-environment
+severity: error
+tags:
+  - node24
+  - self-hosted-runner
+  - runner-version
+  - node-runtime
+  - actions-checkout
+  - actions-cache
+patterns:
+  - regex: "'using: node24' is not supported"
+    flags: "i"
+  - regex: "Parameter.*using.*node24.*is not supported"
+    flags: "i"
+  - regex: "node24.*not supported.*use.*node12.*node16.*node20"
+    flags: "i"
+  - regex: "This version of the Actions runner is too old to run node24"
+    flags: "i"
+error_messages:
+  - "Specified argument was out of the range of valid values. (Parameter ''using: node24' is not supported, use 'docker', 'node12', 'node16' or 'node20' instead.')"
+  - "'using: node24' is not supported, use 'docker', 'node12', 'node16' or 'node20' instead."
+root_cause: |
+  GitHub Actions runner v2.327.1 (released July 25, 2025) was the first version to add
+  support for the `node24` runtime. Actions that bumped their major version to run on
+  Node.js 24 (including `actions/checkout@v5`, `actions/cache@v5`,
+  `actions/upload-artifact@v6`, and `actions/setup-node@v5`) specify `using: node24` in
+  their `action.yml`. When one of these actions runs on a self-hosted runner older than
+  v2.327.1, the runner's `ActionManifestManager` throws a `System.ArgumentOutOfRangeException`
+  because it does not recognise `node24` as a valid runtime identifier — it only knows
+  `docker`, `node12`, `node16`, and `node20`.
+
+  Common scenarios:
+  - Bumping a pinned `actions/checkout@v4` → `actions/checkout@v5` without first updating
+    the self-hosted runner.
+  - Relying on automatic runner self-update: runners sometimes auto-update the agent binary
+    but the worker process still runs under the old version, causing a mismatch
+    (actions/runner#4064).
+  - Using Dependabot or Renovate to auto-bump action versions across a repo.
+fix: |
+  Update all self-hosted runners to version 2.327.1 or later before upgrading any action
+  to a version that requires `node24`. Steps:
+
+  1. Download and install the latest runner from:
+     https://github.com/actions/runner/releases/latest
+  2. Verify the version with: `./run.sh --version` (Linux/macOS) or `.\run.cmd --version`
+     (Windows).
+  3. If automatic self-update is enabled but stuck, stop the runner service, delete the
+     cached `_work/_update` directory, and restart — or manually install the new version.
+  4. For containerised runners (ARC, summerwind/actions-runner-dind), update the base image
+     tag to a version that ships runner ≥ 2.327.1.
+
+  If you cannot update the runner immediately, pin the actions back to the last v4/v5
+  compatible release and schedule the runner upgrade.
+fix_code:
+  - language: yaml
+    label: "Pin to node24-compatible action versions — requires runner ≥ 2.327.1"
+    code: |
+      steps:
+        - uses: actions/checkout@v5         # node24 — runner must be ≥ 2.327.1
+        - uses: actions/cache@v5            # node24 — runner must be ≥ 2.327.1
+        - uses: actions/upload-artifact@v6  # node24 — runner must be ≥ 2.327.1
+        - uses: actions/setup-node@v5       # node24 — runner must be ≥ 2.327.1
+  - language: yaml
+    label: "Temporary pin to node20 versions while runner is being updated"
+    code: |
+      steps:
+        - uses: actions/checkout@v4         # still node20, compatible with older runners
+        - uses: actions/cache@v4            # still node20
+        - uses: actions/upload-artifact@v4  # still node20
+        - uses: actions/setup-node@v4       # still node20
+  - language: yaml
+    label: "Verify runner version in workflow (diagnostic)"
+    code: |
+      steps:
+        - name: Print runner version
+          run: echo "Runner version ${{ runner.version }}"
+        # runner.version must be >= 2.327.1 for node24 actions
+prevention:
+  - "Before bumping any action to a node24 major version, check all self-hosted runner versions and update them first."
+  - "Add a minimum runner version check step or GitHub Actions required runner version policy for your organisation."
+  - "Subscribe to runner-images and actions/runner release announcements to learn about node runtime changes in advance."
+  - "For Dependabot/Renovate auto-bumps, add a CI gate that blocks merging action version upgrades until runner compatibility is confirmed."
+docs:
+  - url: "https://github.com/actions/checkout/issues/2240"
+    label: "actions/checkout#2240 — Breaking change with v5: 'using: node24 is not supported' (27 reactions)"
+  - url: "https://github.com/actions/runner/releases/tag/v2.327.1"
+    label: "actions/runner v2.327.1 — First release with Node.js 24 support"
+  - url: "https://github.com/actions/runner/issues/4064"
+    label: "actions/runner#4064 — Auto-update doesn't take node20 → node24 into account, cascading failures"
+  - url: "https://github.blog/changelog/2025-09-19-deprecation-of-node-20-on-github-actions-runners/"
+    label: "GitHub Changelog — Deprecation of Node 20 on GitHub Actions runners"

package/errors/runner-environment/python39-removed-runner-images.yml

@@ -0,0 +1,97 @@
+id: runner-environment-054
+title: "Python 3.9 Removed from Runner Images — Version Not Found in Local Cache"
+category: runner-environment
+severity: error
+tags:
+  - python
+  - python-39
+  - runner-images
+  - toolcache
+  - setup-python
+  - eol
+patterns:
+  - regex: "Version '3\\.9[^']*' was not found in the local cache"
+    flags: "i"
+  - regex: "python.*3\\.9.*not found.*cache|not found.*python.*3\\.9"
+    flags: "i"
+  - regex: "Unable to find python version.*3\\.9"
+    flags: "i"
+  - regex: "Couldn't find a version that satisfies.*python.*3\\.9"
+    flags: "i"
+error_messages:
+  - "Version '3.9.x' was not found in the local cache"
+  - "Unable to find the requested Python version (3.9.x) in the local tool cache"
+  - "Error: Version 3.9 with arch x64 not found"
+root_cause: |
+  Python 3.9 reached end-of-life on October 5, 2025. Starting January 12, 2026, GitHub
+  removed the pre-cached Python 3.9 toolchain from all runner images (ubuntu-22.04,
+  ubuntu-24.04, macOS-14, macOS-15, Windows Server 2022/2025). Additionally, on
+  Windows-based images Python 3.12 replaced 3.9 as the default version
+  (runner-images#13468).
+
+  Workflows are affected when:
+  1. `actions/setup-python` is used with `python-version: '3.9'` without a fallback —
+     the action tries the local toolcache first and fails when the pre-cached entry is gone.
+  2. A workflow assumes the system `python` or `python3` binary is 3.9 on Windows
+     (where it was the previous default).
+  3. A workflow calls `python3.9` directly (e.g. `python3.9 manage.py …`) without
+     installing it first.
+fix: |
+  Option A — Install Python 3.9 at runtime via actions/setup-python (recommended):
+    Add `actions/setup-python` with a specific version. The action will download and
+    install Python 3.9 from the GitHub-managed toolcache CDN even though it is no longer
+    pre-cached on the image.
+
+  Option B — Migrate to a supported Python version:
+    Python 3.9 is EOL. Migrate to Python 3.11, 3.12, or 3.13 to benefit from active
+    security patches. Test your dependency set against the newer version.
+
+  Option C — Pin a newer default for Windows:
+    If you relied on the system default `python` being 3.9 on Windows, add an explicit
+    `actions/setup-python` step to pin the exact version you need.
+fix_code:
+  - language: yaml
+    label: "Install Python 3.9 at runtime (works despite toolcache removal)"
+    code: |
+      steps:
+        - uses: actions/checkout@v4
+        - uses: actions/setup-python@v5
+          with:
+            python-version: '3.9'   # downloaded from CDN — no longer pre-cached
+        - run: python --version
+  - language: yaml
+    label: "Migrate to Python 3.12 (recommended — actively supported)"
+    code: |
+      steps:
+        - uses: actions/checkout@v4
+        - uses: actions/setup-python@v5
+          with:
+            python-version: '3.12'
+        - run: pip install -r requirements.txt
+  - language: yaml
+    label: "Matrix across multiple Python versions"
+    code: |
+      jobs:
+        test:
+          strategy:
+            matrix:
+              python-version: ['3.11', '3.12', '3.13']
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-python@v5
+              with:
+                python-version: ${{ matrix.python-version }}
+            - run: pip install -r requirements.txt && pytest
+prevention:
+  - "Always use `actions/setup-python` with an explicit `python-version` — never rely on the system pre-cached version."
+  - "Subscribe to runner-images EOL announcements to plan Python version migrations before removal dates."
+  - "Add Python version to `.python-version` or `pyproject.toml` and let `actions/setup-python` read it via `python-version-file`."
+  - "Avoid hard-coding EOL Python versions; use `~3.12` or `>=3.11` range specifiers where the toolchain supports them."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/13468"
+    label: "runner-images#13468 — Python 3.9 removed; Python 3.12 becomes default on Windows (Jan 12, 2026)"
+  - url: "https://github.com/actions/setup-python"
+    label: "actions/setup-python — installs any Python version at runtime from CDN"
+  - url: "https://devguide.python.org/versions/"
+    label: "Python Developer's Guide — supported versions and EOL dates"

package/errors/silent-failures/docker-run-pipe-tee-exit-code-zero.yml

@@ -0,0 +1,99 @@
+id: silent-failures-026
+title: "Docker Run Exit Code Masked When Output Is Piped to tee"
+category: silent-failures
+severity: silent-failure
+tags:
+  - docker
+  - exit-code
+  - pipe
+  - tee
+  - bash
+  - pipefail
+patterns:
+  - regex: "docker run.*\\|.*tee"
+    flags: "i"
+  - regex: "PIPESTATUS|pipefail"
+    flags: "i"
+error_messages:
+  - "Pipe status: 0"
+  - "Exit status: 0"
+  - "The command succeeded."
+root_cause: |
+  When a `docker run` command is piped to `tee` for dual-output (file + console),
+  the shell's `$?` variable captures the exit code of the *last command in the
+  pipeline* — which is `tee`. Since `tee` always exits 0 (unless it cannot write
+  to the output file), the workflow step always reports success even when the
+  container process exits with a non-zero code.
+
+  Example:
+    docker run myimage pytest tests/ 2>&1 | tee output.txt
+    echo $?  # Always 0 — tee's exit code, not docker's
+
+  GitHub Actions enables `set -e` and `set -o pipefail` by default for bash steps,
+  but `pipefail` only propagates failures if the pipeline command itself fails.
+  When the output of `docker run` is piped, the runner still sees `tee`'s exit code
+  as the step's result.
+
+  `${PIPESTATUS[0]}` is the bash array of exit codes for each pipeline segment, but
+  it must be captured *immediately* after the pipeline — it is overwritten by the
+  next command.
+
+  Sources: stackoverflow.com/questions/79075923
+fix: |
+  Option 1 (Recommended): Capture the docker exit code via PIPESTATUS immediately
+  after the pipeline, before running any other command.
+
+  Option 2: Run docker without piping, capturing output to a variable first, then
+  echo it and write to file. This avoids the PIPESTATUS problem entirely.
+
+  Option 3: Enable `set -o pipefail` in the step shell (note: GitHub Actions bash
+  steps do NOT enable pipefail by default despite documentation implying otherwise —
+  test explicitly).
+fix_code:
+  - language: yaml
+    label: "Capture docker exit code via PIPESTATUS[0]"
+    code: |
+      - name: Run tests in Docker
+        run: |
+          docker run myimage pytest tests/ 2>&1 | tee output.txt
+          DOCKER_EXIT=${PIPESTATUS[0]}
+          # PIPESTATUS must be captured immediately after the pipeline
+          echo "Docker exit code: $DOCKER_EXIT"
+          if [ "$DOCKER_EXIT" -ne 0 ]; then
+            echo "Tests failed inside container."
+            exit "$DOCKER_EXIT"
+          fi
+  - language: yaml
+    label: "Avoid piping: capture output in variable, then write and echo"
+    code: |
+      - name: Run tests in Docker
+        run: |
+          # Capture output without piping — preserves $? correctly
+          docker_output=$(docker run myimage pytest tests/ 2>&1)
+          DOCKER_EXIT=$?
+          echo "$docker_output"          # Show in Actions log
+          echo "$docker_output" > output.txt  # Also write to file
+          if [ "$DOCKER_EXIT" -ne 0 ]; then
+            echo "Tests failed (exit $DOCKER_EXIT)"
+            exit "$DOCKER_EXIT"
+          fi
+  - language: yaml
+    label: "Use process substitution to write to file without a pipeline"
+    code: |
+      - name: Run tests in Docker
+        run: |
+          # tee via process substitution — preserves docker's exit code
+          docker run myimage pytest tests/ 2>&1 > >(tee output.txt)
+          # $? is now docker's exit code, not tee's
+prevention:
+  - "Never check $? after a piped command to determine success — always use ${PIPESTATUS[0]} or avoid piping."
+  - "Add an explicit exit-code check after any docker run step, especially when the step uses | tee or redirections."
+  - "Consider adding `set -o pipefail` at the top of multi-command run steps to catch pipeline failures automatically."
+  - "Test workflows with a deliberately failing container command to confirm the step actually fails as expected."
+docs:
+  - url: "https://www.gnu.org/software/bash/manual/bash.html#index-PIPESTATUS"
+    label: "Bash manual — PIPESTATUS"
+  - url: "https://stackoverflow.com/questions/79075923/how-can-i-get-the-error-codes-in-github-actions-shell-when-a-docker-run-command"
+    label: "SO: Get error codes in github-actions shell when docker run command fails while piping output"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions"
+    label: "GitHub Actions workflow commands"

package/package.json

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