Merge branch 'develop' into feat/2348

Author: heitorlessa

.github/workflows/build_changelog.yml

@@ -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:

.github/workflows/codeql-analysis.yml

@@ -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

.github/workflows/dispatch_analytics.yml

@@ -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:
 

.github/workflows/label_pr_on_title.yml

@@ -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:
+      pull-requests: write  # label respective PR
     steps:
       - name: Checkout repository
         uses: actions/checkout@8e5e7e5ab8b370d6c329ec480221332ada57f0ab  # v3.5.2

.github/workflows/on_closed_issues.yml

@@ -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.

.github/workflows/on_label_added.yml

@@ -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

.github/workflows/on_merged_pr.yml

@@ -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,9 @@ 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
+      issues: write         # label issue with pending-release
     if: needs.get_pr_details.outputs.prIsMerged == 'true'
     steps:
       - uses: actions/checkout@8e5e7e5ab8b370d6c329ec480221332ada57f0ab  # v3.5.2

.github/workflows/on_opened_pr.yml

@@ -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"

.github/workflows/on_push_docs.yml

@@ -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: