docs: harden GITHUB_TOKEN permissions in gitStream workflow templates (#850)

* docs: harden GITHUB_TOKEN permissions in gitStream workflow templates

Add `permissions: contents: read` to the generated gitStream workflow
templates and all inline snippets in the installation + troubleshooting
docs. Add a dedicated section explaining the two-token split (workflow
GITHUB_TOKEN vs. gitStream App installation token) and why scoping to
contents: read does not affect any feature.

Covers:
- docs/downloads/gitstream.yml
- docs/downloads/gitstream-lite.yml
- docs/github-installation.md (inline snippets + new section)
- docs/troubleshooting.md (dependabot + lite snippets)
- tutorials/basic-usage-python-repo/.github/workflows/gitstream.yml
- .github/workflows/gitstream.yml (dogfood)

Follows https://github.blog/changelog/2021-04-20-github-actions-control-permissions-for-github_token/

* chore: retrigger CI

Author: MishaKav

.github/workflows/gitstream.yml

@@ -30,9 +30,12 @@ on:
         required: false
         default: ''
 
+permissions:
+  contents: read
+
 jobs:
   gitStream:
-    timeout-minutes: 5
+    timeout-minutes: 15
     runs-on: ubuntu-latest
     name: gitStream workflow automation
     steps:

docs/downloads/gitstream-lite.yml

@@ -30,6 +30,9 @@ on:
         required: false
         default: ''
 
+permissions:
+  contents: read
+
 jobs:
   gitStream:
     timeout-minutes: 15

docs/downloads/gitstream.yml

@@ -30,6 +30,9 @@ on:
         required: false
         default: ''
 
+permissions:
+  contents: read
+
 jobs:
   gitStream:
     timeout-minutes: 15

docs/github-installation.md

@@ -68,6 +68,9 @@ You can set up gitStream for a single repo or your entire GitHub organization. S
             If you're working with a large repository (typically monorepos) and experience timeout issues during GitHub Actions execution, you can use the lite version of gitStream that performs a shallow clone to reduce execution time:
 
             ```yaml
+            permissions:
+              contents: read
+
             jobs:
               gitStream:
                 timeout-minutes: 15
@@ -135,6 +138,9 @@ You can set up gitStream for a single repo or your entire GitHub organization. S
             If you're working with large repositories in your organization (typically monorepos) and experience timeout issues during GitHub Actions execution, you can use the lite version of gitStream that performs a shallow clone to reduce execution time:
 
             ```yaml
+            permissions:
+              contents: read
+
             jobs:
               gitStream:
                 timeout-minutes: 15
@@ -186,6 +192,25 @@ You can set up gitStream for a single repo or your entire GitHub organization. S
 | Read and write access to actions, checks, pull requests, and workflows | Trigger workflows, create and update pull requests and their checks, and modify workflow files |
 | User email | Used to identify users |
 
+### Hardening the Workflow `GITHUB_TOKEN`
+
+The generated `.github/workflows/gitstream.yml` declares an explicit `permissions:` block that scopes the workflow's built-in `GITHUB_TOKEN` to the minimum required:
+
+```yaml
+permissions:
+  contents: read
+```
+
+This follows GitHub's [least-privilege guidance for `GITHUB_TOKEN`](https://github.blog/changelog/2021-04-20-github-actions-control-permissions-for-github_token/). All remaining scopes default to `none` once any key is set.
+
+!!! info "Why `contents: read` is sufficient"
+    The gitStream action uses two distinct tokens:
+
+    - **`GITHUB_TOKEN`** (built into the workflow runner) — used only to clone the repository via `actions/checkout`. Needs `contents: read` on private repos.
+    - **gitStream App installation token** — passed through `client_payload` and used by the action for all PR comments, labels, approvals, and checks. Governed by the **GitHub App permissions** documented above, independent of the workflow `permissions:` block.
+
+    Scoping `GITHUB_TOKEN` down to `contents: read` does not affect any gitStream feature — writes flow through the App token.
+
 ### Configure gitStream to Block Merges <a name="github-merge-block"></a>
 You can configure GitHub to require gitStream checks to pass before PRs can be merged using [branch protection rules](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/about-protected-branches).
 
@@ -221,6 +246,9 @@ Follow these steps to ensure gitStream runs on self-hosted GitHub Actions runner
     - Modify the gitStream GitHub Actions workflow file (`.github/workflows/gitstream.yml`) to specify self-hosted runners:
 
     ```yaml
+    permissions:
+      contents: read
+
     jobs:
       gitStream:
         runs-on: self-hosted

docs/troubleshooting.md

@@ -95,10 +95,13 @@ When using repository level rules, you can edit the `.github/workflows/gitstream
 
     This will not work for org level rules
 
-```yaml+jinja title=".github/workflows/gitstream.yml" hl_lines="5"
+```yaml+jinja title=".github/workflows/gitstream.yml" hl_lines="8"
+permissions:
+  contents: read
+
 jobs:
   gitStream:
-    timeout-minutes: 5
+    timeout-minutes: 15
     # uncomment this condition, if you don't want any automation on dependabot PRs
     if: github.actor != 'dependabot[bot]'
     runs-on: ubuntu-latest
@@ -180,6 +183,9 @@ If you're experiencing timeout issues during GitHub Actions execution, particula
 You can resolve this by using the **lite version** of the gitStream GitHub Action, which performs a shallow clone to reduce execution time:
 
 ```yaml
+permissions:
+  contents: read
+
 jobs:
   gitStream:
     timeout-minutes: 15

tutorials/basic-usage-python-repo/.github/workflows/gitstream.yml

@@ -28,9 +28,12 @@ on:
           required: false
           default: ''
 
+permissions:
+  contents: read
+
 jobs:
   gitStream:
-    timeout-minutes: 5
+    timeout-minutes: 15
     # uncomment this condition, if you dont want any automation on dependabot PRs
     # if: github.actor != 'dependabot[bot]'
     runs-on: ubuntu-latest