aws-powertools · leandrodamascena · Jun 7, 2023 · Jun 5, 2023 · Jun 5, 2023 · Jun 5, 2023
@@ -1,6 +1,16 @@
 # Standalone workflow to update changelog if necessary
 name: Build changelog
 
+# PROCESS
+#
+# 1. Fetch latest changes compared to the latest tag
+# 2. Rebuild CHANGELOG.md using Keep A Changelog format
+# 3. Create a PR with the latest changelog (close and reference any it supersedes)
+
+# USAGE
+#
+# Always triggered on PR merge or manually from GitHub UI if we must.
+
 on:
   workflow_dispatch:
   push:

@@ -1,5 +1,15 @@
 name: "CodeQL"
 
+# PROCESS
+#
+# 1. Static code analysis with CodeQL
+
+# USAGE
+#
+# NOTE: This is our slowest workflow hence it only runs on code merged.
+#
+# Always triggered on PR merge when source code changes.
+
 on:
   push:
     paths:
@@ -11,6 +21,9 @@ jobs:
   analyze:
     name: Analyze
     runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+      actions: read
 
     strategy:
       fail-fast: false

@@ -1,5 +1,15 @@
 name: Dispatch analytics
 
+# PROCESS
+#
+# 1. Trade GitHub JWT token with AWS credentials for the analytics account
+# 2. Invoke a Lambda function dispatcher synchronously with the read-only scoped JWT token
+# 3. The dispatcher function will call GitHub APIs to read data from the last hour and aggregate for operational analytics
+
+# USAGE
+#
+# NOTE: meant to use as a scheduled task only (or manually for debugging purposes).
+
 on:
   workflow_dispatch:
 

@@ -1,5 +1,25 @@
 name: Label PR based on title
 
+# PROCESS
+#
+# 1. Fetch PR details previously saved from untrusted location
+# 2. Parse details for safety
+# 3. Label PR based on semantic title (e.g., area, change type)
+
+# USAGE
+#
+# NOTE: meant to be used with ./.github/workflows/record_pr.yml
+#
+# Security Note:
+#
+#   This workflow depends on "Record PR" workflow that runs in an untrusted location (forks) instead of `pull_request_target`.
+#   This enforces zero trust where "Record PR" workflow always runs on fork with zero permissions on GH_TOKEN.
+#   When "Record PR" completes, this workflow runs in our repository with the appropriate permissions and sanitize inputs.
+#
+#   Coupled with "Approve GitHub Action to run on forks", we have confidence no privilege can be escalated,
+#   since any malicious change would need to be approved, and upon social engineering, it'll have zero permissions.
+
+
 on:
   workflow_run:
     workflows: ["Record PR details"]
@@ -8,6 +28,8 @@ on:
 
 jobs:
   get_pr_details:
+    permissions:
+      actions: read  # download PR artifact
     # Guardrails to only ever run if PR recording workflow was indeed
     # run in a PR event and ran successfully
     if: ${{ github.event.workflow_run.conclusion == 'success' }}
@@ -20,6 +42,8 @@ jobs:
   label_pr:
     needs: get_pr_details
     runs-on: ubuntu-latest
+    permissions:
+      issues: write  # label respective PR
     steps:
       - name: Checkout repository
         uses: actions/checkout@8e5e7e5ab8b370d6c329ec480221332ada57f0ab  # v3.5.2

@@ -1,18 +1,30 @@
 name: Closed Issue Message
+
+# PROCESS
+#
+# 1. Comment on recently closed issues to warn future responses may not be looked after
+
+# USAGE
+#
+# Always triggered upon issue closure
+#
+
 on:
-    issues:
-        types: [closed]
+  issues:
+      types: [closed]
 jobs:
-    auto_comment:
-        runs-on: ubuntu-latest
-        steps:
-            - uses: aws-actions/closed-issue-message@8b6324312193476beecf11f8e8539d73a3553bf4
-              with:
-                  repo-token: "${{ secrets.GITHUB_TOKEN }}"
-                  message: |
-                      ### ⚠️COMMENT VISIBILITY WARNING⚠️
-                      This issue is now closed. Please be mindful that future comments are hard for our team to see.
+  auto_comment:
+      runs-on: ubuntu-latest
+      permissions:
+          issues: write  # comment on issues
+      steps:
+          - uses: aws-actions/closed-issue-message@8b6324312193476beecf11f8e8539d73a3553bf4
+            with:
+                repo-token: "${{ secrets.GITHUB_TOKEN }}"
+                message: |
+                    ### ⚠️COMMENT VISIBILITY WARNING⚠️
+                    This issue is now closed. Please be mindful that future comments are hard for our team to see.
 
-                      If you need more assistance, please either tag a [team member](https://github.com/awslabs/aws-lambda-powertools-python/blob/develop/MAINTAINERS.md#current-maintainers) or open a new issue that references this one.
+                    If you need more assistance, please either tag a [team member](https://github.com/awslabs/aws-lambda-powertools-python/blob/develop/MAINTAINERS.md#current-maintainers) or open a new issue that references this one.
 
-                      If you wish to keep having a conversation with other community members under this issue feel free to do so.
+                    If you wish to keep having a conversation with other community members under this issue feel free to do so.
@@ -1,5 +1,24 @@
 name: On Label added
 
+# PROCESS
+#
+# 1. Fetch PR details previously saved from untrusted location
+# 2. Parse details for safety
+# 3. Comment on PR labels `size/XXL` and suggest splitting into smaller PRs if possible
+
+# USAGE
+#
+# NOTE: meant to be used with ./.github/workflows/record_pr.yml
+#
+# Security Note:
+#
+#   This workflow depends on "Record PR" workflow that runs in an untrusted location (forks) instead of `pull_request_target`.
+#   This enforces zero trust where "Record PR" workflow always runs on fork with zero permissions on GH_TOKEN.
+#   When "Record PR" completes, this workflow runs in our repository with the appropriate permissions and sanitize inputs.
+#
+#   Coupled with "Approve GitHub Action to run on forks", we have confidence no privilege can be escalated,
+#   since any malicious change would need to be approved, and upon social engineering, it'll have zero permissions.
+
 on:
   workflow_run:
     workflows: ["Record PR details"]
@@ -8,6 +27,8 @@ on:
 
 jobs:
   get_pr_details:
+    permissions:
+      actions: read  # download PR artifact
     if: ${{ github.event.workflow_run.conclusion == 'success' }}
     uses: ./.github/workflows/reusable_export_pr_details.yml
     with:
@@ -16,12 +37,11 @@ jobs:
     secrets:
       token: ${{ secrets.GITHUB_TOKEN }}
 
-  split-large-pr:
+  split_large_pr:
     needs: get_pr_details
     runs-on: ubuntu-latest
     permissions:
-      issues: write
-      pull-requests: write
+      pull-requests: write  # comment on PR
     steps:
       - uses: actions/checkout@8e5e7e5ab8b370d6c329ec480221332ada57f0ab  # v3.5.2
       # Maintenance: Persist state per PR as an artifact to avoid spam on label add

@@ -1,5 +1,25 @@
 name: On PR merge
 
+# PROCESS
+#
+# 1. Fetch PR details previously saved from untrusted location
+# 2. Parse details for safety
+# 3. Add `pending-release` label for related issue
+# 4. Make a comment in PR if related issue is invalid or can't be labeled
+
+# USAGE
+#
+# NOTE: meant to be used with ./.github/workflows/record_pr.yml
+#
+# Security Note:
+#
+#   This workflow depends on "Record PR" workflow that runs in an untrusted location (forks) instead of `pull_request_target`.
+#   This enforces zero trust where "Record PR" workflow always runs on fork with zero permissions on GH_TOKEN.
+#   When "Record PR" completes, this workflow runs in our repository with the appropriate permissions and sanitize inputs.
+#
+#   Coupled with "Approve GitHub Action to run on forks", we have confidence no privilege can be escalated,
+#   since any malicious change would need to be approved, and upon social engineering, it'll have zero permissions.
+
 on:
   workflow_run:
     workflows: ["Record PR details"]
@@ -8,6 +28,8 @@ on:
 
 jobs:
   get_pr_details:
+    permissions:
+      actions: read  # download PR artifact
     if: github.event.workflow_run.event == 'pull_request' && github.event.workflow_run.conclusion == 'success'
     uses: ./.github/workflows/reusable_export_pr_details.yml
     with:
@@ -18,6 +40,8 @@ jobs:
   release_label_on_merge:
     needs: get_pr_details
     runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write  # make a comment in PR if unable to find related issue
     if: needs.get_pr_details.outputs.prIsMerged == 'true'
     steps:
       - uses: actions/checkout@8e5e7e5ab8b370d6c329ec480221332ada57f0ab  # v3.5.2

@@ -1,5 +1,25 @@
 name: On new PR
 
+# PROCESS
+#
+# 1. Fetch PR details previously saved from untrusted location
+# 2. Parse details for safety
+# 3. Confirm there is a related issue for newly opened PR
+# 4. Verify if PR template is used and legal acknowledgement hasn't been removed
+
+# USAGE
+#
+# NOTE: meant to be used with ./.github/workflows/record_pr.yml
+#
+# Security Note:
+#
+#   This workflow depends on "Record PR" workflow that runs in an untrusted location (forks) instead of `pull_request_target`.
+#   This enforces zero trust where "Record PR" workflow always runs on fork with zero permissions on GH_TOKEN.
+#   When "Record PR" completes, this workflow runs in our repository with the appropriate permissions and sanitize inputs.
+#
+#   Coupled with "Approve GitHub Action to run on forks", we have confidence no privilege can be escalated,
+#   since any malicious change would need to be approved, and upon social engineering, it'll have zero permissions.
+
 on:
   workflow_run:
     workflows: ["Record PR details"]
@@ -8,6 +28,8 @@ on:
 
 jobs:
   get_pr_details:
+    permissions:
+      actions: read  # download PR artifact
     if: ${{ github.event.workflow_run.conclusion == 'success' }}
     uses: ./.github/workflows/reusable_export_pr_details.yml
     with:
@@ -16,6 +38,8 @@ jobs:
     secrets:
       token: ${{ secrets.GITHUB_TOKEN }}
   check_related_issue:
+    permissions:
+      pull-requests: write  # label and comment on PR if missing related issue (requirement)
     needs: get_pr_details
     runs-on: ubuntu-latest
     steps:
@@ -35,6 +59,8 @@ jobs:
   check_acknowledge_section:
     needs: get_pr_details
     runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write  # label and comment on PR if missing acknowledge section (requirement)
     steps:
       - uses: actions/checkout@8e5e7e5ab8b370d6c329ec480221332ada57f0ab  # v3.5.2
       - name: "Ensure acknowledgement section is present"

@@ -1,5 +1,15 @@
 name: Docs
 
+# PROCESS
+#
+# 1. Build User Guide and API docs
+# 2. Publish to GitHub Pages
+# 3. Publish to S3 (new home)
+
+# USAGE
+#
+# Always triggered on PR merge when changes in documentation changes occur.
+
 on:
   push:
     branches:
@@ -10,15 +20,12 @@ on:
       - "examples/**"
       - "CHANGELOG.md"
 
-permissions:
-  id-token: write
-
 jobs:
   release-docs:
     permissions:
-      contents: write
-      pages: write
-      id-token: write
+      contents: write  # push to gh-pages
+      pages: write     # deploy gh-pages website
+      id-token: write  # trade JWT token for AWS credentials in AWS Docs account
     secrets: inherit
     uses: ./.github/workflows/reusable_publish_docs.yml
     with:

@@ -1,5 +1,31 @@
 name: Deploy v2 layer to all regions
 
+# PROCESS
+#
+# 1. Compile Layer using cdk-aws-lambda-powertools-layer CDK construct for x86 and ARM (uses custom runner as it's CPU heavy)
+# 2. Kick off pipeline for beta, prod, and canary releases
+# 3. Create PR to update trunk so staged docs also point to the latest Layer ARN, when merged
+# 4. Builds and publishes docs with latest Layer ARN using given version (generally coming from release)
+
+
+# USAGE
+#
+# NOTE: meant to be used with ./.github/workflows/release.yml
+#
+# publish_layer:
+#   needs: [seal, release, create_tag]
+#   secrets: inherit
+#   permissions:
+#     id-token: write
+#     contents: write
+#     pages: write
+#     pull-requests: write
+#   uses: ./.github/workflows/publish_v2_layer.yml
+#   with:
+#     latest_published_version: ${{ needs.seal.outputs.RELEASE_VERSION }}
+#     pre_release: ${{ inputs.pre_release }}
+
+
 on:
   workflow_dispatch:
     inputs:
@@ -91,7 +117,7 @@ jobs:
       id-token: write
       contents: read
       pages: write             # docs will be updated with latest Layer ARNs
-      pull-requests: write # creation-action will create a PR with Layer ARN updates
+      pull-requests: write     # creation-action will create a PR with Layer ARN updates
     uses: ./.github/workflows/reusable_deploy_v2_layer_stack.yml
     secrets: inherit
     with:
@@ -107,7 +133,7 @@ jobs:
       id-token: write
       contents: read
       pages: write             # docs will be updated with latest Layer ARNs
-      pull-requests: write # creation-action will create a PR with Layer ARN updates
+      pull-requests: write     # creation-action will create a PR with Layer ARN updates
     uses: ./.github/workflows/reusable_deploy_v2_layer_stack.yml
     secrets: inherit
     with:
@@ -133,7 +159,7 @@ jobs:
       package-version: ${{ inputs.latest_published_version }}
 
   sar-prod:
-    needs: [build-layer, sar-beta]
+    needs: [build-layer, beta, sar-beta]
     permissions:
       # lower privilege propagated from parent workflow (release.yml)
       id-token: write