From 4b624e8dc6ed8c71edac664fc0b60150839bc8ea Mon Sep 17 00:00:00 2001 From: Misha Kav Date: Mon, 20 Apr 2026 13:38:47 +0300 Subject: [PATCH 1/2] 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/ --- .github/workflows/gitstream.yml | 5 +++- docs/downloads/gitstream-lite.yml | 3 ++ docs/downloads/gitstream.yml | 3 ++ docs/github-installation.md | 28 +++++++++++++++++++ docs/troubleshooting.md | 10 +++++-- .../.github/workflows/gitstream.yml | 5 +++- 6 files changed, 50 insertions(+), 4 deletions(-) diff --git a/.github/workflows/gitstream.yml b/.github/workflows/gitstream.yml index 825494f2a..52752687f 100644 --- a/.github/workflows/gitstream.yml +++ b/.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: diff --git a/docs/downloads/gitstream-lite.yml b/docs/downloads/gitstream-lite.yml index d5f6b8e02..f70b8034d 100644 --- a/docs/downloads/gitstream-lite.yml +++ b/docs/downloads/gitstream-lite.yml @@ -30,6 +30,9 @@ on: required: false default: '' +permissions: + contents: read + jobs: gitStream: timeout-minutes: 15 diff --git a/docs/downloads/gitstream.yml b/docs/downloads/gitstream.yml index 06b5271ce..0246c80cd 100644 --- a/docs/downloads/gitstream.yml +++ b/docs/downloads/gitstream.yml @@ -30,6 +30,9 @@ on: required: false default: '' +permissions: + contents: read + jobs: gitStream: timeout-minutes: 15 diff --git a/docs/github-installation.md b/docs/github-installation.md index 164f28c8c..bd4724c74 100644 --- a/docs/github-installation.md +++ b/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 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 diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 46f72b81d..964bc8092 100644 --- a/docs/troubleshooting.md +++ b/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 diff --git a/tutorials/basic-usage-python-repo/.github/workflows/gitstream.yml b/tutorials/basic-usage-python-repo/.github/workflows/gitstream.yml index 4457e9e28..c4b82b5e0 100644 --- a/tutorials/basic-usage-python-repo/.github/workflows/gitstream.yml +++ b/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 From 1e675ce74b92cb0251ae3fe61b0d5e610964b667 Mon Sep 17 00:00:00 2001 From: Misha Kav Date: Mon, 20 Apr 2026 17:43:56 +0300 Subject: [PATCH 2/2] chore: retrigger CI