ARCH-1916 - Update build-and-review-pr.yml implementation

Author: danielle-casella-adams

.github/workflows/build-and-review-pr.yml

@@ -1,68 +1,62 @@
-name: Build and Check for Changes
+name: Build and Review PR
+run-name: Build and Review PR #${{ github.event.pull_request.number }}
+
 on:
-  # This workflow uses the pull_request trigger which prevents write permissions and secrets
-  # access to the target repository from public forks.  This should remain as a pull_request
-  # trigger because checkout, build, format and checking for changes do not need elevated
-  # permissions to the repository.  The reduced permissions for public forks is adequate.
-  # Since this will commit readme/recompile changes back to the branch, special attention 
-  # should be paid to changes made to this workflow when reviewing the PR and granting 
-  # permission to first time contributors to run the workflow.
+  # https://docs.github.com/en/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token
+  #
+  # This workflow uses the pull_request trigger which prevents write permissions on the
+  # GH_TOKEN and secrets access from public forks.  This should remain as a pull_request
+  # trigger to minimize the access public forks have in the repository.  The reduced
+  # permissions are adequate but do mean that re-compiles and readme changes will have to be
+  # made manually by the PR author.  These auto-updates could be done by this workflow
+  # for branches but in order to re-trigger a PR build (which is needed for status checks),
+  # we would make the commits with a different user and their PAT.  To minimize exposure
+  # and complication we will request those changes be manually made by the PR author.
   pull_request:
-  # Don't include any specific paths here so we always get a build that produces a status
-  # check that our Branch Protection Rules can use.  Having a status check also allows us
-  # to require that branches be up to date before they are merged.
+    types: [opened, synchronize, reopened]
+  # paths:
+  #   Do not include specific paths here.  We always want this build to run and produce a
+  #   status check which are branch protection rules can use.  If this is skipped because of
+  #   path filtering, a status check will not be created and we won't be able to merge the PR
+  #   without disabling that requirement.  If we have a status check that is always produced,
+  #   we can also use that to require all branches be up to date before they are merged.
 
 jobs:
-  build:
-    runs-on: ubuntu-latest
-    
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v3
-        with:
-          ref: ${{ github.head_ref }}
-          fetch-depth: 0
+  build-and-review-pr:
+    # This reusable workflow will check to see if an action's source code has changed based on
+    # whether the PR includes files that match the files-with-code arg or are in one of the
+    # dirs-with-code directories.  If there are source code changes, this reusable workflow
+    # will then run the action's build (if one was provided) and update the README.md with the
+    # the latest version of the action.  If those two steps result in any changes that need to
+    # be committed, the workflow will fail because the PR needs some updates.  Instructions for
+    # updating the PR will be available in the build log, the workflow summary and as a PR
+    # comment if the PR came from a branch (not a fork).
+    # This workflow assumes:
+    #  - The main README.md is at the root of the repo
+    #  - The README contains a contribution guidelines and usage examples section
+    uses: im-open/.github/.github/workflows/reusable-build-and-review-pr.yml@v1
+    with:
+      action-name: ${{ github.repository }}
+      default-branch: main
+      readme-name: 'README.md'
+
+      # The id of the contribution guidelines section of the README.md
+      readme-contribution-id: '#contributing'
 
-      - name: Setup Node.js 16
-        uses: actions/setup-node@v3
-        with:
-          node-version: 16.x
+      # The id of the usage examples section of the README.md
+      readme-examples-id: '#usage-examples'
 
-      # If this step results in changes, they will be committed in the last step
-      - name: Recompile and Format action
-        run: npm run build
-      
-      - name: Check for code changes to the action
-        id: action-code
-        uses: im-open/did-custom-action-code-change@v1.0.1
-        with:
-          files-with-code: 'action.yml,package.json,package-lock.json'
-          folders-with-code: 'src,dist'
-          token: ${{ secrets.GITHUB_TOKEN }}
-          
-      - name: Get the next version for the readme if there are code changes to the action
-        if: steps.action-code.outputs.HAS_CHANGES == 'true'
-        id: version
-        uses: im-open/git-version-lite@v2.1.2
+      # The files that contain source code for the action.  Only files that affect the action's execution
+      # should be included like action.yml or package.json.  Do not include files like README.md or .gitignore.
+      # Files do not need to be explicitly provided here if they fall under one of the dirs in dirs-with-code.
+      # ** This value must match the same files-with-code argument specified in increment-version-on-merge.yml.
+      files-with-code: 'action.yml,package.json,package-lock.json'
 
-      - name: Update readme with next version if there are code changes to the action
-        if: steps.action-code.outputs.HAS_CHANGES == 'true'
-        uses: im-open/update-action-version-in-file@v1.0.0
-        with:
-          file-to-update: './README.md'
-          action-name:  ${{ github.repository }}
-          updated-version: ${{ steps.version.outputs.NEXT_VERSION }}
+      # The directories that contain source code for the action.  Only dirs with files that affect the action's
+      # execution should be included like src or dist.  Do not include dirs like .github or node_modules.
+      # ** This value must match the same dirs-with-code argument specified in increment-version-on-merge.yml.
+      dirs-with-code: 'src,dist'
 
-      - name: Commit unstaged readme/recompile changes if there are code changes to the action
-        if: steps.action-code.outputs.HAS_CHANGES == 'true'
-        run: |
-          if [[ "$(git status --porcelain)" != "" ]]; then
-            echo "There are changes to commit"
-            git config user.name github-actions
-            git config user.email github-actions@github.com
-            git add .
-            git commit -m "Update readme with latest version and/or recompile the action."
-            git push origin HEAD:${{ github.head_ref }}
-          else
-            echo "There were no changes to commit"
-          fi
+      # The npm script to run to build the action.  This is typically 'npm run build' if the
+      # action needs to be compiled.  For composite-run-steps actions this is typically empty.
+      build-command: 'npm run build'