@htekdev/actions-debugger 1.0.110 → 1.0.112

package/errors/caching-artifacts/buildkit-gha-cache-legacy-api-v1-self-hosted.yml

@@ -0,0 +1,123 @@
+id: 'caching-artifacts-065'
+title: 'Docker BuildKit type=gha cache fails on self-hosted runners with BuildKit < 0.21.0 after legacy cache service v1 shutdown'
+category: 'caching-artifacts'
+severity: 'error'
+tags:
+  - docker
+  - buildkit
+  - buildx
+  - gha-cache
+  - self-hosted
+  - cache-api-v2
+  - legacy-service
+patterns:
+  - regex: 'This legacy service is shutting down'
+    flags: 'i'
+  - regex: 'failed to solve.*legacy.*service'
+    flags: 'i'
+  - regex: 'gha-cache-sunset'
+    flags: 'i'
+  - regex: 'cache.*type=gha.*legacy'
+    flags: 'i'
+error_messages:
+  - "ERROR: failed to solve: This legacy service is shutting down, effective April 15, 2025. Migrate to the new service ASAP. For more information: https://gh.io/gha-cache-sunset"
+  - "This legacy service is shutting down, effective April 15, 2025."
+  - "importing cache manifest from gha"
+  - "exporting to GitHub Actions Cache"
+root_cause: |
+  GitHub decommissioned the legacy GitHub Actions Cache service v1 API on
+  April 15, 2025. All cache operations now require the new v2 API.
+
+  Docker BuildKit uses a separate Go-based GitHub Actions cache client
+  (`tonistiigi/go-actions-cache`) — distinct from the `@actions/cache` npm
+  package used by `actions/cache`. The `go-actions-cache` library added support
+  for cache API v2 in BuildKit 0.20.0 and Buildx 0.21.0.
+
+  Self-hosted runners that have not been updated since before the migration
+  still ship Docker Engine with an older BuildKit version (< 0.20.0) or an
+  older Docker Buildx binary (< 0.21.0). When these workflows use
+  `cache-from: type=gha` or `cache-to: type=gha`, the old BuildKit communicates
+  with the now-decommissioned v1 API endpoint and receives the shutdown error:
+
+    ERROR: failed to solve: This legacy service is shutting down, effective
+    April 15, 2025. Migrate to the new service ASAP.
+
+  GitHub-hosted runners (ubuntu-latest, etc.) are automatically up to date and
+  are not affected. Only self-hosted runners or custom BuildKit setups that
+  pin an old Buildx/BuildKit version are impacted.
+
+  Note: this is distinct from `actions/cache` action failing due to stale
+  ACTIONS_CACHE_URL overrides (caching-artifacts-031), which is a different
+  failure mode involving the npm-based cache client.
+fix: |
+  Option 1 (recommended): Pin docker/setup-buildx-action to install the latest
+  Buildx on the self-hosted runner before each build. This ensures Buildx >=
+  0.21.0 is always used regardless of the runner's system Buildx version.
+
+  Option 2: Update the self-hosted runner's Docker Engine to >= 28.0.0 and
+  Buildx to >= 0.21.0 at the system level.
+
+  Option 3: Switch to registry-based cache (type=registry) if upgrading Buildx
+  is not feasible. GHCR registry cache is not subject to the API version
+  requirement and is free for public repositories.
+
+  Minimum versions required for cache API v2:
+  - Docker Buildx >= 0.21.0
+  - BuildKit >= 0.20.0
+  - Docker Compose >= 2.33.1
+  - Docker Engine >= 28.0.0 (when using containerd image store)
+fix_code:
+  - language: yaml
+    label: 'Pin setup-buildx-action to install latest Buildx on self-hosted runner'
+    code: |
+      jobs:
+        build:
+          runs-on: [self-hosted, linux, x64]
+          steps:
+            - uses: actions/checkout@v4
+
+            # Always install the latest Buildx — ensures >= 0.21.0 for cache API v2
+            - name: Set up Docker Buildx
+              uses: docker/setup-buildx-action@v3
+              with:
+                version: latest   # Overrides the runner's system Buildx version
+
+            - name: Build and push
+              uses: docker/build-push-action@v7
+              with:
+                push: ${{ github.ref == 'refs/heads/main' }}
+                tags: ghcr.io/${{ github.repository }}:latest
+                cache-from: type=gha
+                cache-to: type=gha,mode=max
+  - language: yaml
+    label: 'Fallback: use GHCR registry cache instead of type=gha'
+    code: |
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build and push (registry cache — no API version dependency)
+        uses: docker/build-push-action@v7
+        with:
+          push: ${{ github.ref == 'refs/heads/main' }}
+          tags: ghcr.io/${{ github.repository }}:latest
+          cache-from: type=registry,ref=ghcr.io/${{ github.repository }}:buildcache
+          cache-to: type=registry,ref=ghcr.io/${{ github.repository }}:buildcache,mode=max
+prevention:
+  - "Always add docker/setup-buildx-action with 'version: latest' before any Docker build step on self-hosted runners."
+  - "Periodically update self-hosted runner Docker Engine and Buildx to latest stable versions."
+  - "Subscribe to the GitHub Changelog (github.blog/changelog) for advance notice of cache service API changes."
+  - "Verify Buildx version in CI: add 'docker buildx version' as a diagnostic step to catch version drift early."
+  - "Consider using registry cache (type=registry) as a more portable alternative to type=gha on self-hosted runners."
+docs:
+  - url: 'https://github.com/docker/build-push-action/issues/1345'
+    label: 'docker/build-push-action#1345 — type=gha cache failure after legacy service shutdown (Apr 2025)'
+  - url: 'https://docs.docker.com/build/ci/github-actions/cache/#github-cache'
+    label: 'Docker Docs — GitHub Actions cache backend (note: legacy v1 API shut down April 15, 2025)'
+  - url: 'https://github.com/docker/setup-buildx-action'
+    label: 'docker/setup-buildx-action — Install latest Buildx on any runner'
+  - url: 'https://gh.io/gha-cache-sunset'
+    label: 'GitHub — GHA cache service v1 sunset announcement'

package/errors/concurrency-timing/merge-group-pr-number-concurrency-null-collapse.yml

@@ -0,0 +1,85 @@
+id: concurrency-timing-051
+title: 'merge_group event has no pull_request.number — PR-number-keyed concurrency group collapses all merge queue runs to the same slot'
+category: concurrency-timing
+severity: silent-failure
+tags:
+  - concurrency
+  - merge-queue
+  - merge_group
+  - pull_request
+  - cancel-in-progress
+  - null-key
+patterns:
+  - regex: 'merge_group'
+    flags: 'i'
+  - regex: 'pull_request\.number'
+    flags: 'i'
+  - regex: 'Canceling since a higher priority waiting run was found'
+    flags: 'i'
+error_messages:
+  - 'This run was automatically cancelled'
+  - 'Canceling since a higher priority waiting run was found'
+  - 'Required status checks did not pass'
+root_cause: |
+  The merge_group event payload does not include a pull_request object. When a workflow
+  uses ${{ github.event.pull_request.number }} in a concurrency group key — a common
+  pattern to scope CI runs per open PR — the expression evaluates to an empty string
+  for all merge_group-triggered runs.
+
+  All merge queue validation runs therefore share an identical concurrency group key
+  (e.g., ci- instead of ci-42). With cancel-in-progress: true, each new merge queue
+  batch immediately cancels the currently running validation for all other batches in
+  the queue. With cancel-in-progress: false, only the most-recently-queued batch runs;
+  earlier batches are ejected from the merge queue with 'Required status checks did
+  not pass'.
+
+  This silently serializes or destroys merge queue throughput and commonly occurs when
+  developers add merge_group to an existing pull_request workflow that already uses
+  PR-number-based concurrency without updating the group expression.
+fix: |
+  Use a conditional expression that resolves to a unique key for both event types.
+  For merge_group events, github.event.merge_group.head_sha provides a value that is
+  unique per merge queue batch:
+
+    group: ci-${{ github.event.pull_request.number || github.event.merge_group.head_sha }}
+fix_code:
+  - language: yaml
+    label: 'Broken: merge_group runs collapse to ci- (empty PR number)'
+    code: |
+      on:
+        pull_request:
+        merge_group:
+
+      concurrency:
+        group: ci-${{ github.event.pull_request.number }}
+        cancel-in-progress: true
+  - language: yaml
+    label: 'Fixed: fallback to merge_group.head_sha for merge queue runs'
+    code: |
+      on:
+        pull_request:
+        merge_group:
+
+      concurrency:
+        # pull_request: keyed by PR number (e.g., ci-42)
+        # merge_group:  keyed by batch SHA (unique per merge queue batch)
+        group: ci-${{ github.event.pull_request.number || github.event.merge_group.head_sha }}
+        cancel-in-progress: true
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: make test
+prevention:
+  - 'When adding merge_group to an existing pull_request workflow, audit every concurrency group expression for github.event.pull_request.* references — all are null on merge_group events'
+  - 'Use github.event.merge_group.head_sha as the fallback identifier for merge queue runs; it is unique per batch'
+  - 'Verify the resolved concurrency key by adding a debug step that prints the evaluated expression for each event type'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#merge_group'
+    label: 'GitHub Docs: merge_group event'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-concurrency'
+    label: 'GitHub Docs: Using concurrency'
+  - url: 'https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-a-merge-queue'
+    label: 'GitHub Docs: Managing a merge queue'

package/errors/concurrency-timing/push-schedule-shared-concurrency-silent-cancel.yml

@@ -0,0 +1,84 @@
+id: concurrency-timing-050
+title: 'push and schedule sharing a concurrency group silently cancel each other on the default branch'
+category: concurrency-timing
+severity: silent-failure
+tags:
+  - concurrency
+  - push
+  - schedule
+  - cancel-in-progress
+  - nightly-build
+  - silent-failure
+patterns:
+  - regex: 'Canceling since a higher priority waiting run was found'
+    flags: 'i'
+  - regex: 'This run was automatically cancelled'
+    flags: 'i'
+error_messages:
+  - 'This run was automatically cancelled'
+  - 'Canceling since a higher priority waiting run was found'
+root_cause: |
+  When a workflow responds to both on.push and on.schedule, and uses a concurrency
+  group key that does not include github.event_name, all push and schedule runs share
+  the same concurrency slot.
+
+  Both a push to the default branch and a scheduled run targeting the default branch
+  evaluate github.ref to refs/heads/main (or the configured default branch name).
+  A concurrency group of ${{ github.workflow }}-${{ github.ref }} therefore produces
+  an identical key for both event types.
+
+  With cancel-in-progress: true, any push commit that lands while a scheduled run
+  (nightly build, report, data sync) is executing immediately cancels that run with
+  no error notification. With cancel-in-progress: false, the one pending-run slot is
+  taken by the push run, silently displacing any queued scheduled run.
+
+  This is distinct from the workflow_dispatch + schedule pattern (concurrency-timing-047)
+  because push events are emitted automatically on every commit and are far more
+  frequent than manual dispatches, making accidental cancellation of scheduled runs a
+  routine occurrence rather than an occasional manual event.
+fix: |
+  Include github.event_name in the concurrency group key so that push runs and
+  schedule runs each occupy a separate, independent slot:
+
+    group: ${{ github.workflow }}-${{ github.event_name }}-${{ github.ref }}
+fix_code:
+  - language: yaml
+    label: 'Broken: push and schedule share one slot'
+    code: |
+      on:
+        push:
+          branches: [main]
+        schedule:
+          - cron: '0 2 * * *'
+
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.ref }}
+        cancel-in-progress: true
+  - language: yaml
+    label: 'Fixed: include github.event_name to isolate push and schedule concurrency slots'
+    code: |
+      on:
+        push:
+          branches: [main]
+        schedule:
+          - cron: '0 2 * * *'
+
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.event_name }}-${{ github.ref }}
+        cancel-in-progress: true
+
+      jobs:
+        ci:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: make test
+prevention:
+  - 'Always include ${{ github.event_name }} in the concurrency group key for workflows triggered by both automated (push/pull_request) and scheduled events'
+  - 'After adding on.schedule to an existing push-triggered workflow, audit the concurrency group key to confirm scheduled runs receive their own independent slot'
+  - 'Monitor the Actions tab for unexpected gaps in scheduled run history — silent cancellations leave no failed run, only a missing run for that time slot'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-concurrency'
+    label: 'GitHub Docs: Using concurrency'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#schedule'
+    label: 'GitHub Docs: schedule event'

package/errors/known-unsolved/ephemeral-jit-runner-lost-communication-false-positive.yml

@@ -0,0 +1,93 @@
+id: known-unsolved-058
+title: 'Ephemeral JIT Runner Reports "Lost Communication" Despite Successful Job Completion'
+category: known-unsolved
+severity: error
+tags:
+  - self-hosted
+  - ephemeral
+  - jit-runner
+  - lost-communication
+  - false-positive
+  - broker
+patterns:
+  - regex: 'The self-hosted runner lost communication with the server'
+    flags: 'i'
+  - regex: 'messageQueueLoopTokenSource|Stop message queue looping'
+    flags: 'i'
+error_messages:
+  - 'The self-hosted runner lost communication with the server'
+  - 'GET request to broker.actions.githubusercontent.com/message ... has been cancelled'
+  - 'TaskCanceledException: The operation was canceled'
+root_cause: |
+  In Runner.cs line 576, after a one-time-use (ephemeral/JIT) job completes, the message queue
+  is cancelled immediately with zero grace period:
+
+    messageQueueLoopTokenSource.Cancel();
+
+  This tears down the in-flight broker long-poll (GET broker.actions.githubusercontent.com/message)
+  immediately after CompleteJobAsync returns. GitHub's broker health monitor detects the TCP
+  disconnect and flags the runner as "lost communication" — racing against the pipeline service
+  that just received the successful completion.
+
+  Two independent GitHub backend systems race:
+  1. Pipeline service — received CompleteJobAsync, knows the job succeeded
+  2. Broker health monitor — sees TCP disconnect, flags runner as "lost communication"
+
+  When the broker monitor wins (which happens on ~5-10% of short jobs), the UI shows
+  "The self-hosted runner lost communication with the server" even though the worker exited
+  with code 100 (success) and the runner itself exited with return code 0.
+
+  The runner logs show all events at identical timestamps — zero delay between
+  "Received job status event. JobState: Online" and "messageQueueLoopTokenSource.Cancel()".
+
+  No user-side configuration can fix this. A code change to Runner.cs is required
+  (add ~5s grace delay before cancel). Source: actions/runner#4309 (March 2026, open bug,
+  affects runner v2.331.0+, ~5-10% failure rate on short ephemeral jobs).
+fix: |
+  There is no user-side configuration fix. The root cause is a zero-grace-period teardown
+  in Runner.cs that must be patched by GitHub.
+
+  Mitigations:
+  1. Verify the diagnostic logs — the job actually succeeded. Check _diag/Runner_*.log
+     for "return code 0" and "result: Succeeded" to confirm before concluding failure.
+  2. Retry the failed job — the "lost communication" is a false positive; re-running
+     produces a clean success.
+  3. Do not use ephemeral JIT runners as required status checks until actions/runner#4309
+     is resolved, or implement a workflow-level retry wrapper.
+  4. Alert on job result=="failure" not on "lost communication" text alone — false positives
+     from this race should not page on-call engineers.
+  5. Batch small jobs — the race is more likely on jobs shorter than 60 seconds. Combining
+     work into longer-running jobs reduces false positive frequency.
+fix_code:
+  - language: yaml
+    label: 'Confirm false positive by reading runner diagnostic log before retrying'
+    code: |
+      # After "lost communication" on an ephemeral JIT runner, check:
+      # _diag/Runner_YYYYMMDD-hhmmss-utc.log
+      #
+      # Successful completion signs (all at identical timestamps):
+      #   [INFO] finish job request for job {id} with result: Succeeded
+      #   [INFO] Job X completed with result: Succeeded
+      #   [INFO] Received job status event. JobState: Online
+      #   [INFO] Runner execution has finished with return code 0
+      #
+      # If these appear immediately before TaskCanceledException, the job DID succeed.
+      # Simply re-run the workflow — the retry will show a clean green result.
+      jobs:
+        build:
+          runs-on: [self-hosted, ephemeral, linux]
+          # Note: retry-on-failure logic can wrap this job in the caller:
+          steps:
+            - uses: actions/checkout@v4
+            - run: make build
+prevention:
+  - 'Treat "lost communication" on ephemeral JIT runners as a potential false positive — check _diag/Runner_*.log for "return code 0" before escalating.'
+  - 'Do not gate required status checks on ephemeral JIT runners until actions/runner#4309 is resolved upstream.'
+  - 'Alert on job result=="failure", not on the "lost communication" message text alone.'
+  - 'Batch work into longer jobs (>60s total) to reduce the broker teardown race frequency.'
+  - 'Watch actions/runner#4309 for an upstream fix (proposed: 5-second grace period before messageQueueLoopTokenSource.Cancel()).'
+docs:
+  - url: 'https://github.com/actions/runner/issues/4309'
+    label: 'actions/runner#4309: Ephemeral/JIT runner reports "lost communication" despite successful completion (March 2026)'
+  - url: 'https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/autoscaling-with-self-hosted-runners#using-just-in-time-runners'
+    label: 'GitHub Docs: Just-in-time (JIT) runners'

package/errors/known-unsolved/vars-context-reusable-workflow-reflects-caller-repo.yml

@@ -0,0 +1,91 @@
+id: known-unsolved-059
+title: 'vars context in reusable workflows reflects the CALLER repository variables — the called workflow repository-level vars are inaccessible'
+category: known-unsolved
+severity: limitation
+tags:
+  - vars
+  - reusable-workflow
+  - workflow_call
+  - variables
+  - configuration
+  - known-limitation
+patterns:
+  - regex: 'vars\.[A-Z_]+'
+    flags: 'i'
+  - regex: 'workflow_call'
+    flags: 'i'
+error_messages:
+  - '(no runtime error — vars context silently returns caller repository values instead of called workflow repository values)'
+root_cause: |
+  GitHub Actions populates the vars context in a reusable workflow called via
+  workflow_call using the CALLER repository organization, repository, and environment
+  variables — not those defined in the repository that hosts the reusable workflow.
+
+  This means repository-level variables set in the reusable workflow repository are
+  not accessible when the workflow executes in another repository context. The vars
+  context in the called workflow reflects only:
+    - Organization-level variables visible to the caller
+    - The CALLER repository-level variables
+    - Environment-scoped variables from environments the caller deploys to
+
+  Unlike secrets (which has secrets: inherit), there is no vars: inherit mechanism.
+  A shared reusable workflow library that stores its own configuration in
+  repository-level variables cannot access those values at runtime when called
+  from another repository.
+
+  The workflow runs without error but references wrong or empty variable values
+  silently, producing incorrect behavior that is difficult to diagnose because
+  the runner logs show no permission error.
+fix: |
+  There is no built-in mechanism to make the called workflow repository-level
+  variables available at runtime.
+
+  Available workarounds:
+  1. Promote shared configuration to organization-level variables — visible to
+     all member repositories and available in both caller and called contexts.
+  2. Pass required values as explicit workflow_call inputs from the caller:
+       with:
+         registry_url: ${{ vars.REGISTRY_URL }}
+  3. Store shared configuration in a committed file in the called workflow
+     repository and read it via a step after checkout.
+fix_code:
+  - language: yaml
+    label: 'Workaround: pass configuration values as explicit workflow_call inputs'
+    code: |
+      # Caller repository workflow
+      jobs:
+        deploy:
+          uses: org/shared-workflows/.github/workflows/deploy.yml@main
+          with:
+            deploy_env: ${{ vars.DEPLOY_ENV }}
+            registry_url: ${{ vars.REGISTRY_URL }}
+          secrets: inherit
+
+      ---
+      # Called reusable workflow (in org/shared-workflows repo)
+      on:
+        workflow_call:
+          inputs:
+            deploy_env:
+              type: string
+              required: true
+            registry_url:
+              type: string
+              required: true
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Deploying to ${{ inputs.deploy_env }}"
+prevention:
+  - 'Do not rely on repository-level vars in a shared reusable workflow library repo — they will not be available when the workflow runs in another repository context'
+  - 'Use organization-level variables for shared configuration that must be accessible from reusable workflows across all member repositories'
+  - 'Document all required configuration values as explicit workflow_call inputs with type and description so callers know exactly what to pass'
+  - 'Audit shared workflow libraries for vars. references that assume the called repo context — they will silently read caller repo values or return empty strings'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#vars-context'
+    label: 'GitHub Docs: vars context'
+  - url: 'https://docs.github.com/en/actions/sharing-automations/reusing-workflows#passing-inputs-and-secrets-to-a-reusable-workflow'
+    label: 'GitHub Docs: Passing inputs and secrets to a reusable workflow'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables'
+    label: 'GitHub Docs: Store information in variables'

package/errors/permissions-auth/security-events-write-required-for-sarif-upload.yml

@@ -0,0 +1,104 @@
+id: permissions-auth-063
+title: 'security-events: write required for SARIF upload — missing permission causes Resource not accessible by integration'
+category: permissions-auth
+severity: error
+tags:
+  - security-events
+  - sarif
+  - code-scanning
+  - permissions
+  - upload-sarif
+  - github-token
+patterns:
+  - regex: 'Resource not accessible by integration'
+    flags: 'i'
+  - regex: 'HttpError: Resource not accessible by integration'
+    flags: 'i'
+  - regex: 'Code scanning is not enabled for this repository'
+    flags: 'i'
+  - regex: 'Advanced Security must be enabled for this repository to use code scanning'
+    flags: 'i'
+error_messages:
+  - 'Resource not accessible by integration'
+  - 'HttpError: Resource not accessible by integration'
+  - 'Code scanning is not enabled for this repository'
+  - 'Advanced Security must be enabled for this repository to use code scanning'
+root_cause: |
+  The github/codeql-action/upload-sarif action and third-party security scanning
+  actions (Trivy, Snyk, Semgrep, osv-scanner, etc.) submit SARIF results to the
+  GitHub code scanning API endpoint POST /repos/{owner}/{repo}/code-scanning/sarifs.
+  This endpoint requires the security-events: write permission on the GITHUB_TOKEN.
+
+  Since February 2023, newly created repositories default GITHUB_TOKEN to read-only
+  permissions. A workflow that calls upload-sarif without an explicit
+  security-events: write permission block will receive 403 Resource not accessible by
+  integration from the API and the scan results will not appear in the Security tab.
+
+  This error is commonly overlooked because:
+  1. The scanning step (CodeQL analyze, Trivy scan, Semgrep scan) often completes
+     successfully — the red X appears only on the upload step.
+  2. Example workflows published before the read-only-default policy may omit the
+     security-events: write permission line.
+  3. For fork pull requests, the pull_request trigger cannot write security-events
+     even with the permission declared — a workflow_run split pattern is required.
+fix: |
+  Add security-events: write to the job permissions block. Include contents: read
+  for checkout and actions: read if the workflow uses CodeQL (which needs to read
+  workflow definitions).
+fix_code:
+  - language: yaml
+    label: 'Add security-events: write for SARIF upload'
+    code: |
+      jobs:
+        scan:
+          runs-on: ubuntu-latest
+          permissions:
+            security-events: write   # required for upload-sarif
+            contents: read           # required for checkout
+            actions: read            # required by CodeQL to read workflow info
+          steps:
+            - uses: actions/checkout@v4
+            - name: Run Trivy vulnerability scanner
+              uses: aquasecurity/trivy-action@master
+              with:
+                scan-type: 'fs'
+                format: 'sarif'
+                output: 'trivy-results.sarif'
+            - name: Upload Trivy results to GitHub Security tab
+              uses: github/codeql-action/upload-sarif@v3
+              with:
+                sarif_file: 'trivy-results.sarif'
+  - language: yaml
+    label: 'Fork PRs: upload SARIF in a workflow_run triggered workflow (has write access)'
+    code: |
+      # Scanning step runs in pull_request context (no write access from fork)
+      # Upload step runs in workflow_run context (has security-events: write)
+      on:
+        workflow_run:
+          workflows: ['Security Scan']
+          types: [completed]
+      jobs:
+        upload-results:
+          runs-on: ubuntu-latest
+          permissions:
+            security-events: write
+          steps:
+            - name: Download SARIF artifact
+              uses: actions/download-artifact@v4
+              with:
+                run-id: ${{ github.event.workflow_run.id }}
+                name: sarif-results
+            - uses: github/codeql-action/upload-sarif@v3
+              with:
+                sarif_file: results.sarif
+prevention:
+  - 'Add security-events: write to every job that calls github/codeql-action/upload-sarif or any third-party SARIF upload action'
+  - 'For fork pull request scanning, use the workflow_run + artifact pattern — the pull_request trigger cannot write security-events from fork contexts'
+  - 'Check the Security tab after a scan workflow succeeds — absence of scan results despite a green workflow is the primary indicator of missing security-events permission'
+docs:
+  - url: 'https://docs.github.com/en/code-security/code-scanning/integrating-with-code-scanning/uploading-a-sarif-file-to-github'
+    label: 'GitHub Docs: Uploading a SARIF file to GitHub'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/assigning-permissions-to-jobs'
+    label: 'GitHub Docs: Assigning permissions to jobs'
+  - url: 'https://docs.github.com/en/code-security/code-scanning/troubleshooting-code-scanning/results-are-different-than-expected'
+    label: 'GitHub Docs: Code scanning troubleshooting — results are different than expected'