@htekdev/actions-debugger 1.0.123 → 1.0.125

package/errors/caching-artifacts/caching-artifacts-073.yml

@@ -0,0 +1,100 @@
+id: caching-artifacts-073
+title: 'actions/upload-artifact and runner blob uploads stall or fail with Bad Request through HTTPS_PROXY — BlobClient missing proxy transport'
+category: caching-artifacts
+severity: error
+tags:
+  - upload-artifact
+  - proxy
+  - https-proxy
+  - azure-blob
+  - self-hosted
+  - blob-client
+  - bad-request
+  - no-proxy
+patterns:
+  - regex: 'Beginning upload of artifact content to blob storage'
+    flags: 'i'
+  - regex: '^Error: Bad Request$'
+    flags: 'im'
+  - regex: 'CONNECT.*blob\.core\.windows\.net.*200.*ALLOWED'
+    flags: 'i'
+  - regex: 'latency=\d+\.\d+s.*stall|stall.*blob.*proxy'
+    flags: 'i'
+error_messages:
+  - 'Beginning upload of artifact content to blob storage'
+  - 'Error: Bad Request'
+  - 'CONNECT productionresultssa*.blob.core.windows.net:443 → status=200 (ALLOWED)'
+root_cause: |
+  When a self-hosted runner is behind an HTTPS forward proxy (HTTPS_PROXY / https_proxy env var),
+  artifact uploads (actions/upload-artifact) and runner-internal uploads (step summaries, job logs,
+  diagnostics) stall or fail with "Error: Bad Request".
+
+  Root cause — two layers, same problem:
+
+  1. @actions/artifact (TypeScript, used by upload-artifact@v4-v7) creates a BlobClient from
+     @azure/storage-blob with only the authenticated URL:
+       new BlobClient(authenticatedUploadURL)
+     No StoragePipelineOptions with proxy configuration are passed. The Azure SDK builds its own
+     HTTP pipeline without proxy transport, so even when HTTPS_PROXY is set in the environment, the
+     SDK does not correctly route the CONNECT tunnel.
+
+  2. The runner's .NET ResultsHttpClient (used for step summaries, logs, diagnostics) also creates a
+     BlobClient without proxy transport options (runner#4351).
+
+  Proxy logs show:
+  - CONNECT tunnel to *.blob.core.windows.net:443 succeeds (HTTP 200 ALLOWED).
+  - Only ~17 KB of the payload is transmitted.
+  - The connection stalls for ~75 seconds and returns a "Bad Request" response.
+  - curl / Python / .NET HttpClient all upload successfully to the same endpoint in <1 second.
+
+  The upload step logs show the artifact upload starting but no "Artifact successfully finalized" line,
+  followed immediately by "Error: Bad Request". The step fails with no further detail.
+fix: |
+  Add the Azure Blob Storage hostname to NO_PROXY to bypass the HTTPS proxy for all blob traffic.
+  The upload URL already contains a time-limited SAS token for authentication, so bypassing the
+  proxy for this destination does not weaken security in most configurations.
+
+  Set NO_PROXY (and no_proxy for case-insensitive tools) to include .blob.core.windows.net.
+
+  This can be set:
+  - In the runner's .env file (persists across all jobs on the runner)
+  - As job-level env: in the workflow (overrides only for that job)
+fix_code:
+  - language: bash
+    label: 'Persist NO_PROXY in the runner service .env file'
+    code: |
+      # Append to the runner .env file (path varies by install location)
+      echo 'NO_PROXY=.blob.core.windows.net' >> /home/runner/actions-runner/.env
+      echo 'no_proxy=.blob.core.windows.net' >> /home/runner/actions-runner/.env
+      # Restart the runner service to pick up the change
+      sudo systemctl restart actions.runner.*.service
+
+  - language: yaml
+    label: 'Set NO_PROXY per workflow job to bypass proxy for artifact uploads'
+    code: |
+      jobs:
+        build:
+          runs-on: [self-hosted]
+          env:
+            # Bypass HTTPS proxy for Azure Blob Storage — prevents BlobClient stall
+            NO_PROXY: '.blob.core.windows.net'
+            no_proxy: '.blob.core.windows.net'
+          steps:
+            - uses: actions/checkout@v4
+            - run: ./build.sh
+            - uses: actions/upload-artifact@v6
+              with:
+                name: build-output
+                path: ./dist/
+prevention:
+  - 'Always test artifact uploads when deploying self-hosted runners behind an HTTPS forward proxy before putting runners into production.'
+  - 'Set NO_PROXY=.blob.core.windows.net in the runner environment before rolling out proxy-configured runners.'
+  - 'Watch proxy logs for 75-second CONNECT stalls to *.blob.core.windows.net as the signature for this issue.'
+  - 'Runner-internal uploads (step summaries, job logs) are also affected — verify both artifact and job-summary visibility when testing.'
+docs:
+  - url: 'https://github.com/actions/toolkit/issues/2377'
+    label: 'actions/toolkit#2377 — @actions/artifact BlobClient missing proxy transport (open)'
+  - url: 'https://github.com/actions/runner/issues/4351'
+    label: 'actions/runner#4351 — runner Azure Blob uploads stall through HTTPS proxy (open)'
+  - url: 'https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners#communication-between-self-hosted-runners-and-github'
+    label: 'GitHub Docs — Self-hosted runner network communication requirements'

package/errors/caching-artifacts/caching-artifacts-074.yml

@@ -0,0 +1,117 @@
+id: caching-artifacts-074
+title: 'actions/cache restore silently treats 429 rate limit as cache miss — no retry, full rebuild forced'
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - cache
+  - rate-limit
+  - 429
+  - restore
+  - cache-miss
+  - rebuild
+  - no-retry
+  - matrix
+patterns:
+  - regex: "You've hit a rate limit"
+    flags: 'i'
+  - regex: 'Failed to restore.*Rate limited.*429'
+    flags: 'i'
+  - regex: 'Failed to GetCacheEntryDownloadURL.*rate limit exceeded'
+    flags: 'i'
+  - regex: 'Too Many Requests.*rate limit exceeded'
+    flags: 'i'
+error_messages:
+  - "Warning: You've hit a rate limit, your rate limit will reset in 18 seconds"
+  - "Warning: Failed to restore: Failed to GetCacheEntryDownloadURL: Rate limited: Failed request: (429) Too Many Requests: rate limit exceeded"
+  - "Cache not found for input keys: ..."
+root_cause: |
+  When the GitHub Actions Cache Service rate-limits a restore request with HTTP 429, the cache
+  action (v4/v5) emits a warning and immediately falls back to "Cache not found" — treating the
+  rate limit as a permanent cache miss rather than a transient error worth retrying.
+
+  The cache action does not:
+  - Retry the restore after the rate-limit reset period (reported in the warning, typically 10-60s).
+  - Fail the step with a hard error so the developer is alerted to an infrastructure issue.
+  - Implement any exponential backoff on the restore path.
+
+  Downstream steps see only "Cache not found for input keys: ..." and proceed to rebuild
+  dependencies from scratch, as if the cache had never been saved. The real cause — a transient
+  429 from the cache service — is easily missed because it appears only as a "Warning:" line
+  mid-step, several lines before the final "Cache not found" output.
+
+  This is most disruptive in large parallel matrix workflows where many concurrent jobs all hit
+  the cache service simultaneously. The cache service rate-limits the burst, every affected job
+  sees a cache miss, and the entire matrix rebuilds from scratch. CI time can multiply by 5-10x
+  with no clear indication in the job summary that the rebuilds were avoidable.
+fix: |
+  While the cache action does not yet implement automatic retry on 429, you can reduce the impact:
+
+  1. Limit max-parallel on matrix strategies to reduce simultaneous cache restore bursts.
+
+  2. Use restore-keys as a fallback: even if the exact-key restore is rate-limited, a prefix
+     match restore-keys request may succeed (different cache entry, different cache service shard).
+
+  3. Stagger cache-heavy workflows using concurrency groups or needs: dependencies so they don't
+     all restore caches at the same second.
+
+  4. Upgrade to the latest cache action — retry logic for 429 is a tracked improvement in
+     actions/cache#1758.
+fix_code:
+  - language: yaml
+    label: 'Use restore-keys as a fallback to reduce full rebuilds on 429 rate limit'
+    code: |
+      - uses: actions/cache@v4
+        id: cache
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
+          # Fallback: match any npm cache for this OS — may succeed even when exact key is rate-limited
+          restore-keys: |
+            ${{ runner.os }}-npm-
+
+  - language: yaml
+    label: 'Limit matrix parallelism to reduce simultaneous cache restore bursts'
+    code: |
+      jobs:
+        build:
+          strategy:
+            matrix:
+              target: [linux-x64, linux-arm64, windows-x64, macos-x64, macos-arm64]
+            # Limit concurrent cache restores — burst of 2 is much less likely to
+            # trigger 429 than a burst of 5 hitting the cache service simultaneously.
+            max-parallel: 2
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/cache@v4
+              with:
+                path: ~/.cache
+                key: ${{ matrix.target }}-deps-${{ hashFiles('**/Cargo.lock') }}
+                restore-keys: |
+                  ${{ matrix.target }}-deps-
+
+  - language: yaml
+    label: 'Stagger cache-restore-heavy jobs using concurrency groups'
+    code: |
+      jobs:
+        restore-cache:
+          concurrency:
+            group: cache-restore-${{ github.ref }}
+            cancel-in-progress: false   # queue, not cancel
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/cache@v4
+              with:
+                path: ~/.gradle/caches
+                key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle*') }}
+prevention:
+  - 'Never run more than ~8 simultaneous cache restore operations in the same repository — the cache service rate limit is per repository.'
+  - 'Always include restore-keys as a fallback so partial cache hits reduce rebuild cost when the exact key is rate-limited.'
+  - 'Watch for the "Warning: You''ve hit a rate limit" log line when investigating unexpectedly slow CI builds.'
+  - 'Treat "Cache not found" as potentially a transient 429, not necessarily a first-run or key-miss, especially in high-parallelism workflows.'
+docs:
+  - url: 'https://github.com/actions/cache/issues/1758'
+    label: 'actions/cache#1758 — Handle rate limit with retry instead of silent cache miss (open)'
+  - url: 'https://github.com/actions/cache#inputs'
+    label: 'actions/cache — restore-keys documentation'
+  - url: 'https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows'
+    label: 'GitHub Docs — Caching dependencies to speed up workflows'

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

@@ -0,0 +1,83 @@
+id: known-unsolved-070
+title: 'ubuntu-24.04 image 20260513.135 breaks WireMock-Spring dynamic port binding in @ConfigurationProperties tests'
+category: known-unsolved
+severity: limitation
+tags:
+  - ubuntu
+  - ubuntu-24.04
+  - spring-boot
+  - wiremock
+  - configurationproperties
+  - regression
+  - java
+  - test
+patterns:
+  - regex: 'foo\.bar\.service\.url=http://localhost:\d+'
+    flags: i
+  - regex: 'http://localhost:9008'
+    flags: i
+  - regex: '@ConfigurationProperties'
+    flags: i
+  - regex: 'wiremock-spring-boot'
+    flags: i
+error_messages:
+  - 'foo.bar.service.url=http://localhost:<random>'
+  - 'The @ConfigurationProperties(prefix = "foo.bar.service") bean ends up bound to the static fallback URL from application-integration-test.yml (http://localhost:9008).'
+  - 'The HTTP client then hits localhost:9008 and the test times out.'
+root_cause: |
+  Starting with Ubuntu 24.04 image `20260513.135`, some Spring Boot integration tests that rely on
+  `wiremock-spring-boot` dynamic port injection regress in GitHub Actions even though the same commit,
+  same JDK, and same test pass on `ubuntu-22.04` and on the older Ubuntu 24.04 image `20260413.86`.
+
+  The observed behavior is:
+  1. WireMock starts and publishes a dynamic property such as `foo.bar.service.url=http://localhost:<port>`.
+  2. The property is visible in logs before the Spring banner.
+  3. The `@ConfigurationProperties` bean still binds to the static fallback value from YAML
+     (`http://localhost:9008`).
+  4. The client calls the fallback URL and the test times out.
+
+  The exact platform-level trigger inside the updated runner image has not been isolated yet. The issue
+  is deterministic on the affected image family, reproducible across multiple repositories, and still open.
+  At the time of writing there is no confirmed runner-side fix or single root cause from GitHub.
+fix: |
+  There is no confirmed upstream fix yet.
+
+  Current workarounds:
+  - pin the workflow to `ubuntu-22.04` while the Ubuntu 24.04 regression is investigated
+  - avoid test setups that rely on `@ConfigurationProperties` picking up a dynamically injected URL
+  - pass the WireMock URL through `@DynamicPropertySource`, a test-specific bean, or direct
+    `Environment` reads closer to the HTTP client wiring
+fix_code:
+  - language: yaml
+    label: 'Pin the test job to Ubuntu 22.04 until the regression is fixed'
+    code: |
+      jobs:
+        integration-tests:
+          runs-on: ubuntu-22.04
+          steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-java@v4
+              with:
+                distribution: temurin
+                java-version: '21'
+            - name: Run integration tests
+              run: ./mvnw test
+
+  - language: java
+    label: 'Inject the dynamic WireMock URL through DynamicPropertySource'
+    code: |
+      @DynamicPropertySource
+      static void registerWireMockProperties(DynamicPropertyRegistry registry) {
+          registry.add("foo.bar.service.url", wireMockServer::baseUrl);
+      }
+prevention:
+  - 'Treat Ubuntu image rollouts as a possible source of Java integration-test regressions, even when your dependencies are unchanged.'
+  - 'Prefer explicit test-time property injection over fallback YAML values when the URL must come from a dynamically started mock server.'
+  - 'Keep a side-by-side `ubuntu-22.04` control job available when debugging new `ubuntu-latest` regressions.'
+docs:
+  - url: 'https://github.com/actions/runner-images/issues/14136'
+    label: 'actions/runner-images#14136 — ubuntu-24.04 image 20260513.135 breaks WireMock-Spring dynamic ports'
+  - url: 'https://docs.spring.io/spring-framework/reference/testing/testcontext-framework/ctx-management/dynamic-property-sources.html'
+    label: 'Spring Docs — @DynamicPropertySource'
+  - url: 'https://github.com/wiremock/wiremock-spring-boot'
+    label: 'wiremock-spring-boot project'

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

@@ -0,0 +1,122 @@
+id: known-unsolved-071
+title: 'Actions cache is repository-scoped — cannot be shared across repositories in the same organization'
+category: known-unsolved
+severity: limitation
+tags:
+  - cache
+  - cross-repo
+  - organization
+  - scope
+  - monorepo
+  - limitation
+  - cache-isolation
+patterns:
+  - regex: 'Cache not found for input keys.*(?:cross-repo|other.repo|shared.cache)'
+    flags: 'i'
+  - regex: 'No cache found.*(?:cross-repo|other.repo|shared)'
+    flags: 'i'
+error_messages:
+  - 'Cache not found for input keys: ...'
+  - 'No cache found'
+root_cause: |
+  The GitHub Actions cache service scopes all cache entries to the repository where they
+  were created. There is no mechanism to share a cache entry between two different
+  repositories, even within the same organization.
+
+  Cache access rules per the GitHub documentation:
+  - A workflow can restore caches created in the current branch, the default branch (main),
+    or (for pull requests) the base branch including base branches of forks.
+  - "Cross-branch" access is supported within the same repository.
+  - There is NO "cross-repository" access — a cache created in `org/repo-a` is
+    completely invisible to workflows running in `org/repo-b`.
+
+  This affects teams who:
+  - Manage related repositories that share build toolchains (e.g., a shared Go module cache
+    across a dozen microservices).
+  - Have split monorepos where a common library is built separately and cached.
+  - Want to cache a slow Docker layer in one repo and reuse it in a deployment repo.
+
+  The underlying reason is cache isolation as a security boundary: allowing cross-repo
+  cache access could leak build artifacts or credentials stored in the cache between
+  unrelated repositories.
+
+  There is no current GitHub Actions native solution for cross-repo cache sharing. The
+  GitHub roadmap has not publicly committed to this feature as of 2026.
+fix: |
+  There is no built-in fix. Workarounds depend on your use case:
+
+  1. Publish shared artifacts to a package registry (GitHub Packages, npm, PyPI, Docker Hub).
+     Instead of caching, version-tag the shared artifact and consume it as a dependency.
+     This is the recommended approach for shared libraries and Docker base images.
+
+  2. Use a self-hosted runner with a shared filesystem. The runner's local disk or a
+     network share can act as a cross-repo cache. Use the `path:` input of actions/cache
+     pointing to a shared mount. Cache hits and misses are managed manually via key files.
+
+  3. Use a third-party caching backend (S3, GCS, Azure Blob, Artifactory) for build
+     artifacts that must be shared. Upload/download via CLI in workflow steps.
+
+  4. Consolidate the related repositories into a single repository (monorepo).
+     All workflows within the same repo can share cache entries.
+fix_code:
+  - language: yaml
+    label: 'Publish shared Docker base image to GHCR instead of caching across repos'
+    code: |
+      # repo-a: builds and publishes the shared base image
+      jobs:
+        publish-base:
+          runs-on: ubuntu-latest
+          permissions:
+            packages: write
+          steps:
+            - uses: actions/checkout@v4
+            - uses: docker/login-action@v3
+              with:
+                registry: ghcr.io
+                username: ${{ github.actor }}
+                password: ${{ secrets.GITHUB_TOKEN }}
+            - uses: docker/build-push-action@v6
+              with:
+                context: ./base-image
+                push: true
+                tags: ghcr.io/${{ github.repository_owner }}/shared-base:latest
+
+      # repo-b: pulls the published image instead of relying on cache
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          container:
+            image: ghcr.io/myorg/shared-base:latest
+            credentials:
+              username: ${{ github.actor }}
+              password: ${{ secrets.GITHUB_TOKEN }}
+          steps:
+            - uses: actions/checkout@v4
+            - run: ./build.sh
+
+  - language: yaml
+    label: 'Self-hosted runner shared-path cache as a cross-repo workaround'
+    code: |
+      # Both repo-a and repo-b workflows — same self-hosted runner, shared disk at /opt/shared-cache
+      jobs:
+        build:
+          runs-on: [self-hosted, linux, shared-cache]
+          steps:
+            - uses: actions/checkout@v4
+            - uses: actions/cache@v4
+              with:
+                path: /opt/shared-cache/gradle
+                # Key is independent of the repo — deliberately shared
+                key: gradle-${{ hashFiles('**/*.gradle*') }}
+              # NOTE: This bypasses GitHub's repo-scope isolation.
+              # Ensure the self-hosted runner pool is trusted and isolated.
+            - run: ./gradlew build
+prevention:
+  - 'Design shared build artifacts as versioned dependencies (packages) from the start — avoids cross-repo cache needs entirely.'
+  - 'For Docker base images shared across repos, publish to a registry and reference by digest, not by mutable tags.'
+  - 'When adopting self-hosted runners for cross-repo cache sharing, audit what secrets and artifacts are accessible to all jobs that share the runner to avoid cross-contamination.'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows#restrictions-for-accessing-a-cache'
+    label: 'GitHub Docs — Cache access restrictions and scoping'
+  - url: 'https://github.com/actions/cache/blob/main/tips-and-workarounds.md'
+    label: 'actions/cache — Tips and workarounds (cross-branch, cross-OS, but not cross-repo)'

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

@@ -0,0 +1,143 @@
+id: known-unsolved-072
+title: 'No parallel steps within a single job — all steps execute sequentially'
+category: known-unsolved
+severity: limitation
+tags:
+  - parallel-steps
+  - sequential
+  - performance
+  - job-structure
+  - limitation
+  - roadmap
+patterns:
+  - regex: 'parallel.*steps.*not.*support|steps.*run.*sequentially'
+    flags: 'i'
+error_messages:
+  - 'steps run sequentially — no native parallel step execution within a single job'
+root_cause: |
+  In GitHub Actions, all steps within a single job execute sequentially in the order they
+  are defined. There is no native syntax to declare that two or more steps within the same
+  job should run concurrently.
+
+  This means:
+  - A job that runs `npm install`, `eslint`, and `jest` must run them one after another,
+    even if `eslint` and `jest` are completely independent and could run simultaneously.
+  - A job that runs two independent API calls, file downloads, or build targets must wait
+    for each to complete before starting the next.
+  - The only way to achieve true parallelism in GitHub Actions is to split work across
+    multiple jobs with `needs:` dependencies — but this requires each job to set up its
+    own runner, check out the repository, restore caches, and install dependencies,
+    adding significant overhead for short tasks.
+
+  This is a long-standing community request. GitHub added it to the public roadmap as
+  "Parallel Steps in GitHub Actions" (github/roadmap#1191, GA milestone, 2025).
+
+  Common workarounds add latency (multiple jobs) or complexity (background processes).
+fix: |
+  There is no built-in fix. Workarounds:
+
+  1. Split parallel work into separate jobs using `needs:` and a matrix strategy.
+     Each job adds runner setup overhead (~15-30s), so this is most effective for
+     tasks that take minutes, not seconds.
+
+  2. Run steps as background shell processes and wait for them with `wait` (bash only).
+     This works for independent shell commands that don't need to write to GITHUB_OUTPUT,
+     GITHUB_ENV, or produce step outputs — those mechanisms are not safe for concurrent use.
+
+  3. Use `make -j N` or `./gradlew --parallel` or similar build-tool parallelism within
+     a single shell step. This parallelizes work inside one run: step without needing
+     multiple GitHub Actions steps.
+
+  4. Run a Docker Compose or docker run --detach to start background services, then
+     use a final step to check results.
+fix_code:
+  - language: yaml
+    label: 'Run independent checks in parallel via separate jobs (preferred for long tasks)'
+    code: |
+      jobs:
+        lint:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-node@v4
+              with:
+                node-version: 22
+                cache: npm
+            - run: npm ci
+            - run: npm run lint
+
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-node@v4
+              with:
+                node-version: 22
+                cache: npm
+            - run: npm ci
+            - run: npm test
+
+        type-check:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-node@v4
+              with:
+                node-version: 22
+                cache: npm
+            - run: npm ci
+            - run: npm run typecheck
+
+        # Final gate job waits for all parallel checks
+        ci-complete:
+          needs: [lint, test, type-check]
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "All checks passed"
+
+  - language: bash
+    label: 'Background shell processes for independent shell commands (same job)'
+    code: |
+      # In a single run: step, launch parallel shell processes and wait for all
+      # WARNING: This pattern does not work with GITHUB_OUTPUT/GITHUB_ENV/GITHUB_STEP_SUMMARY
+      # from the background processes — race conditions corrupt the append-mode files.
+      # Use only for commands that write to their own output files.
+
+      ./fetch-data-source-1.sh > /tmp/source1.json &
+      PID1=$!
+
+      ./fetch-data-source-2.sh > /tmp/source2.json &
+      PID2=$!
+
+      wait $PID1 || { echo "Source 1 fetch failed"; exit 1; }
+      wait $PID2 || { echo "Source 2 fetch failed"; exit 1; }
+
+      echo "Both sources fetched in parallel"
+      ./merge-sources.py /tmp/source1.json /tmp/source2.json
+
+  - language: yaml
+    label: 'Use build tool parallelism inside a single step'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-java@v4
+              with:
+                java-version: 21
+                distribution: temurin
+            # Gradle parallel project execution — all subprojects build concurrently
+            - run: ./gradlew build --parallel --max-workers 4
+prevention:
+  - 'Design CI pipelines with parallel jobs from the start — split lint, test, and build into independent jobs to maximize parallelism today.'
+  - 'Use a shared cache with `actions/cache` to minimize the overhead of repeated `npm ci` / `pip install` across parallel jobs.'
+  - 'Track github/roadmap#1191 for the native parallel steps feature — once released, sequential-step bottlenecks can be eliminated without the multi-job overhead.'
+  - 'For build-tool tasks, always prefer build-native parallelism (`make -j`, `--parallel`, `cargo build --jobs`) over workflow-level workarounds.'
+docs:
+  - url: 'https://github.com/github/roadmap/issues/1191'
+    label: 'github/roadmap#1191 — Parallel Steps in GitHub Actions (GA milestone, open 2025)'
+  - url: 'https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idsteps'
+    label: 'GitHub Docs — jobs.<job_id>.steps (sequential execution model)'
+  - url: 'https://docs.github.com/en/actions/using-jobs/using-a-matrix-for-your-jobs'
+    label: 'GitHub Docs — Using a matrix for parallel jobs as a workaround'