workflows: document write permissions (#496418)

.github/workflows/backport.yml

@@ -11,8 +11,8 @@ on:
 
 permissions:
   contents: read
-  issues: write
-  pull-requests: write
+  issues: write # adding the 'has: port to stable' label
+  pull-requests: write # creating backport pull requests
 
 defaults:
   run:

.github/workflows/bot.yml

@@ -30,8 +30,8 @@ concurrency:
 # This is used as fallback without app only.
 # This happens when testing in forks without setting up that app.
 permissions:
-  issues: write
-  pull-requests: write
+  issues: write # managing issue labels and comments
+  pull-requests: write # managing pull request labels and comments
 
 defaults:
   run:

.github/workflows/check.yml

@@ -31,7 +31,7 @@ jobs:
   commits:
     if: inputs.baseBranch && inputs.headBranch
     permissions:
-      pull-requests: write
+      pull-requests: write # submitting PR reviews
     runs-on: ubuntu-slim
     timeout-minutes: 3
     steps:

.github/workflows/comment.yml

@@ -7,7 +7,7 @@ on:
 # This is used as fallback without app only.
 # This happens when testing in forks without setting up that app.
 permissions:
-  pull-requests: write
+  pull-requests: write # adding reactions to comments
 
 defaults:
   run:

.github/workflows/eval.yml

@@ -248,8 +248,8 @@ jobs:
     needs: [eval]
     if: ${{ !cancelled() && !failure() }}
     permissions:
-      pull-requests: write
-      statuses: write
+      pull-requests: write # submitting 'wrong branch' reviews
+      statuses: write # creating 'Eval Summary' commit statuses
     timeout-minutes: 5
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

.github/workflows/merge-group.yml

@@ -65,8 +65,7 @@ jobs:
     needs: [prepare]
     uses: ./.github/workflows/check.yml
     permissions:
-      # cherry-picks; formality right now, but unused
-      pull-requests: write
+      pull-requests: write # cherry-picks: unused in merge queue but required for check workflow
     secrets:
       CACHIX_AUTH_TOKEN_GHA: ${{ secrets.CACHIX_AUTH_TOKEN_GHA }}
     with:
@@ -90,9 +89,8 @@ jobs:
     # The eval workflow requests these permissions so we must explicitly allow them,
     # even though they are unused when working with the merge queue.
     permissions:
-      # compare
-      pull-requests: write
-      statuses: write
+      pull-requests: write # compare: unused in merge queue but required by eval workflow
+      statuses: write # compare: unused in merge queue but required by eval workflow
     secrets:
       CACHIX_AUTH_TOKEN_GHA: ${{ secrets.CACHIX_AUTH_TOKEN_GHA }}
     with:
@@ -125,7 +123,7 @@ jobs:
       - build
     runs-on: ubuntu-slim
     permissions:
-      statuses: write
+      statuses: write # creating 'no PR failures' commit status
     steps:
       - uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
         env:

.github/workflows/pull-request-target.yml

@@ -21,8 +21,7 @@ jobs:
   prepare:
     runs-on: ubuntu-slim
     permissions:
-      # wrong branch review comment
-      pull-requests: write
+      pull-requests: write # submitting 'wrong branch' reviews
     outputs:
       baseBranch: ${{ steps.prepare.outputs.base }}
       headBranch: ${{ steps.prepare.outputs.head }}

.github/workflows/review.yml

@@ -9,7 +9,7 @@ on:
 # This is used as fallback without app only.
 # This happens when testing in forks without setting up that app.
 permissions:
-  pull-requests: write
+  pull-requests: write # minimizing dismissed reviews and adding reactions
 
 defaults:
   run:

.github/workflows/test.yml

@@ -82,8 +82,8 @@ jobs:
     uses: ./.github/workflows/merge-group.yml
     # Those are actually only used on the merge_group event, but will throw an error if not set.
     permissions:
-      pull-requests: write
-      statuses: write
+      pull-requests: write # unused on pull_request, required by merge-group workflow
+      statuses: write # unused on pull_request, required by merge-group workflow
     with:
       artifact-prefix: mg-
       mergedSha: ${{ needs.prepare.outputs.mergedSha }}
@@ -96,9 +96,9 @@ jobs:
     uses: ./.github/workflows/pull-request-target.yml
     # Those are actually only used on the pull_request_target event, but will throw an error if not set.
     permissions:
-      issues: write
-      pull-requests: write
-      statuses: write
+      issues: write # unused on pull_request, required by bot workflow
+      pull-requests: write # unused on pull_request, required by PR workflow
+      statuses: write # unused on pull_request, required by PR workflow
     secrets:
       NIXPKGS_CI_APP_PRIVATE_KEY: ${{ secrets.NIXPKGS_CI_APP_PRIVATE_KEY }}
     with: