chore(ci): annotate all permissions with reason and action name [SEC-58]

lvrach · claude · lvrach · commit f88a7e617f1a · 2026-02-10T13:10:37.000+01:00
Add inline comments to every job-level permissions entry explaining
why the permission is needed and which action/step requires it.

Co-Authored-By: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/.github/workflows/build-pr-artifacts.yml b/.github/workflows/build-pr-artifacts.yml
@@ -16,7 +16,7 @@ jobs:
     runs-on: ubuntu-latest
     name: Generate Tag Names
     permissions:
-      contents: read
+      contents: read # to checkout repository code (actions/checkout)
     # Skip for the release pull requests as staging artifacts will be generated
     if: startsWith(github.event.pull_request.head.ref, 'release/') != true && startsWith(github.event.pull_request.head.ref, 'hotfix-release/') != true && github.event.pull_request.head.ref != 'main'
     outputs:
@@ -48,8 +48,8 @@ jobs:
   build-transformer-image:
     name: Build Transformer Docker Image - PR
     permissions:
-      id-token: write
-      contents: read
+      id-token: write # to pass OIDC token to reusable workflow (build-push-docker-image.yml)
+      contents: read # to checkout repository code and call reusable workflow (actions/checkout)
     # Skip for the release pull requests as staging artifacts will be generated
     # Skip main to develop sync pull requests
     if: startsWith(github.event.pull_request.head.ref, 'release/') != true && startsWith(github.event.pull_request.head.ref, 'hotfix-release/') != true && github.event.pull_request.head.ref != 'main'
@@ -68,8 +68,8 @@ jobs:
   build-user-transformer-image:
     name: Build User Transformer Docker Image - PR
     permissions:
-      id-token: write
-      contents: read
+      id-token: write # to pass OIDC token to reusable workflow (build-push-docker-image.yml)
+      contents: read # to checkout repository code and call reusable workflow (actions/checkout)
     # Skip for the release pull requests as staging artifacts will be generated
     if: startsWith(github.event.pull_request.head.ref, 'release/') != true && startsWith(github.event.pull_request.head.ref, 'hotfix-release/') != true && github.event.pull_request.head.ref != 'main'
     needs: [generate-tag-names]
@@ -87,7 +87,7 @@ jobs:
   run-ingestion-service-test:
     name: Run Ingestion Service Test
     permissions:
-      contents: read
+      contents: read # to call reusable workflow (ingestion-service-test.yml)
     needs: [build-transformer-image, generate-tag-names]
     uses: ./.github/workflows/ingestion-service-test.yml
     with:
diff --git a/.github/workflows/build-push-docker-image.yml b/.github/workflows/build-push-docker-image.yml
@@ -42,7 +42,7 @@ jobs:
     runs-on: ubuntu-latest
     name: Check if actor is dependabot
     permissions:
-      contents: read
+      contents: read # minimum required permission for job execution
     outputs:
       is_dependabot: ${{ steps.check.outputs.is_dependabot }}
     steps:
@@ -66,7 +66,7 @@ jobs:
     runs-on: ubuntu-latest
     name: Get SHA information
     permissions:
-      contents: read
+      contents: read # minimum required permission for job execution
     outputs:
       sha: ${{steps.getSHA.outputs.SHA}}
     steps:
@@ -90,7 +90,7 @@ jobs:
     runs-on: ubuntu-latest
     name: Get Changed files
     permissions:
-      contents: read
+      contents: read # to checkout repository code and list changed files (actions/checkout, Ana06/get-changed-files)
     outputs:
       should_execute_tests: ${{ steps.processing.outputs.should_execute_tests }}
     steps:
@@ -125,8 +125,8 @@ jobs:
   build-images:
     name: Build Docker Images
     permissions:
-      id-token: write
-      contents: read
+      id-token: write # for AWS OIDC authentication (aws-actions/configure-aws-credentials)
+      contents: read # to checkout repository code (actions/checkout)
     needs: [check_actor, get_sha, get_changed_files]
     strategy:
       matrix:
@@ -224,8 +224,8 @@ jobs:
     name: Create multi-arch manifest for ECR
     runs-on: ubuntu-latest
     permissions:
-      id-token: write
-      contents: read
+      id-token: write # for AWS OIDC authentication (aws-actions/configure-aws-credentials)
+      contents: read # minimum required permission for job execution
     needs: [build-images, check_actor]
     if: ${{ needs.check_actor.outputs.is_dependabot == 'false' }}
     steps:
@@ -264,7 +264,7 @@ jobs:
     name: Create multi-arch manifest for DockerHub
     runs-on: ubuntu-latest
     permissions:
-      contents: read
+      contents: read # minimum required permission for job execution
     needs: [build-images, check_actor]
     if: ${{ needs.check_actor.outputs.is_dependabot == 'false' }}
     steps:
diff --git a/.github/workflows/check-pr-title.yml b/.github/workflows/check-pr-title.yml
@@ -17,7 +17,7 @@ jobs:
     name: Check PR Title
     runs-on: ubuntu-latest
     permissions:
-      pull-requests: read
+      pull-requests: read # to read PR title for validation (rudderlabs/github-action-check-pr-title)
     steps:
       - name: Harden the runner (Audit all outbound calls)
         uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
diff --git a/.github/workflows/commitlint.yml b/.github/workflows/commitlint.yml
@@ -10,7 +10,7 @@ jobs:
   commitlint:
     runs-on: ubuntu-latest
     permissions:
-      contents: read
+      contents: read # to checkout repository code with full history (actions/checkout)
     steps:
       - name: Harden the runner (Audit all outbound calls)
         uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
diff --git a/.github/workflows/create-hotfix-branch.yml b/.github/workflows/create-hotfix-branch.yml
@@ -10,7 +10,7 @@ on:
 jobs:
   validate-actor:
     permissions:
-      contents: read
+      contents: read # to call reusable workflow (validate-actor.yml)
     uses: ./.github/workflows/validate-actor.yml
     with:
       team_names: 'integrations,data-management'
@@ -23,7 +23,7 @@ jobs:
     needs: validate-actor
 
     permissions:
-      contents: read
+      contents: read # to read repo metadata; branch creation uses app token (create-github-app-token)
 
     # Only allow these users to create new hotfix branch from 'main'
     if: github.ref == 'refs/heads/main'
diff --git a/.github/workflows/draft-new-release.yml b/.github/workflows/draft-new-release.yml
@@ -5,7 +5,7 @@ on: workflow_dispatch
 jobs:
   validate-actor:
     permissions:
-      contents: read
+      contents: read # to call reusable workflow (validate-actor.yml)
     uses: ./.github/workflows/validate-actor.yml
     with:
       team_names: 'integrations,data-management'
@@ -18,7 +18,7 @@ jobs:
     needs: validate-actor
 
     permissions:
-      contents: read
+      contents: read # to checkout repository code; writes use app token (create-github-app-token)
 
     # Only allow release stakeholders to initiate releases
     if: (github.ref == 'refs/heads/develop' || startsWith(github.ref, 'refs/heads/hotfix/'))
diff --git a/.github/workflows/dt-test-and-report-code-coverage.yml b/.github/workflows/dt-test-and-report-code-coverage.yml
@@ -15,7 +15,7 @@ jobs:
   get_workflow_url:
     runs-on: ubuntu-latest
     permissions:
-      contents: read
+      contents: read # minimum required permission for job execution
     steps:
       - name: Harden the runner (Audit all outbound calls)
         uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
@@ -33,7 +33,7 @@ jobs:
     name: Code Coverage
     runs-on: ubuntu-latest
     permissions:
-      contents: read
+      contents: read # to checkout repository code with full history (actions/checkout)
     needs: [get_workflow_url]
     outputs:
       tests_run_outcome: ${{steps.run_tests.outcome}}
@@ -100,7 +100,7 @@ jobs:
   notify:
     name: slack notification on failure
     permissions:
-      contents: read
+      contents: read # to call reusable workflow (slack-notify.yml)
     needs: [get_workflow_url, coverage]
     if: needs.coverage.outputs.tests_run_outcome == 'failure' || failure()
     uses: ./.github/workflows/slack-notify.yml
diff --git a/.github/workflows/housekeeping.yml b/.github/workflows/housekeeping.yml
@@ -12,8 +12,8 @@ jobs:
     runs-on: ubuntu-latest
 
     permissions:
-      pull-requests: write
-      issues: write
+      pull-requests: write # to label and close stale PRs (actions/stale)
+      issues: write # to label and close stale issues (actions/stale)
 
     steps:
       - name: Harden the runner (Audit all outbound calls)
@@ -39,7 +39,7 @@ jobs:
     runs-on: ubuntu-latest
 
     permissions:
-      contents: write
+      contents: write # to delete stale branches (beatlabs/delete-old-branches-action)
 
     steps:
       - name: Harden the runner (Audit all outbound calls)
diff --git a/.github/workflows/ingestion-service-test.yml b/.github/workflows/ingestion-service-test.yml
@@ -18,7 +18,7 @@ jobs:
     runs-on: ubuntu-latest
 
     permissions:
-      contents: read
+      contents: read # to checkout repository code (actions/checkout)
     env:
       GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       TRANSFORMER_IMAGE_NAME_FOR_TEST: ${{ inputs.build_tag }}
diff --git a/.github/workflows/integrations_version_audit.yml b/.github/workflows/integrations_version_audit.yml
@@ -10,7 +10,7 @@ jobs:
     name: Run Integration Version Audit
     runs-on: ubuntu-latest
     permissions:
-      contents: read
+      contents: read # to checkout repository code (actions/checkout)
 
     steps:
       - name: Harden the runner (Audit all outbound calls)
diff --git a/.github/workflows/prepare-for-dev-deploy.yml b/.github/workflows/prepare-for-dev-deploy.yml
@@ -14,7 +14,7 @@ jobs:
     runs-on: ubuntu-latest
     name: Generate Tag Names
     permissions:
-      contents: read
+      contents: read # to checkout repository code (actions/checkout)
     outputs:
       tag_name: ${{ steps.gen_tag_names.outputs.tag_name }}
       tag_name_ut: ${{ steps.gen_tag_names.outputs.tag_name_ut }}
@@ -43,8 +43,8 @@ jobs:
   build-transformer-image:
     name: Build Transformer Docker Image - Dev
     permissions:
-      id-token: write
-      contents: read
+      id-token: write # to pass OIDC token to reusable workflow (build-push-docker-image.yml)
+      contents: read # to checkout repository code and call reusable workflow (actions/checkout)
     needs: [generate-tag-names]
     uses: ./.github/workflows/build-push-docker-image.yml
     with:
@@ -61,8 +61,8 @@ jobs:
   build-user-transformer-image:
     name: Build User Transformer Docker Image - Dev
     permissions:
-      id-token: write
-      contents: read
+      id-token: write # to pass OIDC token to reusable workflow (build-push-docker-image.yml)
+      contents: read # to checkout repository code and call reusable workflow (actions/checkout)
     needs: [generate-tag-names]
     uses: ./.github/workflows/build-push-docker-image.yml
     with:
@@ -79,8 +79,8 @@ jobs:
     name: Restart K8s Deployment
     runs-on: ubuntu-latest
     permissions:
-      id-token: write
-      contents: read
+      id-token: write # for AWS OIDC authentication (restart-deployment action uses aws-actions/configure-aws-credentials)
+      contents: read # to checkout repository code and local action (actions/checkout)
     needs: [generate-tag-names, build-transformer-image]
     steps:
       - name: Harden the runner (Audit all outbound calls)
@@ -105,8 +105,8 @@ jobs:
     name: Restart K8s Deployment
     runs-on: ubuntu-latest
     permissions:
-      id-token: write
-      contents: read
+      id-token: write # for AWS OIDC authentication (restart-deployment action uses aws-actions/configure-aws-credentials)
+      contents: read # to checkout repository code and local action (actions/checkout)
     needs: [generate-tag-names, build-transformer-image]
     steps:
       - name: Harden the runner (Audit all outbound calls)
diff --git a/.github/workflows/prepare-for-prod-dt-deploy.yml b/.github/workflows/prepare-for-prod-dt-deploy.yml
@@ -14,7 +14,7 @@ jobs:
     runs-on: ubuntu-latest
     name: Generate Tag Names
     permissions:
-      contents: read
+      contents: read # to checkout repository code and read package.json (actions/checkout)
     outputs:
       tag_name: ${{ steps.gen_tag_names.outputs.tag_name }}
       tag_name_ut: ${{ steps.gen_tag_names.outputs.tag_name_ut }}
@@ -39,8 +39,8 @@ jobs:
   build-transformer-image:
     name: Build Transformer Docker Image - Prod
     permissions:
-      id-token: write
-      contents: read
+      id-token: write # to pass OIDC token to reusable workflow (build-push-docker-image.yml)
+      contents: read # to checkout repository code and call reusable workflow (actions/checkout)
     needs: [generate-tag-names]
     uses: ./.github/workflows/build-push-docker-image.yml
     with:
@@ -62,7 +62,7 @@ jobs:
     needs: [generate-tag-names, build-transformer-image]
 
     permissions:
-      contents: read
+      contents: read # to checkout repository code; cross-repo writes use app token (create-github-app-token)
 
     env:
       TAG_NAME: ${{ needs.generate-tag-names.outputs.tag_name }}
diff --git a/.github/workflows/prepare-for-prod-rollback.yml b/.github/workflows/prepare-for-prod-rollback.yml
@@ -6,7 +6,7 @@ on:
 jobs:
   validate-actor:
     permissions:
-      contents: read
+      contents: read # to call reusable workflow (validate-actor.yml)
     uses: ./.github/workflows/validate-actor.yml
     with:
       team_names: 'integrations'
@@ -19,7 +19,7 @@ jobs:
     needs: validate-actor
 
     permissions:
-      contents: read
+      contents: read # to read repo metadata; cross-repo writes use app token (create-github-app-token)
 
     # Only allow to be deployed from tags and main branch
     if: (startsWith(github.ref, 'refs/tags/') || startsWith(github.ref, 'refs/heads/main'))
diff --git a/.github/workflows/prepare-for-prod-ut-deploy.yml b/.github/workflows/prepare-for-prod-ut-deploy.yml
@@ -14,7 +14,7 @@ jobs:
     runs-on: ubuntu-latest
     name: Generate Tag Names
     permissions:
-      contents: read
+      contents: read # to checkout repository code and read package.json (actions/checkout)
     outputs:
       tag_name_ut: ${{ steps.gen_tag_names.outputs.tag_name_ut }}
       tag_name: ${{ steps.gen_tag_names.outputs.tag_name }}
@@ -43,8 +43,8 @@ jobs:
   build-user-transformer-image:
     name: Build User Transformer Docker Image - Prod
     permissions:
-      id-token: write
-      contents: read
+      id-token: write # to pass OIDC token to reusable workflow (build-push-docker-image.yml)
+      contents: read # to checkout repository code and call reusable workflow (actions/checkout)
     needs: [generate-tag-names]
     uses: ./.github/workflows/build-push-docker-image.yml
     with:
@@ -66,7 +66,7 @@ jobs:
     needs: [generate-tag-names, build-user-transformer-image]
 
     permissions:
-      contents: read
+      contents: read # to checkout repository code; cross-repo writes use app token (create-github-app-token)
 
     env:
       UT_TAG_NAME: ${{ needs.generate-tag-names.outputs.tag_name_ut }}
diff --git a/.github/workflows/prepare-for-staging-deploy.yml b/.github/workflows/prepare-for-staging-deploy.yml
@@ -18,7 +18,7 @@ jobs:
     runs-on: ubuntu-latest
     name: Generate Tag Names
     permissions:
-      contents: read
+      contents: read # to checkout repository code and read package.json (actions/checkout)
     # Only pull requests from release candidate branches must trigger
     if: (startsWith(github.event.pull_request.head.ref, 'release/') || startsWith(github.event.pull_request.head.ref, 'hotfix-release/'))
     outputs:
@@ -49,8 +49,8 @@ jobs:
   build-transformer-image:
     name: Build Transformer Docker Image - Staging
     permissions:
-      id-token: write
-      contents: read
+      id-token: write # to pass OIDC token to reusable workflow (build-push-docker-image.yml)
+      contents: read # to checkout repository code and call reusable workflow (actions/checkout)
     # Only pull requests from release candidate branches must trigger
     if: (startsWith(github.event.pull_request.head.ref, 'release/') || startsWith(github.event.pull_request.head.ref, 'hotfix-release/'))
     needs: [generate-tag-names]
@@ -69,8 +69,8 @@ jobs:
   build-user-transformer-image:
     name: Build User Transformer Docker Image - Staging
     permissions:
-      id-token: write
-      contents: read
+      id-token: write # to pass OIDC token to reusable workflow (build-push-docker-image.yml)
+      contents: read # to checkout repository code and call reusable workflow (actions/checkout)
     # Only pull requests from release candidate branches must trigger
     if: (startsWith(github.event.pull_request.head.ref, 'release/') || startsWith(github.event.pull_request.head.ref, 'hotfix-release/'))
 
@@ -92,7 +92,7 @@ jobs:
     needs: [generate-tag-names, build-transformer-image, build-user-transformer-image]
 
     permissions:
-      contents: read
+      contents: read # to checkout repository code; cross-repo writes use app token (create-github-app-token)
 
     env:
       TF_IMAGE_REPOSITORY: ${{ vars.AWS_ECR_REGISTRY }}/rudderstack/rudder-transformer
diff --git a/.github/workflows/publish-new-release.yml b/.github/workflows/publish-new-release.yml
@@ -16,7 +16,7 @@ jobs:
     runs-on: ubuntu-latest
 
     permissions:
-      contents: read
+      contents: read # to checkout repository code; releases and tags use app token (create-github-app-token)
 
     if: (startsWith(github.event.pull_request.head.ref, 'release/') || startsWith(github.event.pull_request.head.ref, 'hotfix-release/')) && github.event.pull_request.merged == true # only merged pull requests must trigger this job
 
diff --git a/.github/workflows/slack-notify.yml b/.github/workflows/slack-notify.yml
diff --git a/.github/workflows/update-ingestion-service.yml b/.github/workflows/update-ingestion-service.yml
diff --git a/.github/workflows/ut-tests.yml b/.github/workflows/ut-tests.yml
diff --git a/.github/workflows/validate-actor.yml b/.github/workflows/validate-actor.yml
diff --git a/.github/workflows/verify-server-start.yml b/.github/workflows/verify-server-start.yml
diff --git a/.github/workflows/verify.yml b/.github/workflows/verify.yml
