docs: add required permissions to all caller examples in README

Add explicit permissions blocks to all 17 usage examples and the
generic template in the README. Also add a note in the Limitations
section explaining that reusable workflows can only restrict
GITHUB_TOKEN permissions, not escalate them.

Co-Authored-By: OpenCode <noreply@opencode.ai>

Author: 0x46616c6b

README.md

@@ -14,6 +14,7 @@ on: ...
 jobs:
   <action name>:
     uses: Staffbase/gha-workflows/.github/workflows/template_*.yml@v11.0.1
+    permissions: ...  # see individual examples below
     with: ...
 ```
 
@@ -42,6 +43,7 @@ on:
 jobs:
   dependabot:
     uses: Staffbase/gha-workflows/.github/workflows/template_automerge_dependabot.yml@v11.0.1
+    permissions: {}
     with:
       # optional: ⚠️ only enable the force merge if you want to do the merge just now
       force: true
@@ -77,6 +79,8 @@ on:
 jobs:
   autodev:
     uses: Staffbase/gha-workflows/.github/workflows/template_autodev.yml@v11.0.1
+    permissions:
+      contents: read
     with:
       # optional: base branch from which the history originates, default: main
       base: master
@@ -121,6 +125,9 @@ on:
 jobs:
   changeset-check:
     uses: Staffbase/gha-workflows/.github/workflows/template_changeset_check.yml@v11.0.1
+    permissions:
+      contents: read
+      pull-requests: write
 ```
 
 </details>
@@ -143,6 +150,8 @@ on:
 jobs:
   changeset-release:
     uses: Staffbase/gha-workflows/.github/workflows/template_changeset_release.yml@v11.0.1
+    permissions:
+      contents: read
     with:
       # optional: The file containing the Node.js version to use, defaults to .nvmrc
       node-version-file: '.node-version'
@@ -181,6 +190,7 @@ on:
 jobs:
   flaky-tests:
     uses: Staffbase/gha-workflows/.github/workflows/template_flaky_tests.yml@v11.0.1
+    permissions: {}
     with:
       # identifier for the slack channel
       slack-channel-id: 45678787976
@@ -215,6 +225,8 @@ on: [push]
 jobs:
   gitops:
     uses: Staffbase/gha-workflows/.github/workflows/template_gitops.yml@v11.0.1
+    permissions:
+      contents: read
     with:
       # optional: host of the docker registry, default: "registry.staffbase.com"
       docker-registry: '<your-registry>'
@@ -302,6 +314,8 @@ on:
 jobs:
   jira_annotate:
     uses: Staffbase/gha-workflows/.github/workflows/template_jira_tagging.yml@v11.0.1
+    permissions:
+      contents: read
     with:
       # optional: name of the service to add as label, default: name of the repository
       name: 'component name'
@@ -335,6 +349,8 @@ on:
 jobs:
   ld_code_references:
     uses: Staffbase/gha-workflows/.github/workflows/template_launchdarkly_code_references.yml@v11.0.1
+    permissions:
+      contents: read
     with:
       # optional: key of the LD project, default: default
       project-key: 'my-project'
@@ -360,6 +376,8 @@ on:
 jobs:
   block:
     uses: Staffbase/gha-workflows/.github/workflows/template_merge_block.yml@v11.0.1
+    permissions:
+      pull-requests: write
     with:
       # optional: name of the label if the PR should not be merged, default: do not merge
       label: merge block
@@ -388,6 +406,9 @@ on:
 jobs:
   update_release_draft:
     uses: Staffbase/gha-workflows/.github/workflows/template_release_drafter.yml@v11.0.1
+    permissions:
+      contents: write
+      pull-requests: read
     with:
       # optional: name of the release drafter configuration file, default: release-drafter.yml
       config-name: release-drafter-test.yml
@@ -433,6 +454,8 @@ on:
 jobs:
   new_version:
     uses: Staffbase/gha-workflows/.github/workflows/template_release_version.yml@v11.0.1
+    permissions:
+      contents: read
     with:
       # optional: prefix of the tag in order to find the last release; this is useful for multi artifact/service repositories, default: 'v'
       tag-prefix: 'app-v'
@@ -468,6 +491,8 @@ on: [pull_request]
 jobs:
   trufflehog:
     uses: Staffbase/gha-workflows/.github/workflows/template_secret_scan.yml@v11.0.1
+    permissions:
+      contents: read
 ```
 
 </details>
@@ -487,6 +512,10 @@ on:
 jobs:
   stale:
     uses: Staffbase/gha-workflows/.github/workflows/template_stale.yml@v11.0.1
+    permissions:
+      contents: write
+      pull-requests: write
+      issues: write
     with:
       # optional: comment on the stale pull request while closed, default: This stale PR was closed because there was no activity.
       close-pr-message: your message
@@ -524,6 +553,8 @@ on:
 jobs:
   techdocs:
     uses: Staffbase/gha-workflows/.github/workflows/template_techdocs_monorepo.yml@v11.0.1
+    permissions:
+      contents: read
     secrets:
       # required: specifies an Azure Storage account name
       azure-account-name: ${{ vars.TECHDOCS_AZURE_ACCOUNT_NAME }}
@@ -553,6 +584,8 @@ on:
 jobs:
   techdocs:
     uses: Staffbase/gha-workflows/.github/workflows/template_techdocs.yml@v11.0.1
+    permissions:
+      contents: read
     with:
       # optional: kind of the Backstage entity, default: Component
       # ref: https://backstage.io/docs/features/software-catalog/descriptor-format#contents
@@ -583,6 +616,9 @@ on: [pull_request]
 jobs:
   terraform:
     uses: Staffbase/gha-workflows/.github/workflows/template_terraform_format.yml@v11.0.1
+    permissions:
+      contents: read
+      pull-requests: write
     with:
       # optional: Terraform version, default: latest
       terraform-version: latest
@@ -616,6 +652,9 @@ on:
 jobs:
   yamllint:
     uses: Staffbase/gha-workflows/.github/workflows/template_yaml.yml@v11.0.1
+    permissions:
+      contents: read
+      checks: write
     with:
       # optional: name of the running action, default: yamllint / yamllint
       action-name: your name
@@ -631,6 +670,8 @@ With the current implementation of the reusable workflows from GitHub, we have s
 
 - It isn't possible to [access environment variables][reusable-workflow-env] and [secrets][reusable-workflow-secrets], so it's necessary to pass them to the workflow. But we don't want to do it for all secrets.
 
+- Reusable workflows can only restrict `GITHUB_TOKEN` permissions, not escalate them. The calling workflow must grant at least the permissions required by the reusable workflow. All examples above include the minimum required `permissions` for each workflow. For more details, see the [GitHub documentation][reusable-workflow-permissions].
+
 There are also some [further limitations][further-limitations] if you want to use the `GITHUB_TOKEN`.
 
 ## Release 🔖
@@ -662,4 +703,5 @@ This project is licensed under the Apache-2.0 License - see the [LICENSE.md](LIC
 [release-new]: https://github.com/Staffbase/gha-workflows/releases
 [reusable-workflow-secrets]: https://github.com/orgs/community/discussions/17554
 [reusable-workflow-env]: https://github.com/orgs/community/discussions/26671
+[reusable-workflow-permissions]: https://docs.github.com/en/actions/sharing-automations/reusing-workflows#supported-keywords-for-jobs-that-call-a-reusable-workflow
 [further-limitations]: https://docs.github.com/en/actions/security-guides/automatic-token-authentication#using-the-github_token-in-a-workflow