@htekdev/actions-debugger 1.0.23 → 1.0.25

package/errors/known-unsolved/artifact-download-url-unauthenticated-404.yml

@@ -0,0 +1,98 @@
+id: known-unsolved-027
+title: "Artifact Download URLs Require GitHub Authentication (404 for Unauthenticated Users)"
+category: known-unsolved
+severity: limitation
+tags:
+  - upload-artifact
+  - download
+  - authentication
+  - public-access
+  - known-limitation
+patterns:
+  - regex: "artifact.*download.*404|artifact.*not found.*auth"
+    flags: "i"
+  - regex: "artifact.*only.*registered|artifact.*guest.*not found"
+    flags: "i"
+error_messages:
+  - "404 Not Found when downloading artifact URL without a GitHub session"
+  - "Resource not accessible by integration"
+  - "Must have push access to repository to list workflow run artifacts"
+root_cause: |
+  All GitHub Actions artifact download URLs — both the UI links on the Actions tab and the archive
+  URLs returned by the REST API (GET /repos/{owner}/{repo}/actions/artifacts/{artifact_id}/zip)
+  — require GitHub authentication. Unauthenticated visitors to public repositories receive a
+  404 Not Found response regardless of the artifact's age or the repository's visibility.
+
+  This was not always the case. Prior to a GitHub platform change (around late 2020), direct
+  artifact archive URLs were publicly accessible without a GitHub account. The change was made
+  without a formal deprecation announcement, breaking projects that distributed nightly builds
+  or pre-release binaries via artifact URLs linked from documentation or release pages.
+
+  The REST API endpoint for listing artifacts (GET /repos/{owner}/{repo}/actions/artifacts)
+  also requires authentication, preventing anonymous services from discovering or linking
+  current artifact URLs.
+
+  185 reactions on actions/upload-artifact#51 (open since Feb 2020).
+fix: |
+  There is no way to make GitHub Actions artifacts publicly accessible without authentication.
+
+  Alternatives for distributing build outputs to unauthenticated users:
+  1. GitHub Releases — release assets attached via `softprops/action-gh-release` are publicly
+     downloadable without a GitHub account.
+  2. GitHub Pages — deploy build outputs as static files; pages are publicly accessible.
+  3. External storage (S3, GCS, Azure Blob Storage) — upload artifacts to a public bucket
+     and provide a stable URL.
+  4. nightly.link proxy — a free service that fetches artifacts via GitHub App auth and
+     provides a public redirect URL. URL format:
+     https://nightly.link/{owner}/{repo}/workflows/{workflow}/{branch}/{artifact-name}.zip
+fix_code:
+  - language: yaml
+    label: "Alternative: publish as GitHub Release asset (publicly accessible)"
+    code: |
+      jobs:
+        build-and-release:
+          runs-on: ubuntu-latest
+          permissions:
+            contents: write
+          steps:
+            - uses: actions/checkout@v4
+            - run: ./build.sh -o dist/output.zip
+
+            # Release assets are publicly downloadable without GitHub login
+            - uses: softprops/action-gh-release@v2
+              with:
+                tag_name: nightly-${{ github.run_number }}
+                files: dist/output.zip
+                prerelease: true
+
+  - language: yaml
+    label: "Alternative: deploy to GitHub Pages (publicly accessible static files)"
+    code: |
+      jobs:
+        deploy-pages:
+          runs-on: ubuntu-latest
+          permissions:
+            pages: write
+            id-token: write
+          environment:
+            name: github-pages
+          steps:
+            - uses: actions/checkout@v4
+            - run: ./build.sh -o ./public
+
+            - uses: actions/upload-pages-artifact@v3
+              with:
+                path: ./public
+            - uses: actions/deploy-pages@v4
+prevention:
+  - "Never publish artifact download URLs as public links — they are always authentication-gated."
+  - "For public distribution of build outputs, use GitHub Releases, GitHub Pages, or an external CDN."
+  - "Use nightly.link for zero-config public access to the latest artifact in open-source projects."
+  - "Document the authentication requirement in README when directing contributors to artifacts."
+docs:
+  - url: "https://github.com/actions/upload-artifact/issues/51"
+    label: "actions/upload-artifact #51 — Artifact URLs require GitHub account (185 reactions)"
+  - url: "https://nightly.link"
+    label: "nightly.link — Public proxy for GitHub Actions artifacts"
+  - url: "https://docs.github.com/en/rest/actions/artifacts"
+    label: "GitHub REST API — Actions Artifacts (requires auth)"

package/errors/known-unsolved/checkout-v6-credentials-docker-run-manual.yml

@@ -0,0 +1,105 @@
+id: known-unsolved-024
+title: "checkout@v6 Git Credentials Inaccessible Inside Manually Invoked Docker Containers"
+category: known-unsolved
+severity: error
+tags:
+  - checkout
+  - docker
+  - credentials
+  - git-auth
+  - includeif
+  - v6
+patterns:
+  - regex: "fatal: could not read Username for.*No such device or address"
+    flags: "i"
+  - regex: "fatal: Authentication failed for.*github\\.com"
+    flags: "i"
+  - regex: "includeIf\\.gitdir.*git-credentials.*config"
+    flags: "i"
+error_messages:
+  - "fatal: could not read Username for 'https://github.com': No such device or address"
+  - "fatal: Authentication failed for 'https://github.com/org/repo.git'"
+  - "remote: Repository not found."
+root_cause: |
+  actions/checkout@v6 changed the credential persistence mechanism from HTTP Authorization
+  headers written directly into .git/config (the v5 approach) to path-based includeIf.gitdir
+  directives that reference a credentials file stored in $RUNNER_TEMP.
+
+  This mechanism works for GitHub-managed Docker container actions (using: docker), where
+  the runner automatically mounts $RUNNER_TEMP into the container as /github/runner_temp
+  and configures paths to match. However, it breaks for any workflow step that runs its own
+  docker run commands or scripts that spin up Docker containers manually, because:
+
+  1. The $RUNNER_TEMP directory is not mounted into the custom container.
+  2. Even if mounted, the includeIf.gitdir path condition requires the workspace to be
+     mounted at /github/workspace for the condition to evaluate as true.
+  3. Any docker run at a non-standard path will not satisfy the gitdir condition even if
+     the credentials file is accessible.
+
+  Any workflow step that runs docker run outside of a formal Docker action and then performs
+  authenticated repository operations (fetch, clone, publish) inside that container will
+  fail to authenticate, even with persist-credentials: true.
+
+  As of June 2026, a fix is in progress upstream (switching from includeIf.gitdir to
+  include.path would eliminate the path-matching requirement) but not yet released.
+  No fully clean universal workaround exists.
+  Reported in actions/checkout#2359 (12 reactions, open Jan 2026).
+fix: |
+  No complete fix available until checkout releases an updated credential mechanism.
+
+  Option 1 (recommended until fix released): Pin to actions/checkout@v5.
+  v5 uses HTTP Authorization headers written directly into .git/config, visible inside any
+  Docker container that mounts the workspace. No path-based includeIf is involved.
+
+  Option 2: Mount RUNNER_TEMP at the expected path inside docker run.
+  Add -v "$RUNNER_TEMP:/github/runner_temp" to the docker run command AND mount the
+  workspace at /github/workspace. Both mounts are required simultaneously.
+
+  Option 3: Pass the token explicitly to the container via environment variable.
+  Set the GitHub token as an env variable and configure the credential helper inside
+  the container entrypoint to use it via the token-embedded remote URL.
+fix_code:
+  - language: yaml
+    label: "Option 1: Pin to checkout@v5 (recommended until upstream fix)"
+    code: |
+      - name: Checkout repository
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+  - language: yaml
+    label: "Option 2: Mount RUNNER_TEMP and workspace at expected paths"
+    code: |
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          persist-credentials: true
+      - name: Run docker with credentials accessible
+        run: |
+          docker run \
+            -v "$GITHUB_WORKSPACE:/github/workspace" \
+            -v "$RUNNER_TEMP:/github/runner_temp" \
+            -w /github/workspace \
+            my-image:latest ./scripts/build.sh
+  - language: yaml
+    label: "Option 3: Pass token to container entrypoint"
+    code: |
+      - name: Run docker with explicit token
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          docker run -e GH_TOKEN="${GH_TOKEN}" my-image:latest ./scripts/release.sh
+prevention:
+  - "Do not upgrade to checkout@v6 if your workflow contains manual docker run steps that perform authenticated repository operations inside the container."
+  - "Use formal Docker container actions (using: docker in action.yml) instead of manual docker run steps when repository operations inside containers are needed."
+  - "Pin checkout to an explicit version and use Dependabot/Renovate to control upgrade timing."
+  - "Track actions/checkout#2359 for the upstream fix when released."
+docs:
+  - url: "https://github.com/actions/checkout/issues/2359"
+    label: "actions/checkout#2359 — checkout@v6 credentials broken with Docker container actions (Jan 2026)"
+  - url: "https://github.com/actions/checkout/issues/2386"
+    label: "actions/checkout#2386 — related Docker credential issue"
+  - url: "https://github.com/actions/checkout/releases/tag/v6.0.0"
+    label: "checkout v6.0.0 release notes — credential mechanism change"
+  - url: "https://docs.github.com/en/actions/sharing-automations/creating-actions/creating-a-docker-container-action"
+    label: "Creating a Docker container action"

package/errors/known-unsolved/concurrency-groups-repo-scoped-only.yml

@@ -0,0 +1,138 @@
+id: known-unsolved-023
+title: "Concurrency Groups Are Repository-Scoped — Cannot Synchronize Workflows Across Repositories"
+category: known-unsolved
+severity: limitation
+tags:
+  - concurrency
+  - cross-repository
+  - scoping
+  - deployment
+  - mutex
+  - known-limit
+  - organization
+patterns:
+  - regex: "concurrency.*cross.?repo|cross.?repo.*concurrency"
+    flags: "i"
+  - regex: "concurrency.*organization|global.*concurrency|multi.?repo.*concurrency"
+    flags: "i"
+  - regex: "concurrency only works within a single repository"
+    flags: "i"
+error_messages:
+  - "GitHub Actions concurrency only works within a single repository"
+  - "Concurrency groups cannot be shared across repositories — identical group names in different repos run in parallel"
+root_cause: |
+  GitHub Actions `concurrency:` groups are evaluated strictly within a single repository.
+  Two workflows in different repositories that define identical `concurrency.group` strings
+  (e.g., `group: deploy-production`) run in PARALLEL with no coordination — the group
+  name has no cross-repository meaning.
+
+  This is a hard platform-level scope boundary. GitHub's concurrency implementation stores
+  group membership state per-repository, so there is no shared namespace between repos.
+
+  Common scenarios where this surprises teams:
+  - Multiple application repos deploying to a shared staging/production environment
+  - A monorepo split into microservice repos that must not deploy simultaneously
+  - Platform teams providing reusable deploy workflows called from many repos
+  - Organizations trying to limit total simultaneous cloud deployments across a fleet
+  - Trying to prevent two repos from running the same database migration at once
+
+  The behavior is counterintuitive because the same concurrency group string CAN
+  coordinate same-repo workflows — so teams naturally assume it works cross-repo too.
+
+  Source: Stack Overflow #79690697 (Make workflow run sequentially for reusable workflow
+  — accepted answer explicitly states: "GitHub Actions' concurrency only works within
+  a single repository")
+  Source: ben-z/gh-action-mutex (community workaround for cross-repo mutex, 500+ stars)
+  Source: GitHub Actions docs (concurrency group scope is per-repository)
+fix: |
+  There is no native GitHub Actions concurrency primitive that works cross-repository.
+  Use one of these architectural workarounds:
+
+  Workaround 1 — Orchestrator repository with repository_dispatch (recommended):
+    Create a central orchestrator repo. Each application repo sends a
+    `repository_dispatch` event to the orchestrator. The orchestrator runs the shared
+    workflow sequentially using its own concurrency group (single-repo scope is fine
+    here because all dispatch events arrive at one repo).
+
+  Workaround 2 — External mutex via ben-z/gh-action-mutex:
+    Uses a dedicated lock repository's branch as a distributed mutex. Works across
+    repos because the lock state lives in one shared repository.
+
+  Workaround 3 — Environment deployment protection with single-slot reviewers:
+    A deployment environment with required reviewers can throttle approval-gated
+    deployments. Multiple jobs can still enter "waiting" simultaneously, but the
+    gate prevents concurrent execution if reviewers approve only one at a time.
+
+  Workaround 4 — External coordination service (Redis, DynamoDB, Azure Service Bus):
+    For production systems at scale, use a lock/queue service all workflows can reach.
+    Requires infrastructure management but provides the most reliable behavior.
+fix_code:
+  - language: yaml
+    label: "Orchestrator pattern: all repos dispatch to a central repo that serializes deploys"
+    code: |
+      # In each application repo — sends dispatch to orchestrator
+      name: Trigger Orchestrated Deploy
+      on:
+        push:
+          branches: [main]
+      jobs:
+        dispatch:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Dispatch to orchestrator
+              run: |
+                gh api /repos/myorg/deploy-orchestrator/dispatches \
+                  --method POST \
+                  -F event_type=deploy \
+                  -F client_payload[repo]="${{ github.repository }}" \
+                  -F client_payload[sha]="${{ github.sha }}"
+              env:
+                GH_TOKEN: ${{ secrets.ORCHESTRATOR_DISPATCH_PAT }}
+
+      ---
+      # In deploy-orchestrator repo — single-repo concurrency works correctly here
+      name: Orchestrated Deploy
+      on:
+        repository_dispatch:
+          types: [deploy]
+      concurrency:
+        group: deploy-production   # Scoped to orchestrator repo — works as intended
+        cancel-in-progress: false  # Queue all deployments; never skip one
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - run: |
+                echo "Deploying ${{ github.event.client_payload.repo }} @ ${{ github.event.client_payload.sha }}"
+                # ... deploy logic ...
+
+  - language: yaml
+    label: "External mutex using ben-z/gh-action-mutex for cross-repo locking"
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Acquire cross-repo deployment lock
+              uses: ben-z/gh-action-mutex@v1.0-alpha-7
+              with:
+                branch: mutex-deploy-production   # Branch in the shared lock repo
+                repo-token: ${{ secrets.MUTEX_REPO_PAT }}
+                repository: myorg/locks           # Dedicated lock repository
+
+            - name: Deploy
+              run: ./deploy.sh
+
+            # Lock is automatically released when the job completes (success or failure)
+prevention:
+  - "Do not assume identical concurrency group names coordinate across repositories — they have no cross-repo effect."
+  - "Design cross-repo deployment sequencing with an explicit architecture before scaling to multiple repos."
+  - "Document the serialization mechanism in your runbooks — this is a common architecture surprise for new team members."
+  - "Prefer a single orchestrator repo pattern from the start when cross-repo ordering is a requirement."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/using-concurrency"
+    label: "GitHub Docs: Using concurrency in GitHub Actions (repo-scoped)"
+  - url: "https://stackoverflow.com/questions/79690697/make-workflow-run-sequentially-allowing-one-job-run-at-a-time-for-github-action-reusable-workflow"
+    label: "Stack Overflow #79690697: Cross-repo sequential GitHub Actions execution"
+  - url: "https://github.com/ben-z/gh-action-mutex"
+    label: "ben-z/gh-action-mutex — cross-repo mutex via shared lock repository"

package/errors/known-unsolved/environment-deployment-false-custom-protection.yml

@@ -0,0 +1,93 @@
+id: known-unsolved-029
+title: "deployment:false environment key incompatible with custom deployment protection rules"
+category: known-unsolved
+severity: limitation
+tags:
+  - environment
+  - deployment
+  - protection-rules
+  - custom-deployment-protection
+  - no-fix
+
+patterns:
+  - regex: "You cannot (use|disable) deployment.*custom deployment protection"
+    flags: "i"
+  - regex: "deployment: false.*is not supported.*protection rule"
+    flags: "i"
+
+error_messages:
+  - "You cannot use deployment: false when a custom deployment protection rule is configured for this environment."
+  - "Environments with custom deployment protection rules require automatic deployment tracking. Remove deployment: false to proceed."
+
+root_cause: |
+  GitHub Actions added deployment: false as a new key for environments in March 2026
+  (changelog 2026-03-19). This key lets workflows use environment secrets and variables
+  without creating a GitHub Deployment record, which was a long-requested feature for
+  teams who want secrets management without polluting the Deployments tab.
+
+  However, the deployment: false key is fundamentally incompatible with custom deployment
+  protection rules. Custom deployment protection rules (third-party apps registered via
+  the GitHub API to gate deployments) rely on GitHub Deployment events being created —
+  the protection rule callback fires when a deployment is created, approves or rejects it,
+  and the workflow proceeds based on the response.
+
+  When deployment: false is set, no Deployment record is created, so there is no event
+  to trigger the custom protection rule callback. GitHub therefore blocks the combination
+  entirely rather than silently skipping the protection rule check, which could create
+  a security bypass.
+
+  This is a platform-level design constraint with no workaround. Teams that need custom
+  deployment protection rules cannot use deployment: false and must keep auto-deployment
+  enabled.
+
+fix: |
+  There is no workaround. If your environment uses a custom deployment protection rule
+  (a third-party app that approves or rejects deployments), you cannot use deployment: false.
+
+  Options:
+  1. Remove the custom deployment protection rule if it is no longer needed, then use
+     deployment: false to stop creating Deployment records.
+  2. Keep auto-deployment enabled (omit deployment: false) and accept that deployments
+     will appear in the Deployments tab.
+  3. Use a different secrets management strategy (repository secrets, organization secrets,
+     or HashiCorp Vault) if you want to avoid environment-scoped secrets entirely.
+
+fix_code:
+  - language: yaml
+    label: "Valid: deployment:false without custom protection rules"
+    code: |
+      # Works only when the environment has NO custom deployment protection rules
+      jobs:
+        deploy:
+          environment:
+            name: staging
+            deployment: false   # Suppresses Deployment record creation
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Using ${{ secrets.STAGING_API_KEY }} without creating a deployment"
+
+  - language: yaml
+    label: "Required: keep deployment enabled when custom protection rules are configured"
+    code: |
+      # When a custom deployment protection rule (third-party app) is registered
+      # on the environment, omit deployment:false entirely
+      jobs:
+        deploy:
+          environment:
+            name: production   # Has custom protection rule — must create deployment
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Deployment record created; custom protection rule fires and must approve"
+
+prevention:
+  - "Check environment settings in Settings > Environments before adding deployment: false to confirm no custom protection rules are registered."
+  - "Document which environments use custom protection rules so team members know deployment: false is unavailable for those environments."
+  - "If you need both secrets management and no deployment records, consider migrating secrets to organization-level secrets with repository access restrictions."
+
+docs:
+  - url: "https://github.blog/changelog/2026-03-19-github-actions-late-march-2026-updates/"
+    label: "GitHub Changelog 2026-03-19: Environments without auto-deployment (deployment: false)"
+  - url: "https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment#using-an-environment-without-auto-deployment"
+    label: "GitHub Docs: Using an environment without auto-deployment"
+  - url: "https://docs.github.com/en/actions/deployment/protecting-deployments/creating-custom-deployment-protection-rules"
+    label: "GitHub Docs: Creating custom deployment protection rules"

package/errors/known-unsolved/matrix-256-job-limit.yml

@@ -0,0 +1,142 @@
+id: known-unsolved-022
+title: "Job Matrix Hard Limit: Maximum 256 Jobs Per Workflow Run"
+category: known-unsolved
+severity: limitation
+tags:
+  - matrix
+  - strategy
+  - job-limit
+  - scale
+  - known-limit
+  - monorepo
+patterns:
+  - regex: "256 jobs|matrix.*256|256.*matrix"
+    flags: "i"
+  - regex: "Job matrix generate.*more than|maximum.*jobs.*workflow.*run"
+    flags: "i"
+  - regex: "matrix.*maximum.*jobs|generates more than 256"
+    flags: "i"
+error_messages:
+  - "Job matrix generates more than 256 jobs"
+  - "A job matrix can generate a maximum of 256 jobs per workflow run"
+  - "The job was not run because it would exceed the maximum number of jobs in a workflow run"
+root_cause: |
+  GitHub Actions enforces a hard limit of 256 jobs per workflow run for job matrix strategies.
+  This limit applies equally to GitHub-hosted and self-hosted runners and cannot be raised
+  via repository or organization settings.
+
+  The limit is evaluated at workflow run creation time against the total number of matrix
+  job combinations. If the computed combination count exceeds 256, the run is blocked.
+
+  Common matrix combinations that silently approach or exceed the limit:
+    - 3 OS × 4 Node.js versions × 22 packages     = 264 jobs  ❌
+    - 4 cloud regions × 4 environments × 17 services = 272 jobs  ❌
+    - 5 browsers × 4 OS × 13 test shards           = 260 jobs  ❌
+
+  This is a long-standing documented constraint. As of the GitHub Actions limits page,
+  the 256-job cap has not been increased and no per-organization override is available.
+
+  Practical impact grows over time: monorepos and test suites that start within the limit
+  gradually approach it as services and configuration dimensions are added, with no
+  warning until a push suddenly fails workflow creation.
+
+  Source: GitHub Docs — Usage limits (256 jobs / workflow run)
+  Source: cloudposse/github-action-matrix-extended (widely-used community workaround)
+  Source: huggingface/transformers PR#28773 (real-world 2-level split at scale)
+fix: |
+  There is no way to raise the 256-job limit via settings. Use one of these workarounds:
+
+  Workaround 1 — Nested matrix via reusable workflows (extends limit to 256² = 65,536):
+    Split work into "slices" at the top-level matrix (up to 256 slices), then call a
+    reusable workflow that runs its own matrix (up to 256 jobs per slice). Each slice
+    × jobs combination stays within the per-run limit.
+
+  Workaround 2 — `github-action-matrix-extended` by cloudposse:
+    Automates the nested slice pattern and supports up to 3 levels (256³ theoretical max).
+    Outputs JSON structure consumed by nested matrix strategy calls.
+
+  Workaround 3 — Path-change filtering via `dorny/paths-filter`:
+    Only generate matrix entries for packages/services that changed in the PR. Keeps
+    CI fast AND well under the job limit for most runs.
+
+  Workaround 4 — Reduce matrix dimensions with `include`/`exclude`:
+    Test all OS on the latest version; test all versions on one OS. Use `exclude:` to
+    prune uncommon OS × version combinations that rarely catch real issues.
+fix_code:
+  - language: yaml
+    label: "Nested reusable workflow split: top-level generates slices, called workflow runs sub-matrix"
+    code: |
+      # outer.yml — up to 256 slices × called workflow's matrix (256 each)
+      name: Test Suite
+      on: [push]
+
+      jobs:
+        generate-slices:
+          runs-on: ubuntu-latest
+          outputs:
+            slices: ${{ steps.gen.outputs.slices }}
+          steps:
+            - id: gen
+              run: |
+                # Generate slice IDs from your service list (split into groups)
+                python3 -c "
+                import json, math
+                services = ['svc-' + str(i) for i in range(300)]
+                slice_size = 10
+                slices = [services[i:i+slice_size] for i in range(0, len(services), slice_size)]
+                print('slices=' + json.dumps([json.dumps(s) for s in slices]))
+                " >> $GITHUB_OUTPUT
+
+        run-slice:
+          needs: generate-slices
+          strategy:
+            matrix:
+              slice: ${{ fromJSON(needs.generate-slices.outputs.slices) }}
+            fail-fast: false
+          uses: ./.github/workflows/test-slice.yml
+          with:
+            services: ${{ matrix.slice }}  # JSON string of services for this slice
+
+  - language: yaml
+    label: "Path filtering: only run matrix jobs for changed packages"
+    code: |
+      jobs:
+        detect-changes:
+          runs-on: ubuntu-latest
+          outputs:
+            matrix: ${{ steps.filter.outputs.changes }}
+          steps:
+            - uses: actions/checkout@v4
+            - id: filter
+              uses: dorny/paths-filter@v3
+              with:
+                filters: |
+                  service-a: ['services/a/**']
+                  service-b: ['services/b/**']
+                  service-c: ['services/c/**']
+                  # ... define one filter per service
+
+        test:
+          needs: detect-changes
+          if: needs.detect-changes.outputs.matrix != '[]'
+          strategy:
+            matrix:
+              service: ${{ fromJSON(needs.detect-changes.outputs.matrix) }}
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm test --workspace=services/${{ matrix.service }}
+prevention:
+  - "Track total matrix job count — when exceeding 200, plan a nested split before hitting the 256 wall."
+  - "Implement path-change filtering early in the project lifecycle to prevent combinatorial explosion."
+  - "Prefer `include`/`exclude` pruning over full combinatorial matrices for OS × version coverage."
+  - "Design your CI architecture with the 256-job ceiling in mind, especially for monorepos."
+docs:
+  - url: "https://docs.github.com/en/actions/administering-github-actions/usage-limits-billing-and-administration#usage-limits"
+    label: "GitHub Docs: Usage limits — Job Matrix (256 jobs per workflow run)"
+  - url: "https://github.com/cloudposse/github-action-matrix-extended"
+    label: "cloudposse/github-action-matrix-extended — nested matrix workaround"
+  - url: "https://github.com/dorny/paths-filter"
+    label: "dorny/paths-filter — change-based matrix filtering"
+  - url: "https://github.com/huggingface/transformers/pull/28773"
+    label: "huggingface/transformers PR#28773: Real-world 2-level matrix split"