Add a new workflow to GitHub Actions for creating the test build of Custom GitHub actions

.github/scripts/github-actions-create-and-commit-build.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+
+# The value of TAG_NAME and the content composited from it are described in terms of
+# the official release build. When creating a test build, a branch name is passed in,
+# but the related contents won't be adjusted to make the result as close as possible
+# to the official release build.
+REPO_URL=$1
+TAG_NAME=$2
+SOURCE_SHA=$(git rev-parse HEAD)
+
+# To build all actions:
+
+pushd ./packages/github-actions
+
+## 1. Build the JavaScript actions.
+npm ci --ignore-scripts
+npm run build
+
+## 2. Build the PHP actions into .zip files.
+./build-php-actions.sh
+
+popd
+
+# Use the github-actions bot account to commit.
+# https://api.github.com/users/github-actions%5Bbot%5D
+git config user.name github-actions[bot]
+git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+
+# To move all actions to the top directory:
+## 1. Delete all files from version control system.
+git rm -r .
+git commit -q -m "Create the ${TAG_NAME} release build for the \`github-actions\` package."
+
+## 2. Get all actions back.
+git checkout HEAD^ -- ./packages/github-actions/actions
+git restore --staged .
+
+## 3. Avoid committing src directories to the build.
+echo "/packages/github-actions/actions/*/src" > .gitignore
+
+## 4. Unzip all of the PHP actions and replace them.
+for zipFile in $(find ./packages/github-actions/actions -name "*.zip" -mindepth 1 -maxdepth 1) ; do
+  actionDir="${zipFile%.*}"
+  rm -rf $actionDir
+  unzip $zipFile -d ./packages/github-actions/actions
+  rm $zipFile
+  echo "${actionDir}/src" | sed -e "s/^\.\//!/g" >> .gitignore
+done
+
+## 5. Move all actions to the top directory.
+git add ./packages/github-actions/actions
+git mv ./packages/github-actions/actions/* ./
+
+## 6. Create the README to point to the source revision of this build.
+tee README.md << END
+# Custom GitHub actions
+### This is the release build of version \`${TAG_NAME}\`.
+### :pushpin: Please visit [here to view the source code of this version](${REPO_URL}/tree/${SOURCE_SHA}/packages/github-actions).
+END
+git add README.md
+
+## 7. Complete the build for release or test.
+git commit -q --amend -C HEAD
+
+# The temporary `tmp-gha-release-build` branch is only for pushing to the remote repo.
+# Tagging it with a version tag will be proceeded with a separate step.
+git push origin HEAD:refs/heads/tmp-gha-release-build
+git push -d origin tmp-gha-release-build

.github/workflows/github-actions-create-test-build.yml

@@ -0,0 +1,40 @@
+name: GitHub Actions - Create Test Build
+run-name:  Create test build onto the ${{ github.ref_name }} branch by @${{ github.actor }}
+
+on:
+  workflow_dispatch:
+
+jobs:
+  CreateTestBuild:
+    name: Create Test Build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+
+      - name: Prepare node
+        uses: ./packages/github-actions/actions/prepare-node
+        with:
+          node-version: 14
+          cache-dependency-path: ./packages/github-actions/package-lock.json
+          install-deps: "no"
+
+      - name: Create and commit test build
+        run: |
+          REPO_URL="${{ github.server_url }}/${{ github.repository }}"
+          BRANCH_NAME="${{ github.ref_name }}"
+          TEST_BRANCH_NAME="${BRANCH_NAME}-test-build"
+
+          .github/scripts/github-actions-create-and-commit-build.sh "$REPO_URL" "$BRANCH_NAME"
+
+          # This `git checkout HEAD^` is to prevent errors from the post jobs like "Prepare node".
+          git checkout HEAD^ -- ./packages/github-actions/actions
+
+          # Set/update the test branch
+          git push --force origin "HEAD:refs/heads/${TEST_BRANCH_NAME}"
+
+          # Set summary
+          echo "### :link: The test build has been created" >> $GITHUB_STEP_SUMMARY
+          echo "${REPO_URL}/tree/${TEST_BRANCH_NAME}" >> $GITHUB_STEP_SUMMARY
+          echo "### :zap: Use the test build" >> $GITHUB_STEP_SUMMARY
+          echo "In the repo where you want to test custom actions with this test build, specify the \`uses\` with \`${{ github.repository }}/ACTION_PATH_TO_BE_TESTED@${TEST_BRANCH_NAME}\`." >> $GITHUB_STEP_SUMMARY

.github/workflows/github-actions-release.yml

@@ -90,60 +90,16 @@ jobs:
 
       - name: Create and commit release build
         id: commit-build
-        # Use the github-actions bot account to commit.
-        # https://api.github.com/users/github-actions%5Bbot%5D
-        #
-        # The second `git checkout HEAD^` is to prevent errors from the post jobs like "Prepare node".
         run: |
-          SOURCE_SHA=$(git rev-parse HEAD);
+          REPO_URL="${{ github.server_url }}/${{ github.repository }}"
           TAG_NAME="${{ steps.resolve-tag.outputs.tag_name }}"
 
-          pushd ./packages/github-actions
-
-          # Build the JavaScript actions.
-          npm ci --ignore-scripts
-          npm run build
-
-          # Build the PHP actions into .zip files.
-          ./build-php-actions.sh
-
-          popd
-
-          git config user.name github-actions[bot]
-          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
-
-          git rm -r .
-          git commit -q -m "Create the ${TAG_NAME} release build for the \`github-actions\` package."
+          .github/scripts/github-actions-create-and-commit-build.sh "$REPO_URL" "$TAG_NAME"
 
+          # This `git checkout HEAD^` is to prevent errors from the post jobs like "Prepare node".
           git checkout HEAD^ -- ./packages/github-actions/actions
-          git restore --staged .
-          echo "/packages/github-actions/actions/*/src" > .gitignore
-
-          # Unzip all of the PHP actions and replace them.
-          for zipFile in $(find ./packages/github-actions/actions -name "*.zip" -mindepth 1 -maxdepth 1) ; do
-            actionDir="${zipFile%.*}"
-            rm -rf $actionDir
-            unzip $zipFile -d ./packages/github-actions/actions
-            rm $zipFile
-            echo "${actionDir}/src" | sed -e "s/^\.\//!/g" >> .gitignore
-          done
-
-          # Move all actions to the top directory.
-          git add ./packages/github-actions/actions
-          git mv ./packages/github-actions/actions/* ./
-
-          tee README.md << END
-          # Custom GitHub actions
-          ### This is the release build of version \`${TAG_NAME}\`.
-          ### :pushpin: Please visit [here to view the source code of this version](https://github.com/woocommerce/grow/tree/${SOURCE_SHA}/packages/github-actions).
-          END
-          git add README.md
-          git commit -q --amend -C HEAD
-
-          git push origin HEAD:refs/heads/tmp-gha-release-build
-          git push -d origin tmp-gha-release-build
 
-          git checkout HEAD^ -- ./packages/github-actions/actions
+          # Set output for the next step
           echo "sha=$(git rev-parse HEAD)" >> $GITHUB_OUTPUT
 
       - name: Update version tags

packages/github-actions/README.md

@@ -68,6 +68,17 @@ Custom GitHub actions that help to composite GitHub workflows across the repos m
 - The `src` directories of JavaScript actions will be skipped in the release build.
 - When adding a new script that needs to be built, add its build script to package.json and make sure it will be called in `npm run build`.
 
+### Create a test build
+
+Create a test build on the given branch and commit it to a separate branch with the `-test-build` suffix to facilitate testing and development.
+
+1. Go to Workflow [GitHub Actions - Create Test Build](https://github.com/woocommerce/grow/actions/workflows/github-actions-create-test-build.yml)
+1. Manually run the workflow with the target branch.
+1. Wait for the triggered workflow run to complete.
+1. View the summary of the workflow run to use the test build.
+1. Take the branch name `add/my-action` and action path `greet-visitor` as an example. After a test build is created, it should be able to test the custom action by `woocommerce/grow/greet-visitor@add/my-action-test-build`
+1. Delete the test branch once it is no longer needed.
+
 ### Directory structure of release build
 
 ```
@@ -129,7 +140,7 @@ gitGraph
 
 ## Release
 
-### Official release
+### Official release process
 
 1. :technologist: Create the specific branch `release/actions` onto the target revision on `trunk` branch.
 1. :octocat: When the branch `release/actions` is created, will continue to commit the release content to `release/actions` branch.
@@ -153,7 +164,9 @@ gitGraph
 1. :technologist: Check if both release workflows are run successfully.
 1. :technologist: Merge the release PR.
 
-### Testing release
+### Testing the release process
+
+:bulb: To create a test build based on a branch, please refer to the [Create a test build](#create-a-test-build) section.
 
 1. Create a new release with a **prerelease version tag**. For example `actions-vX.Y.Z-pre`.
 1. Check if the ["GitHub Actions - Release" workflow](https://github.com/woocommerce/grow/actions/workflows/github-actions-release.yml) is run successfully.