diff --git a/.github/workflows/self-scan.yml b/.github/workflows/self-scan.yml
index ce5138f..b289056 100644
--- a/.github/workflows/self-scan.yml
+++ b/.github/workflows/self-scan.yml
@@ -30,6 +30,8 @@ jobs:
 
   self-scan-action:
     runs-on: ubuntu-latest
+    permissions:
+      security-events: write
 
     steps:
       - name: Checkout
diff --git a/website/docs/sarif.md b/website/docs/sarif.md
index 5f8a978..594b3a9 100644
--- a/website/docs/sarif.md
+++ b/website/docs/sarif.md
@@ -29,20 +29,30 @@ cve-lite . --sarif --json
 Upload the SARIF file to GitHub's Security tab using the official action:
 
 ```yaml
-- name: Scan dependencies
-  run: cve-lite . --sarif
-
-- name: Upload SARIF to GitHub
-  uses: github/codeql-action/upload-sarif@v4
-  if: always()
-  with:
-    sarif_file: ${{ github.workspace }}
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write  # required for upload-sarif
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Scan dependencies
+        run: cve-lite . --sarif
+
+      - name: Upload SARIF to GitHub
+        uses: github/codeql-action/upload-sarif@v4
+        if: always()
+        with:
+          sarif_file: ${{ github.workspace }}
 ```
 
 Findings appear in the **Security → Code scanning** tab and as PR annotations.
 
 :::tip
-Use `if: always()` on the upload step. Without it, the upload is skipped when `--fail-on` causes a non-zero exit — which means you'd lose the findings in Code Scanning exactly when they matter most.
+`security-events: write` is a GitHub platform requirement for any workflow that uploads to Code Scanning — it must be declared on the job, not inside the action.
+
+Use `if: always()` on the upload step so findings are uploaded even when `--fail-on` causes a non-zero exit.
 :::
 
 ## What the SARIF file contains
diff --git a/website/docs/workflow-integration.md b/website/docs/workflow-integration.md
index eb36a88..5fc8eb8 100644
--- a/website/docs/workflow-integration.md
+++ b/website/docs/workflow-integration.md
@@ -114,21 +114,29 @@ This repository also uses CVE Lite CLI in its own CI to scan itself. See [`self-
 Add `sarif: "true"` and an upload step to surface findings in the **Security → Code scanning** tab and as PR annotations:
 
 ```yaml
-- uses: actions/checkout@v6
-- uses: OWASP/cve-lite-cli@v1
-  with:
-    fail-on: high
-    sarif: "true"
-
-- name: Upload to GitHub Code Scanning
-  uses: github/codeql-action/upload-sarif@v4
-  if: always()
-  with:
-    sarif_file: ${{ github.workspace }}
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write  # required for upload-sarif
+    steps:
+      - uses: actions/checkout@v6
+      - uses: OWASP/cve-lite-cli@v1
+        with:
+          fail-on: high
+          sarif: "true"
+
+      - name: Upload to GitHub Code Scanning
+        uses: github/codeql-action/upload-sarif@v4
+        if: always()
+        with:
+          sarif_file: ${{ github.workspace }}
 ```
 
 :::tip
-`if: always()` is required on the upload step. Without it, the upload is skipped when `--fail-on` causes a non-zero exit — losing your findings in Code Scanning exactly when they matter most.
+`security-events: write` is a GitHub platform requirement for any workflow that uploads to Code Scanning — it must be declared on the job, not inside the action.
+
+Use `if: always()` on the upload step so findings are uploaded even when `--fail-on` causes a non-zero exit.
 :::
 
 ---