chore(ci): refactor release workflow (#2028)

* Update GitHub Actions workflows

* remove env, use git sha

* Update GitHub Actions references to use github.sha

* change publish from package using sha instead of tag

* remove unnecessary token for checkout

* add workflow docs and comments

* small wording changes

Author: am29d

.github/workflows/make-release.yml

@@ -1,4 +1,22 @@
 name: Make Release
+
+# RELEASE PROCESS
+#
+# === Automated activities ===
+# 1. [Quality check] run unit tests, linting, examples, layer, doc snippets
+# 2. [Release] publish all packages to npmjs.org using the latest git commit, ensure provenance with NPM_CONFIG_PROVENANCE=true
+# 3. [Create tag] create a new git tag using released version, i.e. v1.13.1
+# 4. [Publish layer] build and package layer, kick off the workflow for beta and prod deployment, including canary tests
+# 5. [Publish layer] update documentation with the latest layer ARN version of the prod deployment
+# 6. [Publish layer] create PR to merge the updated documentation
+#
+# === Manual activities ===
+# 1. Kick off `make-version` workflow to bump and review the version changes and changelog for each package
+# 2. Merge the PR created by `make-version` workflow
+# 3. Kick off this workflow to make the release
+# 4. Merge the PR created by the `publish_layer` workflow to update the documentation
+# 5. Update draft release notes with the latest changes and publish the release on GitHub
+
 on:
   workflow_dispatch: {}
 
@@ -7,9 +25,15 @@ permissions:
 
 concurrency:
   group: on-release-publish
+
+
 jobs:
   run-unit-tests:
     uses: ./.github/workflows/reusable-run-linting-check-and-unit-tests.yml
+  # This job publishes the packages to npm.
+  # It uses the latest git commit sha as the version and ensures provenance with NPM_CONFIG_PROVENANCE flag.
+  # We don't bump the version because we do that in the `make-version` workflow.
+  # It also sets the RELEASE_VERSION output to be used by the next job to create a git tag.
   publish-npm:
     needs: run-unit-tests
     # Needed as recommended by npm docs on publishing with provenance https://docs.npmjs.com/generating-provenance-statements
@@ -24,35 +48,47 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11  # v4.1.1
         with:
-          # Here `token` is needed to avoid incurring in error GH006 Protected  Branch Update Failed,
-          token: ${{ secrets.GH_PUBLISH_TOKEN }}
-          # While `fetch-depth` is used to allow the workflow to later commit & push the changes.
-          fetch-depth: 0
+          ref: ${{ github.sha }}
       - name: Setup NodeJS
         uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
         with:
           node-version: "20"
           cache: "npm"
       - name: Setup auth tokens
         run: |
-          git config --global user.name 'github-actions[bot]'
-          git config --global user.email 'github-actions[bot]@users.noreply.github.com'
-          git remote set-url origin https://x-access-token:${{ secrets.GH_PUBLISH_TOKEN }}@github.com/$GITHUB_REPOSITORY
           npm set "//registry.npmjs.org/:_authToken=${{ secrets.NPM_TOKEN }}"
       - name: Setup dependencies
         uses: ./.github/actions/cached-node-modules
-      - name: Version
-        run: |
-          npx lerna version minor --force-publish --no-commit-hooks --yes
       - name: Publish to npm
         run: |
-          NPM_CONFIG_PROVENANCE=true npx lerna publish from-git --yes
+          NPM_CONFIG_PROVENANCE=true npx lerna publish from-package --git-head ${{ github.sha }} --yes 
       - name: Set release version
         id: set-release-version
         run: |
           VERSION=$(cat lerna.json | jq .version -r)
           echo RELEASE_VERSION="$VERSION" >> "$GITHUB_OUTPUT"
-
+  
+  # This job creates a new git tag using the released version (v1.18.1)
+  create_tag: 
+    needs: [publish-npm]
+    permissions:
+      contents: write
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11  # v4.1.1
+        with:
+          ref: ${{ github.sha }}
+      - name: Git client setup
+        run: | 
+          git config --global user.name 'aws-powertools-bot'
+          git config --global user.email '151832416+aws-powertools-bot@users.noreply.github.com'
+          git config remote.origin.url >&-
+      - name: Create git tag
+        run : |
+          git tag -a v${{ needs.publish-npm.outputs.RELEASE_VERSION }} -m "Release v${{ needs.publish-npm.outputs.RELEASE_VERSION }}"
+          git push origin v${{ needs.publish-npm.outputs.RELEASE_VERSION }}
+   
   # NOTE: Watch out for the depth limit of 4 nested workflow_calls.
   # publish_layer -> reusable_deploy_layer_stack -> reusable_update_layer_arn_docs
   publish_layer:

.github/workflows/make-version.yml

@@ -4,9 +4,6 @@ on:
   workflow_dispatch: { }
 
 
-env:
-  RELEASE_COMMIT: ${{ github.sha }}
-
 jobs:
   bump-version:
     permissions:
@@ -20,7 +17,7 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11  # v4.1.1
         with:
-          ref: ${{ github.ref }}
+          ref: ${{ github.sha }}
       - name: Setup NodeJS
         uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
         with:

.github/workflows/publish_layer.yml

@@ -1,7 +1,7 @@
 name: Deploy layer to all regions
 
 permissions:
-  contents: write
+  contents: read
 
 on:
   # Manual trigger
@@ -33,7 +33,7 @@ jobs:
       - name: checkout
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11  # v4.1.1
         with:
-          fetch-depth: 0
+          ref: ${{ github.sha }}
       - name: Setup Node.js
         uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
         with:

.github/workflows/reusable_update_layer_arn_docs.yml

@@ -9,7 +9,7 @@ on:
         required: true
 
 permissions:
-  contents: write
+  contents: read
 
 env:
   BRANCH: main
@@ -21,18 +21,15 @@ jobs:
     concurrency:
       group: changelog-build
     runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+      id-token: none
     steps:
       - name: Checkout repository # reusable workflows start clean, so we need to checkout again
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11  # v4.1.1
         with:
-          fetch-depth: 0
-      - name: Git client setup and refresh tip
-        run: |
-          git config user.name "Release bot[bot]"
-          git config user.email "aws-devax-open-source@amazon.com"
-          git config pull.rebase true
-          git config remote.origin.url >&- || git remote add origin https://github.com/"${origin}" # Git Detached mode (release notes) doesn't have origin
-          git pull origin "${BRANCH}"
+          ref: ${{ github.sha }}
       - name: Download CDK layer artifact
         uses: actions/download-artifact@6b208ae046db98c579e8a3aa621ab581ff575935 # v4.1.1
         with:
@@ -42,11 +39,12 @@ jobs:
         run: |
           ls -la cdk-layer-stack/
           ./.github/scripts/update_layer_arn.sh cdk-layer-stack
-      - name: Update documentation in trunk
-        run: |
-          HAS_CHANGE=$(git status --porcelain)
-          test -z "${HAS_CHANGE}" && echo "Nothing to update" && exit 0
-          git add docs/index.md
-          git commit -m "chore: update layer ARN on documentation"
-          git pull origin "${BRANCH}" # prevents concurrent branch update failing push
-          git push origin HEAD:refs/heads/"${BRANCH}"
+      - name: Create PR
+        id: create-pr
+        uses: ./.github/actions/create-pr
+        with: 
+          files: 'docs/index.md'
+          temp_branch_prefix: 'ci-layer-docs'
+          pull_request_title: 'chore(ci): update layer ARN on documentation'
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+