Skip to content

Commit af55f01

Browse files
author
Alexander Schueren
authored
chore(ci): automatically update docs after layer publish during release (#1324)
1 parent ade5923 commit af55f01

File tree

9 files changed

+279
-94
lines changed

9 files changed

+279
-94
lines changed

‎.github/scripts/update_layer_arn.sh‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
#!/bin/bash
2+
3+
# This script is run during the reusable_update_v2_layer_arn_docs CI job,
4+
# and it is responsible for replacing the layer ARN in our documentation,
5+
# based on the output files generated by CDK when deploying to each pseudo_region.
6+
#
7+
# see .github/workflows/reusable_deploy_v2_layer_stack.yml
8+
9+
set -eo pipefail
10+
11+
if [[ $# -ne 1 ]]; then
12+
cat <<EOM
13+
Usage: $(basename $0) cdk-output-dir
14+
15+
cdk-output-dir: directory containing the cdk output files generated when deploying the Layer
16+
EOM
17+
exit 1
18+
fi
19+
20+
CDK_OUTPUT_DIR=$1
21+
22+
# Check if CDK output dir is a directory
23+
if [ ! -d "$CDK_OUTPUT_DIR" ]; then
24+
echo "No $CDK_OUTPUT_DIR directory found, not replacing lambda layer versions"
25+
exit 1
26+
fi
27+
28+
# Process each file inside the directory
29+
files="$CDK_OUTPUT_DIR/*"
30+
for file in $files; do
31+
echo "[+] Processing: $file"
32+
33+
# Process each line inside the file
34+
lines=$(cat "$file")
35+
for line in $lines; do
36+
echo -e "\t[*] ARN: $line"
37+
# line = arn:aws:lambda:us-east-1:094274105915:layer:AWSLambdaPowertoolsTypeScript:49
38+
39+
# From the full ARN, extract everything but the version at the end. This prefix
40+
# will later be used to find/replace the ARN on the documentation file.
41+
prefix=$(echo "$line" | cut -d ':' -f 1-7)
42+
# prefix = arn:aws:lambda:us-east-1:094274105915:layer:AWSLambdaPowertoolsTypeScript
43+
44+
# Now replace the all "prefix"s in the file with the full new Layer ARN (line)
45+
# prefix:\d+ ==> line
46+
# sed doesn't support \d+ in a portable way, so we cheat with (:digit: :digit: *)
47+
sed -i -e "s/$prefix:[[:digit:]][[:digit:]]*/$line/g" docs/index.md
48+
49+
# We use the eu-central-1 layer as the version for all the frameworks (SAM, CDK, SLS, etc)
50+
# We could have used any other region. What's important is the version at the end.
51+
52+
# Examples of strings found in the documentation with pseudo regions:
53+
# arn:aws:lambda:{region}:094274105915:layer:AWSLambdaPowertoolsTypeScript:39
54+
# arn:aws:lambda:${AWS::Region}:094274105915:layer:AWSLambdaPowertoolsTypeScript:39
55+
# arn:aws:lambda:${aws:region}:094274105915:layer:AWSLambdaPowertoolsTypeScript:39
56+
# arn:aws:lambda:{env.region}:094274105915:layer:AWSLambdaPowertoolsTypeScript:39
57+
if [[ "$line" == *"eu-central-1"* ]]; then
58+
# These are all the framework pseudo parameters currently found in the docs
59+
for pseudo_region in '{region}' '${AWS::Region}' '${aws::region}' '{aws::region}' '{env.region}' '${cdk.Stack.of(this).region}' '${aws.getRegionOutput().name}'; do
60+
prefix_pseudo_region=$(echo "$prefix" | sed "s/eu-central-1/${pseudo_region}/")
61+
# prefix_pseudo_region = arn:aws:lambda:${AWS::Region}:094274105915:layer:AWSLambdaPowertoolsTypeScript
62+
63+
line_pseudo_region=$(echo "$line" | sed "s/eu-central-1/${pseudo_region}/")
64+
# line_pseudo_region = arn:aws:lambda:${AWS::Region}:094274105915:layer:AWSLambdaPowertoolsTypeScript:49
65+
66+
# Replace all the "prefix_pseudo_region"'s in the file
67+
# prefix_pseudo_region:\d+ ==> line_pseudo_region
68+
sed -i -e "s/$prefix_pseudo_region:[[:digit:]][[:digit:]]*/$line_pseudo_region/g" docs/index.md
69+
done
70+
fi
71+
done
72+
done

‎.github/workflows/make-release.yml‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,8 @@ jobs:
99
publish-npm:
1010
needs: run-unit-tests
1111
runs-on: ubuntu-latest
12+
outputs:
13+
RELEASE_VERSION: ${{ steps.set-release-version.outputs.RELEASE_VERSION }}
1214
steps:
1315
- name: Checkout code
1416
uses: actions/checkout@v3
@@ -47,3 +49,21 @@ jobs:
4749
git remote set-url origin https://x-access-token:${GH_TOKEN}@github.com/$GITHUB_REPOSITORY
4850
npx lerna version --conventional-commits --force-publish --yes
4951
npx lerna publish from-git --no-verify-access --yes
52+
- name: Set release version
53+
id: set-release-version
54+
run: |
55+
RELEASE=$(npm view @aws-lambda-powertools/tracer version)
56+
echo RELEASE_VERSION="$RELEASE_VERSION" >> "$GITHUB_OUTPUT"
57+
58+
# NOTE: Watch out for the depth limit of 4 nested workflow_calls.
59+
# publish_layer -> reusable_deploy_layer_stack -> reusable_update_layer_arn_docs
60+
publish_layer:
61+
needs: publish-npm
62+
secrets: inherit
63+
permissions:
64+
id-token: write
65+
contents: write
66+
pages: write
67+
uses: ./.github/workflows/publish_layer.yml
68+
with:
69+
latest_published_version: ${{ needs.publish-npm.outputs.RELEASE_VERSION }}

‎.github/workflows/on-merge-to-main.yml‎

Lines changed: 0 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -21,15 +21,6 @@ jobs:
2121
needs: get_pr_details
2222
if: ${{ needs.get_pr_details.outputs.prIsMerged == 'true' }}
2323
uses: ./.github/workflows/reusable-run-linting-check-and-unit-tests.yml
24-
publish:
25-
needs:
26-
[get_pr_details, run-unit-tests]
27-
uses: ./.github/workflows/reusable-publish-docs.yml
28-
with:
29-
workflow_origin: ${{ github.event.repository.full_name }}
30-
prIsMerged: ${{ needs.get_pr_details.outputs.prIsMerged }}
31-
secrets:
32-
token: ${{ secrets.GITHUB_TOKEN }}
3324
update-release-draft:
3425
needs: publish
3526
runs-on: ubuntu-latest

‎.github/workflows/on_doc_merge.yml‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
name: Docs
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
paths:
8+
- "docs/**"
9+
- "mkdocs.yml"
10+
- "examples/**"
11+
12+
jobs:
13+
release-docs:
14+
needs: changelog
15+
permissions:
16+
contents: write
17+
pages: write
18+
uses: ./.github/workflows/reusable-publish-docs.yml
19+
with:
20+
workflow_origin: ${{ github.event.repository.full_name }}
21+
version: dev
22+
alias: stage
23+
secrets:
24+
token: ${{ secrets.GITHUB_TOKEN }}

‎.github/workflows/publish-docs-on-release.yml‎

Lines changed: 0 additions & 23 deletions
This file was deleted.

‎.github/workflows/publish_layer.yaml‎

Lines changed: 42 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -12,11 +12,18 @@ on:
1212
description: "Latest npm published version to rebuild corresponding layer for, e.g. v1.0.2"
1313
default: "v1.0.2"
1414
required: true
15-
# Automatic trigger after release
16-
workflow_run:
17-
workflows: ["Make Release"]
18-
types:
19-
- completed
15+
16+
workflow_call:
17+
inputs:
18+
latest_published_version:
19+
type: string
20+
description: "Latest npm published version to rebuild latest docs for, e.g. 2.0.0, 2.0.0a1 (pre-release)"
21+
required: true
22+
pre_release:
23+
description: "Publishes documentation using a pre-release tag (2.0.0a1)."
24+
default: false
25+
type: boolean
26+
required: false
2027

2128
jobs:
2229
# Build layer by running cdk synth in layer-publisher directory and uploading cdk.out for deployment
@@ -73,6 +80,7 @@ jobs:
7380
with:
7481
stage: "BETA"
7582
artifact-name: "cdk-layer-artifact"
83+
latest_published_version: ${{ inputs.latest_published_version }}
7684
secrets:
7785
target-account-role: ${{ secrets.AWS_LAYERS_BETA_ROLE_ARN }}
7886

@@ -84,5 +92,33 @@ jobs:
8492
with:
8593
stage: "PROD"
8694
artifact-name: "cdk-layer-artifact"
95+
latest_published_version: ${{ inputs.latest_published_version }}
8796
secrets:
88-
target-account-role: ${{ secrets.AWS_LAYERS_PROD_ROLE_ARN }}
97+
target-account-role: ${{ secrets.AWS_LAYERS_PROD_ROLE_ARN }}
98+
99+
prepare_docs_alias:
100+
runs-on: ubuntu-latest
101+
permissions:
102+
contents: read
103+
outputs:
104+
DOCS_ALIAS: ${{ steps.set-alias.outputs.DOCS_ALIAS }}
105+
steps:
106+
- name: Set docs alias
107+
id: set-alias
108+
run: |
109+
DOCS_ALIAS=latest
110+
if [[ "${{ inputs.pre_release }}" == true ]] ; then
111+
DOCS_ALIAS=alpha
112+
fi
113+
echo DOCS_ALIAS="$DOCS_ALIAS" >> "$GITHUB_OUTPUT"
114+
115+
release-docs:
116+
needs: [ prod, prepare_docs_alias ]
117+
permissions:
118+
contents: write
119+
pages: write
120+
uses: ./.github/workflows/reusable_publish_docs.yml
121+
with:
122+
version: ${{ inputs.latest_published_version }}
123+
alias: ${{ needs.prepare_docs_alias.outputs.DOCS_ALIAS }}
124+
detached_mode: true

‎.github/workflows/reusable-publish-docs.yml‎

Lines changed: 41 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,28 @@
11
name: Reusable Publish docs
22

3+
env:
4+
BRANCH: main
5+
ORIGIN: awslabs/aws-lambda-powertools-typescript
6+
7+
38
on:
49
workflow_call:
510
inputs:
6-
workflow_origin: # see https://github.com/awslabs/aws-lambda-powertools-python/issues/1349
11+
version:
12+
description: "Version to build and publish docs (1.28.0, develop)"
713
required: true
814
type: string
9-
prIsMerged:
10-
required: false
11-
default: "false"
12-
type: string
13-
isRelease:
14-
required: false
15-
default: "false"
15+
alias:
16+
description: "Alias to associate version (latest, stage)"
17+
required: true
1618
type: string
17-
versionNumber:
19+
detached_mode:
20+
description: "Whether it's running in git detached mode to ensure git is sync'd"
1821
required: false
19-
default: ""
22+
default: false
23+
type: boolean
24+
workflow_origin: # see https://github.com/awslabs/aws-lambda-powertools-python/issues/1349
25+
required: true
2026
type: string
2127
secrets:
2228
token:
@@ -65,68 +71,48 @@ jobs:
6571
uses: actions/setup-python@v4
6672
with:
6773
python-version: "3.8"
68-
# We run this step only when the workflow has been triggered by a release
69-
# in this case we publish the docs to `/latest`
70-
- name: (Conditional) Set RELEASE_VERSION env var to `latest`
71-
if: ${{ inputs.isRelease == 'true' }}
72-
run: |
73-
RELEASE_VERSION=$(echo ${{ github.ref_name }} | sed 's/v//')
74-
EXPLICIT_RELEASE_VERSION=$(echo ${{ inputs.versionNumber }} | sed 's/v//')
75-
if [ $EXPLICIT_RELEASE_VERSION != "" ]; then
76-
echo "RELEASE_VERSION=${EXPLICIT_RELEASE_VERSION}"
77-
echo "RELEASE_VERSION=${EXPLICIT_RELEASE_VERSION}" >> $GITHUB_ENV
78-
else
79-
echo "RELEASE_VERSION=${RELEASE_VERSION}"
80-
echo "RELEASE_VERSION=${RELEASE_VERSION}" >> $GITHUB_ENV
81-
fi
82-
# We run this step only when the workflow has been triggered by a PR merge
83-
# in this case we publish the docs to `/dev`
84-
- name: (Conditional) Set RELEASE_VERSION env var to `dev`
85-
if: ${{ inputs.prIsMerged == 'true' }}
86-
run: |
87-
echo "RELEASE_VERSION=dev" >> $GITHUB_ENV
88-
- name: Check RELEASE_VERSION env var
89-
if: ${{ env.RELEASE_VERSION == '' }}
90-
uses: actions/github-script@v3
91-
with:
92-
script: |
93-
core.setFailed('RELEASE_VERSION env var is empty.')
9474
- name: Install doc generation dependencies
9575
run: |
9676
pip install --upgrade pip
9777
pip install -r docs/requirements.txt
9878
- name: Setup doc deploy
9979
run: |
10080
git config --global user.name Docs deploy
101-
git config --global user.email docs@dummy.bot.com
102-
- name: Publish docs to latest if isRelease
103-
if: ${{ env.RELEASE_VERSION != 'dev' }}
81+
git config --global user.email aws-devax-open-source@amazon.com
82+
- name: Git refresh tip (detached mode)
83+
# Git Detached mode (release notes) doesn't have origin
84+
if: ${{ inputs.detached_mode }}
85+
run: |
86+
git config pull.rebase true
87+
git config remote.origin.url >&- || git remote add origin https://github.com/"$ORIGIN"
88+
git pull origin "$BRANCH"
89+
- name: Build docs website and API reference
90+
run: |
91+
make release-docs VERSION="$VERSION" ALIAS="$ALIAS"
92+
poetry run mike set-default --push latest
93+
- name: Build docs website and API reference
94+
env:
95+
VERSION: ${{ inputs.version }}
96+
ALIAS: ${{ inputs.alias }}
10497
run: |
10598
rm -rf site
10699
mkdocs build
107-
mike deploy --push --update-aliases --no-redirect "${{ env.RELEASE_VERSION }}" "latest"
100+
mike deploy --push --update-aliases --no-redirect ${{ env.VERSION }} ${{ env.ALIAS }}"
108101
# Set latest version as a default
109102
mike set-default --push latest
110-
- name: Publish docs to dev
111-
if: ${{ env.RELEASE_VERSION == 'dev' }}
112-
run: |
113-
rm -rf site
114-
mkdocs build
115-
mike deploy --push dev
116-
- name: Build API docs
117-
run: |
118-
rm -rf api
119-
npm run docs-generateApiDoc
103+
120104
- name: Release API docs
121-
uses: peaceiris/actions-gh-pages@v3
105+
uses: peaceiris/actions-gh-pages@bd8c6b06eba6b3d25d72b7a1767993c0aeee42e7 # v3.9.2
106+
env:
107+
VERSION: ${{ inputs.version }}
122108
with:
123109
github_token: ${{ secrets.GITHUB_TOKEN }}
124110
publish_dir: ./api
125111
keep_files: true
126-
destination_dir: ${{ env.RELEASE_VERSION }}/api
127-
- name: Release API docs to latest if isRelease
128-
if: ${{ env.RELEASE_VERSION != 'dev' }}
129-
uses: peaceiris/actions-gh-pages@v3
112+
destination_dir: ${{ env.VERSION }}/api
113+
- name: Release API docs to latest
114+
if: ${{ input.alias == 'latest' }}
115+
uses: peaceiris/actions-gh-pages@bd8c6b06eba6b3d25d72b7a1767993c0aeee42e7
130116
with:
131117
github_token: ${{ secrets.GITHUB_TOKEN }}
132118
publish_dir: ./api

0 commit comments

Comments
 (0)