From adb29f5166d7793363201c860535338e4fcc659d Mon Sep 17 00:00:00 2001
From: Hashim1999164 <64767361+Hashim1999164@users.noreply.github.com>
Date: Fri, 31 Jul 2026 23:19:26 +0500
Subject: [PATCH] Document required workflow permissions in README

Restore a clear permissions example for advanced setup workflows,
including private-repo needs, so existing users can apply the minimum
set without digging through starter templates. Fixes #1913.
---
 README.md | 21 ++++++++++++++++++++-
 1 file changed, 20 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 530c028f97..469d793926 100644
--- a/README.md
+++ b/README.md
@@ -38,7 +38,26 @@ Actions with special purposes and unlikely to be used directly:
 
 ### Workflow Permissions
 
-All advanced setup code scanning workflows must have the `security-events: write` permission. Workflows in private repositories must additionally have the `contents: read` permission. For more information, see "[Assigning permissions to jobs](https://docs.github.com/en/actions/using-jobs/assigning-permissions-to-jobs)."
+All advanced setup code scanning workflows need certain permissions. At minimum:
+
+```yaml
+permissions:
+  # required for all workflows
+  security-events: write
+
+  # required to fetch internal or private CodeQL packs
+  packages: read
+
+  # only required for workflows in private repositories
+  actions: read
+  contents: read
+```
+
+- `security-events: write` is required so the action can upload results to code scanning.
+- `packages: read` is needed when the workflow fetches internal or private CodeQL packs.
+- `actions: read` and `contents: read` are required for workflows in private repositories.
+
+For more information, see "[Assigning permissions to jobs](https://docs.github.com/en/actions/using-jobs/assigning-permissions-to-jobs)" and the [CodeQL starter workflow](https://github.com/actions/starter-workflows/blob/main/code-scanning/codeql.yml).
 
 ### Build Modes