ci: document permissions

Author: rjaegers

.github/workflows/linting-formatting.yml

@@ -22,7 +22,7 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       contents: read
-      actions: read
+      actions: read # is needed by zizmorcore/zizmor-action
       pull-requests: write # is needed by oxsecurity/megalinter and reviewdog/action-suggester to post PR comments
       security-events: write # is needed by oxsecurity/megalinter for uploading sarif files
     steps:

.github/workflows/release-build.yml

@@ -124,10 +124,9 @@ jobs:
     name: 📄 Upload Documents
     runs-on: ubuntu-latest
     permissions:
-      # `contents: write` is needed to modify a release.
       # Please note that this is an overly broad scope, but GitHub does not
       # currently provide a more fine-grained permission for release modification.
-      contents: write
+      contents: write # is needed to modify a release
     needs: [build-push-test]
     steps:
       - uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # v5.0.0

.github/workflows/update-dependencies.yml

@@ -19,8 +19,8 @@ jobs:
     # set-up correctly.
     container: ghcr.io/philips-software/amp-devcontainer-${{ matrix.flavor }}:edge
     permissions:
-      contents: write
-      pull-requests: write
+      contents: write # is needed by peter-evans/create-pull-request to create branches and push commits
+      pull-requests: write # is needed by peter-evans/create-pull-request to create a PR
     steps:
       - uses: step-security/harden-runner@f4a75cfd619ee5ce8d5b864b0d183aff3c69b55a # v2.13.1
         with:
@@ -53,8 +53,8 @@ jobs:
         flavor: ["cpp", "rust"]
         file: ["devcontainer-metadata.json", "devcontainer.json"]
     permissions:
-      contents: write
-      pull-requests: write
+      contents: write # is needed by peter-evans/create-pull-request to create branches and push commits
+      pull-requests: write # is needed by peter-evans/create-pull-request to create a PR
     steps:
       - uses: step-security/harden-runner@f4a75cfd619ee5ce8d5b864b0d183aff3c69b55a # v2.13.1
         with:

.github/workflows/wc-build-push.yml

@@ -65,7 +65,7 @@ jobs:
     needs: sanitize-image-name
     permissions:
       contents: read
-      packages: write
+      packages: write # is needed by docker/build-push-action to push images to GitHub Container Registry
     steps:
       - uses: step-security/harden-runner@f4a75cfd619ee5ce8d5b864b0d183aff3c69b55a # v2.13.1
         with:

.github/workflows/wc-dependency-review.yml

@@ -24,7 +24,7 @@ jobs:
     runs-on: ${{ fromJson(inputs.runner-labels) }}
     permissions:
       contents: read
-      pull-requests: write
+      pull-requests: write # is needed by actions/dependency-review-action to write PR summaries
     steps:
       - uses: step-security/harden-runner@f4a75cfd619ee5ce8d5b864b0d183aff3c69b55a # v2.13.1
         with: