Skip to content

Commit b99f65b

Browse files
heitorlessaheitorlessa
authored
chore(ci): document all github action workflows and enforce least-privilege (#2395)
1 parent d681d18 commit b99f65b

22 files changed

+383
-47
lines changed

‎.github/workflows/build_changelog.yml

+10
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,16 @@
11
# Standalone workflow to update changelog if necessary
22
name: Build changelog
33

4+
# PROCESS
5+
#
6+
# 1. Fetch latest changes compared to the latest tag
7+
# 2. Rebuild CHANGELOG.md using Keep A Changelog format
8+
# 3. Create a PR with the latest changelog (close and reference any it supersedes)
9+
10+
# USAGE
11+
#
12+
# Always triggered on PR merge or manually from GitHub UI if we must.
13+
414
on:
515
workflow_dispatch:
616
push:

‎.github/workflows/codeql-analysis.yml

+13
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,15 @@
11
name: "CodeQL"
22

3+
# PROCESS
4+
#
5+
# 1. Static code analysis with CodeQL
6+
7+
# USAGE
8+
#
9+
# NOTE: This is our slowest workflow hence it only runs on code merged.
10+
#
11+
# Always triggered on PR merge when source code changes.
12+
313
on:
414
push:
515
paths:
@@ -11,6 +21,9 @@ jobs:
1121
analyze:
1222
name: Analyze
1323
runs-on: ubuntu-latest
24+
permissions:
25+
security-events: write
26+
actions: read
1427

1528
strategy:
1629
fail-fast: false

‎.github/workflows/dispatch_analytics.yml

+10
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,15 @@
11
name: Dispatch analytics
22

3+
# PROCESS
4+
#
5+
# 1. Trade GitHub JWT token with AWS credentials for the analytics account
6+
# 2. Invoke a Lambda function dispatcher synchronously with the read-only scoped JWT token
7+
# 3. The dispatcher function will call GitHub APIs to read data from the last hour and aggregate for operational analytics
8+
9+
# USAGE
10+
#
11+
# NOTE: meant to use as a scheduled task only (or manually for debugging purposes).
12+
313
on:
414
workflow_dispatch:
515

‎.github/workflows/label_pr_on_title.yml

+24
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,25 @@
11
name: Label PR based on title
22

3+
# PROCESS
4+
#
5+
# 1. Fetch PR details previously saved from untrusted location
6+
# 2. Parse details for safety
7+
# 3. Label PR based on semantic title (e.g., area, change type)
8+
9+
# USAGE
10+
#
11+
# NOTE: meant to be used with ./.github/workflows/record_pr.yml
12+
#
13+
# Security Note:
14+
#
15+
# This workflow depends on "Record PR" workflow that runs in an untrusted location (forks) instead of `pull_request_target`.
16+
# This enforces zero trust where "Record PR" workflow always runs on fork with zero permissions on GH_TOKEN.
17+
# When "Record PR" completes, this workflow runs in our repository with the appropriate permissions and sanitize inputs.
18+
#
19+
# Coupled with "Approve GitHub Action to run on forks", we have confidence no privilege can be escalated,
20+
# since any malicious change would need to be approved, and upon social engineering, it'll have zero permissions.
21+
22+
323
on:
424
workflow_run:
525
workflows: ["Record PR details"]
@@ -8,6 +28,8 @@ on:
828

929
jobs:
1030
get_pr_details:
31+
permissions:
32+
actions: read # download PR artifact
1133
# Guardrails to only ever run if PR recording workflow was indeed
1234
# run in a PR event and ran successfully
1335
if: ${{ github.event.workflow_run.conclusion == 'success' }}
@@ -20,6 +42,8 @@ jobs:
2042
label_pr:
2143
needs: get_pr_details
2244
runs-on: ubuntu-latest
45+
permissions:
46+
issues: write # label respective PR
2347
steps:
2448
- name: Checkout repository
2549
uses: actions/checkout@8e5e7e5ab8b370d6c329ec480221332ada57f0ab # v3.5.2

‎.github/workflows/on_closed_issues.yml

+25-13
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,30 @@
11
name: Closed Issue Message
2+
3+
# PROCESS
4+
#
5+
# 1. Comment on recently closed issues to warn future responses may not be looked after
6+
7+
# USAGE
8+
#
9+
# Always triggered upon issue closure
10+
#
11+
212
on:
3-
issues:
4-
types: [closed]
13+
issues:
14+
types: [closed]
515
jobs:
6-
auto_comment:
7-
runs-on: ubuntu-latest
8-
steps:
9-
- uses: aws-actions/closed-issue-message@8b6324312193476beecf11f8e8539d73a3553bf4
10-
with:
11-
repo-token: "${{ secrets.GITHUB_TOKEN }}"
12-
message: |
13-
### ⚠️COMMENT VISIBILITY WARNING⚠️
14-
This issue is now closed. Please be mindful that future comments are hard for our team to see.
16+
auto_comment:
17+
runs-on: ubuntu-latest
18+
permissions:
19+
issues: write # comment on issues
20+
steps:
21+
- uses: aws-actions/closed-issue-message@8b6324312193476beecf11f8e8539d73a3553bf4
22+
with:
23+
repo-token: "${{ secrets.GITHUB_TOKEN }}"
24+
message: |
25+
### ⚠️COMMENT VISIBILITY WARNING⚠️
26+
This issue is now closed. Please be mindful that future comments are hard for our team to see.
1527
16-
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.
28+
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.
1729
18-
If you wish to keep having a conversation with other community members under this issue feel free to do so.
30+
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

+23-3
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,24 @@
11
name: On Label added
22

3+
# PROCESS
4+
#
5+
# 1. Fetch PR details previously saved from untrusted location
6+
# 2. Parse details for safety
7+
# 3. Comment on PR labels `size/XXL` and suggest splitting into smaller PRs if possible
8+
9+
# USAGE
10+
#
11+
# NOTE: meant to be used with ./.github/workflows/record_pr.yml
12+
#
13+
# Security Note:
14+
#
15+
# This workflow depends on "Record PR" workflow that runs in an untrusted location (forks) instead of `pull_request_target`.
16+
# This enforces zero trust where "Record PR" workflow always runs on fork with zero permissions on GH_TOKEN.
17+
# When "Record PR" completes, this workflow runs in our repository with the appropriate permissions and sanitize inputs.
18+
#
19+
# Coupled with "Approve GitHub Action to run on forks", we have confidence no privilege can be escalated,
20+
# since any malicious change would need to be approved, and upon social engineering, it'll have zero permissions.
21+
322
on:
423
workflow_run:
524
workflows: ["Record PR details"]
@@ -8,6 +27,8 @@ on:
827

928
jobs:
1029
get_pr_details:
30+
permissions:
31+
actions: read # download PR artifact
1132
if: ${{ github.event.workflow_run.conclusion == 'success' }}
1233
uses: ./.github/workflows/reusable_export_pr_details.yml
1334
with:
@@ -16,12 +37,11 @@ jobs:
1637
secrets:
1738
token: ${{ secrets.GITHUB_TOKEN }}
1839

19-
split-large-pr:
40+
split_large_pr:
2041
needs: get_pr_details
2142
runs-on: ubuntu-latest
2243
permissions:
23-
issues: write
24-
pull-requests: write
44+
pull-requests: write # comment on PR
2545
steps:
2646
- uses: actions/checkout@8e5e7e5ab8b370d6c329ec480221332ada57f0ab # v3.5.2
2747
# Maintenance: Persist state per PR as an artifact to avoid spam on label add

‎.github/workflows/on_merged_pr.yml

+24
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,25 @@
11
name: On PR merge
22

3+
# PROCESS
4+
#
5+
# 1. Fetch PR details previously saved from untrusted location
6+
# 2. Parse details for safety
7+
# 3. Add `pending-release` label for related issue
8+
# 4. Make a comment in PR if related issue is invalid or can't be labeled
9+
10+
# USAGE
11+
#
12+
# NOTE: meant to be used with ./.github/workflows/record_pr.yml
13+
#
14+
# Security Note:
15+
#
16+
# This workflow depends on "Record PR" workflow that runs in an untrusted location (forks) instead of `pull_request_target`.
17+
# This enforces zero trust where "Record PR" workflow always runs on fork with zero permissions on GH_TOKEN.
18+
# When "Record PR" completes, this workflow runs in our repository with the appropriate permissions and sanitize inputs.
19+
#
20+
# Coupled with "Approve GitHub Action to run on forks", we have confidence no privilege can be escalated,
21+
# since any malicious change would need to be approved, and upon social engineering, it'll have zero permissions.
22+
323
on:
424
workflow_run:
525
workflows: ["Record PR details"]
@@ -8,6 +28,8 @@ on:
828

929
jobs:
1030
get_pr_details:
31+
permissions:
32+
actions: read # download PR artifact
1133
if: github.event.workflow_run.event == 'pull_request' && github.event.workflow_run.conclusion == 'success'
1234
uses: ./.github/workflows/reusable_export_pr_details.yml
1335
with:
@@ -18,6 +40,8 @@ jobs:
1840
release_label_on_merge:
1941
needs: get_pr_details
2042
runs-on: ubuntu-latest
43+
permissions:
44+
pull-requests: write # make a comment in PR if unable to find related issue
2145
if: needs.get_pr_details.outputs.prIsMerged == 'true'
2246
steps:
2347
- uses: actions/checkout@8e5e7e5ab8b370d6c329ec480221332ada57f0ab # v3.5.2

‎.github/workflows/on_opened_pr.yml

+26
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,25 @@
11
name: On new PR
22

3+
# PROCESS
4+
#
5+
# 1. Fetch PR details previously saved from untrusted location
6+
# 2. Parse details for safety
7+
# 3. Confirm there is a related issue for newly opened PR
8+
# 4. Verify if PR template is used and legal acknowledgement hasn't been removed
9+
10+
# USAGE
11+
#
12+
# NOTE: meant to be used with ./.github/workflows/record_pr.yml
13+
#
14+
# Security Note:
15+
#
16+
# This workflow depends on "Record PR" workflow that runs in an untrusted location (forks) instead of `pull_request_target`.
17+
# This enforces zero trust where "Record PR" workflow always runs on fork with zero permissions on GH_TOKEN.
18+
# When "Record PR" completes, this workflow runs in our repository with the appropriate permissions and sanitize inputs.
19+
#
20+
# Coupled with "Approve GitHub Action to run on forks", we have confidence no privilege can be escalated,
21+
# since any malicious change would need to be approved, and upon social engineering, it'll have zero permissions.
22+
323
on:
424
workflow_run:
525
workflows: ["Record PR details"]
@@ -8,6 +28,8 @@ on:
828

929
jobs:
1030
get_pr_details:
31+
permissions:
32+
actions: read # download PR artifact
1133
if: ${{ github.event.workflow_run.conclusion == 'success' }}
1234
uses: ./.github/workflows/reusable_export_pr_details.yml
1335
with:
@@ -16,6 +38,8 @@ jobs:
1638
secrets:
1739
token: ${{ secrets.GITHUB_TOKEN }}
1840
check_related_issue:
41+
permissions:
42+
pull-requests: write # label and comment on PR if missing related issue (requirement)
1943
needs: get_pr_details
2044
runs-on: ubuntu-latest
2145
steps:
@@ -35,6 +59,8 @@ jobs:
3559
check_acknowledge_section:
3660
needs: get_pr_details
3761
runs-on: ubuntu-latest
62+
permissions:
63+
pull-requests: write # label and comment on PR if missing acknowledge section (requirement)
3864
steps:
3965
- uses: actions/checkout@8e5e7e5ab8b370d6c329ec480221332ada57f0ab # v3.5.2
4066
- name: "Ensure acknowledgement section is present"

‎.github/workflows/on_push_docs.yml

+13-6
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,15 @@
11
name: Docs
22

3+
# PROCESS
4+
#
5+
# 1. Build User Guide and API docs
6+
# 2. Publish to GitHub Pages
7+
# 3. Publish to S3 (new home)
8+
9+
# USAGE
10+
#
11+
# Always triggered on PR merge when changes in documentation changes occur.
12+
313
on:
414
push:
515
branches:
@@ -10,15 +20,12 @@ on:
1020
- "examples/**"
1121
- "CHANGELOG.md"
1222

13-
permissions:
14-
id-token: write
15-
1623
jobs:
1724
release-docs:
1825
permissions:
19-
contents: write
20-
pages: write
21-
id-token: write
26+
contents: write # push to gh-pages
27+
pages: write # deploy gh-pages website
28+
id-token: write # trade JWT token for AWS credentials in AWS Docs account
2229
secrets: inherit
2330
uses: ./.github/workflows/reusable_publish_docs.yml
2431
with:

‎.github/workflows/publish_v2_layer.yml

+29-3
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,31 @@
11
name: Deploy v2 layer to all regions
22

3+
# PROCESS
4+
#
5+
# 1. Compile Layer using cdk-aws-lambda-powertools-layer CDK construct for x86 and ARM (uses custom runner as it's CPU heavy)
6+
# 2. Kick off pipeline for beta, prod, and canary releases
7+
# 3. Create PR to update trunk so staged docs also point to the latest Layer ARN, when merged
8+
# 4. Builds and publishes docs with latest Layer ARN using given version (generally coming from release)
9+
10+
11+
# USAGE
12+
#
13+
# NOTE: meant to be used with ./.github/workflows/release.yml
14+
#
15+
# publish_layer:
16+
# needs: [seal, release, create_tag]
17+
# secrets: inherit
18+
# permissions:
19+
# id-token: write
20+
# contents: write
21+
# pages: write
22+
# pull-requests: write
23+
# uses: ./.github/workflows/publish_v2_layer.yml
24+
# with:
25+
# latest_published_version: ${{ needs.seal.outputs.RELEASE_VERSION }}
26+
# pre_release: ${{ inputs.pre_release }}
27+
28+
329
on:
430
workflow_dispatch:
531
inputs:
@@ -91,7 +117,7 @@ jobs:
91117
id-token: write
92118
contents: read
93119
pages: write # docs will be updated with latest Layer ARNs
94-
pull-requests: write # creation-action will create a PR with Layer ARN updates
120+
pull-requests: write # creation-action will create a PR with Layer ARN updates
95121
uses: ./.github/workflows/reusable_deploy_v2_layer_stack.yml
96122
secrets: inherit
97123
with:
@@ -107,7 +133,7 @@ jobs:
107133
id-token: write
108134
contents: read
109135
pages: write # docs will be updated with latest Layer ARNs
110-
pull-requests: write # creation-action will create a PR with Layer ARN updates
136+
pull-requests: write # creation-action will create a PR with Layer ARN updates
111137
uses: ./.github/workflows/reusable_deploy_v2_layer_stack.yml
112138
secrets: inherit
113139
with:
@@ -133,7 +159,7 @@ jobs:
133159
package-version: ${{ inputs.latest_published_version }}
134160

135161
sar-prod:
136-
needs: [build-layer, sar-beta]
162+
needs: [build-layer, beta, sar-beta]
137163
permissions:
138164
# lower privilege propagated from parent workflow (release.yml)
139165
id-token: write

0 commit comments

Comments
 (0)