Document the permissions blocks in CI workflows

.github/workflows/docs.yaml

@@ -50,7 +50,7 @@ jobs:
   pages-docs:
     name: GitHub Pages
     permissions:
-      contents: write
+      contents: write # needed to push the built docs to the gh-pages branch
     runs-on: ubuntu-latest
     needs:
       - pre

.github/workflows/latest_deps.yml

@@ -208,8 +208,8 @@ jobs:
       - complement
 
     permissions:
-      contents: read
-      issues: write
+      contents: read # needed to check out the issue template
+      issues: write # needed for opening/editing an issue upon build failure
 
     runs-on: ubuntu-latest
 

.github/workflows/push_complement_image.yml

@@ -33,7 +33,7 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       contents: read
-      packages: write
+      packages: write # needed to push the image to ghcr.io
     steps:
       - name: Checkout specific branch (debug build)
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0

.github/workflows/twisted_trunk.yml

@@ -181,8 +181,8 @@ jobs:
       - complement
 
     permissions:
-      contents: read
-      issues: write
+      contents: read # needed to check out the issue template
+      issues: write # needed for opening/editing an issue upon build failure
 
     runs-on: ubuntu-latest