@htekdev/actions-debugger 1.0.124 → 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-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'

package/errors/permissions-auth/permissions-auth-071.yml

@@ -0,0 +1,144 @@
+id: permissions-auth-071
+title: 'OIDC token not available in pull_request events from forks — id-token: write cannot be granted'
+category: permissions-auth
+severity: error
+tags:
+  - oidc
+  - fork
+  - pull-request
+  - id-token
+  - attestation
+  - aws
+  - azure
+  - workload-identity
+patterns:
+  - regex: 'Unable to get ACTIONS_ID_TOKEN_REQUEST_URL env variable'
+    flags: 'i'
+  - regex: 'Could not fetch an OIDC token.*id-token.*write'
+    flags: 'i'
+  - regex: 'Error: Action failed with error: Error: Error message: Unable to get ACTIONS_ID_TOKEN_REQUEST_URL'
+    flags: 'i'
+error_messages:
+  - 'Error: Error message: Unable to get ACTIONS_ID_TOKEN_REQUEST_URL env variable'
+  - 'Could not fetch an OIDC token. Did you remember to add `id-token: write` to your workflow permissions?'
+  - 'Error: Action failed with error: Error: Error message: Unable to get ACTIONS_ID_TOKEN_REQUEST_URL env variable'
+root_cause: |
+  GitHub Actions workflows triggered by `pull_request` events from forked repositories cannot
+  mint OIDC tokens, even when `id-token: write` is explicitly set in the workflow `permissions:` block.
+
+  The restriction is enforced by GitHub's security model for fork pull requests:
+  - Fork PRs run with the permissions of the fork, not the base repository.
+  - GitHub documentation states: "You can use the permissions key to add and remove read
+    permissions for forked repositories, but typically you can't grant write access."
+  - The `id-token: write` scope is a WRITE permission. The ACTIONS_ID_TOKEN_REQUEST_URL
+    environment variable is only set when the runtime has write-level token access.
+  - When the variable is absent, any action or toolkit call to `core.getIDToken()` fails with
+    "Unable to get ACTIONS_ID_TOKEN_REQUEST_URL env variable".
+
+  This commonly impacts:
+  - Cloud provider OIDC authentication (AWS configure-aws-credentials, Azure login, GCP auth)
+  - actions/attest-build-provenance and actions/attest for build attestation on PRs
+  - Any action that relies on `@actions/core` `getIDToken()` for OIDC federation
+
+  The restriction exists to prevent malicious fork contributors from using OIDC tokens to
+  authenticate against production cloud accounts or push malicious artifacts.
+fix: |
+  Option 1 — Use `pull_request_target` instead of `pull_request` (CAUTION required).
+  `pull_request_target` runs in the context of the base repository and CAN mint OIDC tokens.
+  However, it executes in the base repo's context with full access to base repo secrets —
+  this is a significant security risk if the workflow checks out or executes fork code without
+  proper isolation. Read all security guides before using this trigger.
+
+  Option 2 — Split the workflow into two parts.
+  Use `pull_request` for the build/test phase (no OIDC). Use a separate workflow triggered
+  by `workflow_run` or manual approval to perform OIDC-protected operations (attestation, deploy)
+  after verifying the PR code is safe.
+
+  Option 3 — Use a GitHub App token with explicit repository permissions for operations
+  that do not strictly require OIDC (e.g., package publishing). This avoids the OIDC
+  restriction entirely.
+
+  Option 4 — Only run OIDC-dependent steps on `push` events to protected branches (post-merge),
+  not on `pull_request` events from forks. Guard OIDC steps with:
+    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.fork == false
+fix_code:
+  - language: yaml
+    label: 'Guard OIDC steps — skip for fork PRs, run only for same-repo PRs or push'
+    code: |
+      jobs:
+        build-and-attest:
+          runs-on: ubuntu-latest
+          permissions:
+            id-token: write
+            contents: read
+            attestations: write
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Build artifact
+              run: ./build.sh
+
+            # OIDC-dependent steps: skip if fork PR (id-token write not available)
+            - name: Attest build provenance
+              if: >
+                github.event_name != 'pull_request' ||
+                github.event.pull_request.head.repo.full_name == github.repository
+              uses: actions/attest-build-provenance@v2
+              with:
+                subject-path: './dist/app'
+
+  - language: yaml
+    label: 'Split workflow: use workflow_run to run OIDC steps after fork PR merges'
+    code: |
+      # Workflow 1: runs on pull_request — builds and uploads artifact (no OIDC)
+      on:
+        pull_request:
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: ./build.sh
+            - uses: actions/upload-artifact@v4
+              with:
+                name: build-output
+                path: ./dist/
+
+      ---
+
+      # Workflow 2: runs after workflow 1 completes — performs OIDC operations
+      on:
+        workflow_run:
+          workflows: ['Build']
+          types: [completed]
+      jobs:
+        attest:
+          # Only runs on base-repo push events completing after a merge
+          if: github.event.workflow_run.conclusion == 'success'
+          runs-on: ubuntu-latest
+          permissions:
+            id-token: write
+            attestations: write
+          steps:
+            - uses: actions/download-artifact@v4
+              with:
+                name: build-output
+                run-id: ${{ github.event.workflow_run.id }}
+                github-token: ${{ secrets.GITHUB_TOKEN }}
+            - uses: actions/attest-build-provenance@v2
+              with:
+                subject-path: './dist/app'
+prevention:
+  - 'Never assume `id-token: write` is sufficient — fork PRs override write permissions to read-only regardless of the workflow `permissions:` block.'
+  - 'Add an explicit `if:` guard on every OIDC-dependent step to skip it for fork PRs: `if: github.event.pull_request.head.repo.fork == false`.'
+  - 'Use `pull_request_target` only after thoroughly reading the security hardening guide — it runs in base repo context and is vulnerable to pwn requests if fork code is checked out.'
+  - 'For attestation workflows, run attestation as a post-merge step on `push` to the default branch, not on PRs from forks.'
+docs:
+  - url: 'https://github.com/actions/attest-build-provenance/issues/99'
+    label: 'actions/attest-build-provenance#99 — OIDC unavailable in fork PR workflows (open)'
+  - url: 'https://github.com/aws-actions/configure-aws-credentials/issues/373'
+    label: 'aws-actions/configure-aws-credentials#373 — OIDC fails for pull request from fork'
+  - url: 'https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication#permissions-for-the-github_token'
+    label: 'GitHub Docs — GITHUB_TOKEN permissions for forked repos'
+  - url: 'https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions#using-pull_request_target-safely'
+    label: 'GitHub Docs — Security hardening for pull_request_target'