@htekdev/actions-debugger 1.0.124 → 1.0.126

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/concurrency-timing/concurrency-timing-059.yml

@@ -0,0 +1,146 @@
+id: concurrency-timing-059
+title: 'Skipped downstream job satisfies required status check — PR merges despite upstream job failure'
+category: concurrency-timing
+severity: silent-failure
+tags:
+  - needs
+  - skipped
+  - required-status-check
+  - branch-protection
+  - dependency
+  - silent-merge
+  - job-conclusion
+patterns:
+  - regex: 'This job was skipped'
+    flags: 'i'
+  - regex: 'Result: skipped'
+    flags: 'i'
+  - regex: 'needs\.[a-zA-Z0-9_-]+\.result.*skipped'
+    flags: 'i'
+error_messages:
+  - "This job was skipped."
+  - "Skipping this job because a previous job in the chain was skipped or failed."
+root_cause: |
+  GitHub Actions marks a downstream job as `skipped` (not `failure`) when an upstream
+  `needs:` dependency fails or is cancelled and the downstream job has no explicit `if:`
+  condition to handle that state.
+
+  Since April 2023, GitHub's branch protection rules treat a `skipped` check conclusion
+  as **passing** — equivalent to `success` — to support the common "aggregator job"
+  pattern. This means:
+
+  1. `build` job fails.
+  2. `test-results` job (which `needs: [build]`) is marked `skipped`.
+  3. Branch protection rule requires `test-results` to pass.
+  4. GitHub sees conclusion = `skipped` → treats it as satisfied → merge is allowed.
+
+  The PR can be merged even though the `build` step failed. There is no warning or
+  error in the UI — the required check shows a green checkmark (or neutral status)
+  rather than a red blocking indicator.
+
+  This behavior is distinct from:
+  - `cancel-in-progress` cancelling a required check (conclusion = `cancelled`, which
+    blocks merging — a separate issue).
+  - Path-filter causing a workflow to never run (check stays "Expected" / pending).
+  - The general skipped-needs cascade (which documents that downstream jobs skip, but
+    not the branch protection bypass consequence).
+fix: |
+  Add an explicit **catch-all aggregator job** that runs whenever any dependency failed
+  or was cancelled, and exits with a non-zero code:
+
+  ```yaml
+  ci-gate:
+    if: ${{ always() && (contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled')) }}
+    needs: [build, test, lint]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Fail — one or more required jobs did not succeed
+        run: |
+          echo "Required jobs: ${{ toJSON(needs.*.result) }}"
+          exit 1
+  ```
+
+  Set `ci-gate` as the sole required status check in branch protection. This aggregator
+  job only runs (and fails) when something upstream fails. When all upstream jobs
+  succeed, `ci-gate` is `skipped` → satisfies the required check. When any upstream
+  fails, `ci-gate` runs and explicitly fails → blocks the merge.
+
+  Alternatively, use the pattern that always runs the aggregator:
+
+  ```yaml
+  ci-gate:
+    if: always()
+    needs: [build, test, lint]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check all required jobs passed
+        run: |
+          results='${{ toJSON(needs.*.result) }}'
+          if echo "$results" | grep -qE '"failure"|"cancelled"'; then
+            echo "One or more jobs failed: $results"
+            exit 1
+          fi
+          echo "All required jobs passed."
+  ```
+fix_code:
+  - language: yaml
+    label: 'Broken — downstream skipped check silently satisfies branch protection'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - run: ./build.sh   # Fails
+
+        test-results:
+          needs: [build]        # Skipped when build fails
+          runs-on: ubuntu-latest
+          # ⚠ No if: condition — job is skipped when build fails
+          # ⚠ Branch protection requires test-results to "pass"
+          # ⚠ skipped = passing in GitHub's branch protection evaluation
+          steps:
+            - run: ./test.sh
+
+  - language: yaml
+    label: 'Fixed — explicit catch-all aggregator job that fails on upstream failure'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - run: ./build.sh
+
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - run: ./test.sh
+
+        ci-gate:
+          if: always()
+          needs: [build, test]
+          runs-on: ubuntu-latest
+          steps:
+            - name: All required jobs must succeed
+              run: |
+                results='${{ toJSON(needs.*.result) }}'
+                if echo "$results" | grep -qE '"failure"|"cancelled"'; then
+                  echo "Pipeline failed: $results"
+                  exit 1
+                fi
+                echo "All jobs passed: $results"
+
+      # In branch protection: require "ci-gate" — not "build" or "test" individually
+
+prevention:
+  - 'Use a single aggregator job (`ci-gate`) as the required status check instead of individual job names.'
+  - 'Always include `if: always()` on the aggregator and explicitly check `needs.*.result` for failure/cancelled.'
+  - 'Do NOT rely on `needs:` skipping to propagate failures to branch protection — skipped is treated as passing.'
+  - 'After changing which jobs are required status checks, verify by letting a build fail and confirm the PR is blocked.'
+  - 'actionlint does not detect this misconfiguration — manual testing is required.'
+docs:
+  - url: 'https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/troubleshooting-required-status-checks'
+    label: 'GitHub Docs: Troubleshooting required status checks'
+  - url: 'https://github.com/actions/runner/issues/2566'
+    label: 'actions/runner#2566: Skipped jobs satisfy required checks (many reactions)'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-conditions-to-control-job-execution'
+    label: 'GitHub Docs: Using conditions to control job execution'

package/errors/concurrency-timing/concurrency-timing-060.yml

@@ -0,0 +1,144 @@
+id: concurrency-timing-060
+title: 'cancel-in-progress: false still silently drops older pending run when third concurrent dispatch arrives — GitHub enforces a 1-active + 1-pending hard limit per concurrency group'
+category: concurrency-timing
+severity: silent-failure
+tags:
+  - concurrency
+  - cancel-in-progress
+  - pending
+  - silent-cancel
+  - dispatch
+  - queue
+  - lost-run
+patterns:
+  - regex: 'This run was cancelled'
+    flags: 'i'
+  - regex: 'cancel-in-progress:\s*false'
+    flags: 'i'
+  - regex: 'Run was cancelled'
+    flags: 'i'
+error_messages:
+  - "This run was cancelled."
+  - "Run was cancelled."
+root_cause: |
+  Setting `cancel-in-progress: false` in a concurrency group does NOT mean "queue all
+  runs indefinitely." It means "do not cancel the currently *in-progress* run."
+
+  GitHub Actions enforces a hard internal limit of **1 in-progress + 1 pending** run
+  per concurrency group (when using the default or `cancel-in-progress: false`).
+  When a third concurrent run arrives:
+
+  1. Run A is **in-progress** (held in slot 1).
+  2. Run B is **pending** (held in slot 2, waiting for Run A to finish).
+  3. Run C arrives → GitHub silently cancels Run B to free slot 2, then queues Run C.
+
+  The net effect: Run B is lost. Run C is now pending and will eventually execute.
+  With `cancel-in-progress: false`, *only Run A is protected* from cancellation — not
+  Run B. The arriving run always displaces the previously pending one.
+
+  This surprises developers who read `cancel-in-progress: false` as "let all runs
+  queue and execute in order." The actual semantics are: "don't kill the in-flight
+  run, but still replace any queued-but-not-yet-running run."
+
+  There is no log entry showing Run B was cancelled by Run C's arrival; the cancellation
+  shows as "This run was cancelled" with no attribution.
+
+  To allow more than 1 pending run, use `queue: max` (up to 100 pending slots) — but
+  note that `queue: max` and `cancel-in-progress: true` cannot be combined.
+fix: |
+  Choose the concurrency strategy that matches your desired behavior:
+
+  **Option 1 — Allow up to 100 queued runs (strict ordering, no drops):**
+  Use `queue: max`. Every run is preserved and executes in arrival order. The 101st
+  concurrent run silently cancels the oldest pending run (see concurrency-timing-058
+  for the queue:max overflow edge case).
+
+  **Option 2 — Cancel stale runs, always run the latest (most common for CI):**
+  Use `cancel-in-progress: true`. Stale pending runs are cancelled; only the most
+  recent push/dispatch runs.
+
+  **Option 3 — Fine-grained concurrency keys to prevent grouping:**
+  Include `github.sha` or `github.run_id` in the group key so each run gets its own
+  isolated slot and nothing is ever cancelled or queued against another run.
+
+  **Option 4 — Accept the default behavior:**
+  Understand that `cancel-in-progress: false` means 1-active + 1-pending, and design
+  your pipeline around this. For example, if you need every commit tested, use
+  `cancel-in-progress: true` so you always test the latest commit, or `queue: max`
+  if you need every commit tested in order.
+fix_code:
+  - language: yaml
+    label: 'Broken — cancel-in-progress: false does NOT queue all runs; 3rd run drops 2nd'
+    code: |
+      on: push
+
+      concurrency:
+        group: deploy-${{ github.ref }}
+        cancel-in-progress: false   # ❌ Only protects the in-progress run (slot 1)
+                                    # ❌ Slot 2 (pending) is still replaced when a 3rd run arrives
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - run: ./deploy.sh
+
+  - language: yaml
+    label: 'Fixed — use queue: max to preserve all pending runs (up to 100)'
+    code: |
+      on: push
+
+      concurrency:
+        group: deploy-${{ github.ref }}
+        queue: max    # ✅ Up to 100 pending runs preserved, executed in order
+                      # ✅ No run is silently dropped until the 101st arrives
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - run: ./deploy.sh
+
+  - language: yaml
+    label: 'Alternative — cancel stale runs, keep only the latest (typical CI pattern)'
+    code: |
+      on: push
+
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.ref }}
+        cancel-in-progress: true   # ✅ Latest commit always runs; stale runs cancelled
+
+      jobs:
+        ci:
+          runs-on: ubuntu-latest
+          steps:
+            - run: ./test.sh
+
+  - language: yaml
+    label: 'Alternative — unique key per run (no cancellation, no queueing)'
+    code: |
+      on: push
+
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.run_id }}   # ✅ Each run is isolated
+        cancel-in-progress: false
+
+      jobs:
+        ci:
+          runs-on: ubuntu-latest
+          steps:
+            - run: ./test.sh
+
+prevention:
+  - 'Read `cancel-in-progress: false` as "protect the running job, not all pending jobs."'
+  - 'Use `queue: max` when you need every dispatched run to eventually execute.'
+  - '`queue: max` and `cancel-in-progress: true` cannot be combined — validation error.'
+  - 'Include `github.sha` or `github.run_id` in the group key to give each run its own isolated slot.'
+  - 'Monitor the Actions tab for unexplained cancellations after rapid pushes to confirm you are hitting the 1-pending limit.'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/control-the-concurrency-of-workflows-and-jobs'
+    label: 'GitHub Docs: Control the concurrency of workflows and jobs'
+  - url: 'https://github.com/orgs/community/discussions/5435'
+    label: 'GitHub Community #5435: cancel-in-progress: false still cancels pending runs'
+  - url: 'https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#concurrency'
+    label: 'GitHub Docs: Workflow syntax — concurrency'

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)'