ARCH-1192 - Switch to pr_target & add descriptions for use

.github/workflows/build.yml

@@ -1,5 +1,9 @@
-name: Build and Test
+name: Build and Check for Changes
 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.
   pull_request:
     paths-ignore:
       - '**.md'

.github/workflows/increment-version-on-merge.yml

@@ -1,6 +1,19 @@
 name: Increment Version on Merge
 on:
-  pull_request:
+  # https://securitylab.github.com/research/github-actions-preventing-pwn-requests/
+  # - GitHub’s standard pull_request workflow trigger prevents write permissions and secrets
+  #   access to the target repository from public forks.  PRs from a branch in the same repo
+  #   and forks of internal/private repos are not limited the same way for this trigger.
+  # - The pull_request_target trigger allows the workflow to relax some restrictions to a
+  #   target repository so PRs from forks have write permission to the target repo and have
+  #   secrets access (which we need in order to push a new tag in this workflow).
+  # - For this workflow, the elevated permissions should not be a problem because:
+  #    - Our im-open repositories do not contain secrets, they are dumb actions
+  #    - Require approval for all outside collaborators' is set at the org level so someone
+  #      with Write access has a chance to review code before allowing any workflow runs
+  #    - This workflow with elevated Write permissions will only run once the code has been
+  #      reviewed, approved by a CODEOWNER and merged
+  pull_request_target:
     types: [closed]
 
 jobs:
@@ -10,12 +23,19 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
+      # Generally speaking, when the PR contents are treated as passive data, i.e. not in a
+      # position  of influence over the build/testing process, it is safe to checkout the code
+      # on a pull_request_target.  But we need to be extra careful not to trigger any script
+      # that may operate on PR controlled contents like in the case of npm install.
       - name: Checkout Repository
         uses: actions/checkout@v2
         with:
+          ref: main
           fetch-depth: 0
+          persist-credentials: false
 
-      # See https://github.com/im-open/git-version-lite for more details around how to increment major/minor/patch through commit messages
+      # See https://github.com/im-open/git-version-lite for more details around how to increment
+      # major/minor/patch through commit messages
       - name: Increment the version
         uses: im-open/git-version-lite@v2.0.6
         with: