Update Workflows to Version 0.12.2

.github/workflows/README.md

@@ -46,8 +46,11 @@ This workflow has two caches; one cache is for the lesson infrastructure and
 the other is for the the lesson dependencies if the lesson contains rendered
 content. These caches are invalidated by new versions of the infrastructure and
 the `renv.lock` file, respectively. If there is a problem with the cache, 
-manual invaliation is necessary and can be done by setting the `CACHE_VERSION`
-secret to the current date.
+manual invaliation is necessary. You will need maintain access to the repository
+and you can either go to the actions tab and [click on the caches button to find
+and invalidate the failing cache](https://github.blog/changelog/2022-10-20-manage-caches-in-your-actions-workflows-from-web-interface/) 
+or by setting the `CACHE_VERSION` secret to the current date (which will
+invalidate all of the caches).
 
 ## Updates
 
@@ -56,15 +59,15 @@ secret to the current date.
 These workflows run on a schedule and at the maintainer's request. Because they
 create pull requests that update workflows/require the downstream actions to run,
 they need a special repository/organization secret token called 
-`SANDPAPER_WORKFLOW` and it must have the `repo` and `workflow` scope. 
+`SANDPAPER_WORKFLOW` and it must have the `public_repo` and `workflow` scope. 
 
 This can be an individual user token, OR it can be a trusted bot account. If you
 have a repository in one of the official Carpentries accounts, then you do not
 need to worry about this token being present because the Carpentries Core Team
 will take care of supplying this token.
 
 If you want to use your personal account: you can go to 
-<https://github.com/settings/tokens/new?scopes=repo,workflow&description=Sandpaper%20Token>
+<https://github.com/settings/tokens/new?scopes=public_repo,workflow&description=Sandpaper%20Token>
 to create a token. Once you have created your token, you should copy it to your
 clipboard and then go to your repository's settings > secrets > actions and
 create or edit the `SANDPAPER_WORKFLOW` secret, pasting in the generated token.
@@ -86,24 +89,25 @@ will do the following:
 1. check the recorded version of sandpaper against the current version on github
 2. update the files if there is a difference in versions
 
-After the files are updated, a pull request is created if there are any changes.
-Maintainers are encouraged to review the changes and accept the pull request.
+After the files are updated, if there are any changes, they are pushed to a
+branch called `update/workflows` and a pull request is created. Maintainers are
+encouraged to review the changes and accept the pull request if the outputs
+are okay.
 
 This update is run ~~weekly or~~ on demand.
 
-TODO: 
-  - perform check if a pull request exists before creating pull request
-
 ### 03 Maintain: Update Pacakge Cache (update-cache.yaml)
 
 For lessons that have generated content, we use {renv} to ensure that the output
 is stable. This is controlled by a single lockfile which documents the packages
-needed for the lesson and the version numbers.
+needed for the lesson and the version numbers. This workflow is skipped in 
+lessons that do not have generated content.
 
 Because the lessons need to remain current with the package ecosystem, it's a
 good idea to make sure these packages can be updated periodically. The 
-update cache workflow will do this by checking for updates, applying them and
-creating a pull request with _only the lockfile changed_. 
+update cache workflow will do this by checking for updates, applying them in a
+branch called `updates/packages` and creating a pull request with _only the
+lockfile changed_. 
 
 From here, the markdown documents will be rebuilt and you can inspect what has
 changed based on how the packages have updated. 
@@ -117,7 +121,24 @@ pull requests that do not pass checks and do not have bots commented on them.**
 This series of workflows all go together and are described in the following 
 diagram and the below sections:
 
-![Graph representation of a pull request](../../vignettes/articles/img/pr-flow.dot.svg)
+![Graph representation of a pull request](https://carpentries.github.io/sandpaper/articles/img/pr-flow.dot.svg)
+
+### Pre Flight Pull Request Validation (pr-preflight.yaml)
+
+This workflow runs every time a pull request is created and its purpose is to
+validate that the pull request is okay to run. This means the following things:
+
+1. The pull request does not contain modified workflow files
+2. If the pull request contains modified workflow files, it does not contain 
+   modified content files (such as a situation where @carpentries-bot will
+   make an automated pull request)
+3. The pull request does not contain an invalid commit hash (e.g. from a fork
+   that was made before a lesson was transitioned from styles to use the
+   workbench).
+
+Once the checks are finished, a comment is issued to the pull request, which 
+will allow maintainers to determine if it is safe to run the 
+"Receive Pull Request" workflow from new contributors.
 
 ### Recieve Pull Request (pr-recieve.yaml)
 
@@ -126,6 +147,11 @@ pull request. GitHub has safeguarded the token used in this workflow to have no
 priviledges in the repository, but we have taken precautions to protect against
 spoofing.
 
+This workflow is triggered with every push to a pull request. If this workflow
+is already running and a new push is sent to the pull request, the workflow
+running from the previous push will be cancelled and a new workflow run will be
+started.
+
 The first step of this workflow is to check if it is valid (e.g. that no
 workflow files have been modified). If there are workflow files that have been
 modified, a comment is made that indicates that the workflow is not run. If 
@@ -139,25 +165,23 @@ request. This builds the content and uploads three artifacts:
 3. The rendered files (build)
 
 Because this workflow builds generated content, it follows the same general 
-process as the sandpaper-main workflow with the same caching mechanisms.
+process as the `sandpaper-main` workflow with the same caching mechanisms.
 
 The artifacts produced are used by the next workflow.
 
-# sandpaper 0.5.5
 ### Comment on Pull Request (pr-comment.yaml)
 
 This workflow is triggered if the `pr-recieve.yaml` workflow is successful.
 The steps in this workflow are:
 
-1. Test if the workflow is valid
-2. If it is valid: create an orphan branch with two commits: the current state of
-   the repository and the proposed changes.
-3. If it is valid: comment on the pull request with the summary of changes
-4. If it is NOT valid: comment on the pull request that it is not valid,
-   warning the maintainer that more scrutiny is needed.
+1. Test if the workflow is valid and comment the validity of the workflow to the
+   pull request.
+2. If it is valid: create an orphan branch with two commits: the current state
+   of the repository and the proposed changes.
+3. If it is valid: update the pull request comment with the summary of changes
 
 Importantly: if the pull request is invalid, the branch is not created so any
-malicious code is not published. 
+malicious code is not published.
 
 From here, the maintainer can request changes from the author and eventually 
 either merge or reject the PR. When this happens, if the PR was valid, the 

.github/workflows/pr-close-signal.yaml

@@ -16,8 +16,8 @@ jobs:
           mkdir -p ./pr
           printf ${{ github.event.number }} > ./pr/NUM
       - name: Upload Diff
-        uses: actions/upload-artifact@v2
+        uses: actions/upload-artifact@v3
         with:
-          name: pr 
+          name: pr
           path: ./pr
 

.github/workflows/pr-comment.yaml

@@ -8,6 +8,11 @@ on:
     types:
       - completed
 
+concurrency:
+  group: pr-${{ github.event.workflow_run.pull_requests[0].number }}
+  cancel-in-progress: true
+
+
 jobs:
   # Pull requests are valid if:
   #  - they match the sha of the workflow run head commit
@@ -16,11 +21,14 @@ jobs:
   test-pr:
     name: "Test if pull request is valid"
     runs-on: ubuntu-latest
-    if: ${{ github.event.workflow_run.event == 'pull_request' && github.event.workflow_run.conclusion == 'success' }}
+    if: >
+      github.event.workflow_run.event == 'pull_request' &&
+      github.event.workflow_run.conclusion == 'success'
     outputs:
       is_valid: ${{ steps.check-pr.outputs.VALID }}
       payload: ${{ steps.check-pr.outputs.payload }}
       number: ${{ steps.get-pr.outputs.NUM }}
+      msg: ${{ steps.check-pr.outputs.MSG }}
     steps:
       - name: 'Download PR artifact'
         id: dl
@@ -34,22 +42,30 @@ jobs:
         id: get-pr
         run: |
           unzip pr.zip
-          echo "::set-output name=NUM::$(<./NR)"
+          echo "NUM=$(<./NR)" >> $GITHUB_OUTPUT
 
       - name: "Fail if PR number was not present"
         id: bad-pr
         if: ${{ steps.dl.outputs.success != 'true' }}
         run: |
           echo '::error::A pull request number was not recorded. The pull request that triggered this workflow is likely malicious.'
           exit 1
-
+      - name: "Get Invalid Hashes File"
+        id: hash
+        run: |
+          echo "json<<EOF
+          $(curl -sL https://files.carpentries.org/invalid-hashes.json)
+          EOF" >> $GITHUB_OUTPUT
       - name: "Check PR"
         id: check-pr
         if: ${{ steps.dl.outputs.success == 'true' }}
         uses: carpentries/actions/check-valid-pr@main
         with:
           pr: ${{ steps.get-pr.outputs.NUM }}
-          sha: ${{ github.events.workflow_run.head_commit.sha }}
+          sha: ${{ github.event.workflow_run.head_sha }}
+          headroom: 3 # if it's within the last three commits, we can keep going, because it's likely rapid-fire
+          invalid: ${{ fromJSON(steps.hash.outputs.json)[github.repository] }}
+          fail_on_error: true
 
   # Create an orphan branch on this repository with two commits
   #  - the current HEAD of the md-outputs branch
@@ -62,9 +78,11 @@ jobs:
     if: ${{ needs.test-pr.outputs.is_valid == 'true' }}
     env:
       NR: ${{ needs.test-pr.outputs.number }}
+    permissions:
+      contents: write
     steps:
       - name: 'Checkout md outputs'
-        uses: actions/checkout@v2.3.4
+        uses: actions/checkout@v3
         with:
           ref: md-outputs
           path: built
@@ -88,11 +106,11 @@ jobs:
           git config --local user.name "GitHub Actions"
           CURR_HEAD=$(git rev-parse HEAD)
           git checkout --orphan md-outputs-PR-${NR}
-          git add -A 
+          git add -A
           git commit -m "source commit: ${CURR_HEAD}"
-          ls -A | grep -v '^.git' | xargs rm -r
+          ls -A | grep -v '^.git$' | xargs -I _ rm -r '_'
           cd ..
-          unzip -d built built.zip
+          unzip -o -d built built.zip
           cd built
           git add -A
           git commit --allow-empty -m "differences for PR #${NR}"
@@ -106,14 +124,16 @@ jobs:
     if: ${{ needs.test-pr.outputs.is_valid == 'true' }}
     env:
       NR: ${{ needs.test-pr.outputs.number }}
+    permissions:
+      pull-requests: write
     steps:
       - name: 'Download comment artifact'
         id: dl
         uses: carpentries/actions/download-workflow-artifact@main
         with:
           run: ${{ github.event.workflow_run.id }}
           name: 'diff'
-          
+
       - if: ${{ steps.dl.outputs.success == 'true' }}
         run: unzip ${{ github.workspace }}/diff.zip
 
@@ -122,7 +142,7 @@ jobs:
         if: ${{ steps.dl.outputs.success == 'true' }}
         uses: carpentries/actions/comment-diff@main
         with:
-          pr: ${{ env.NR }} 
+          pr: ${{ env.NR }}
           path: ${{ github.workspace }}/diff.md
 
   # Comment if the PR is open and matches the SHA, but the workflow files have
@@ -131,18 +151,35 @@ jobs:
     name: "Comment if workflow files have changed"
     needs: test-pr
     runs-on: ubuntu-latest
-    if: ${{ needs.test-pr.outputs.is_valid == 'false' }}
+    if: ${{ always() && needs.test-pr.outputs.is_valid == 'false' }}
     env:
-      NR: ${{ needs.test-pr.outputs.number }}
+      NR: ${{ github.event.workflow_run.pull_requests[0].number }}
+      body: ${{ needs.test-pr.outputs.msg }}
+    permissions:
+      pull-requests: write
     steps:
+      - name: 'Check for spoofing'
+        id: dl
+        uses: carpentries/actions/download-workflow-artifact@main
+        with:
+          run: ${{ github.event.workflow_run.id }}
+          name: 'built'
+
+      - name: 'Alert if spoofed'
+        id: spoof
+        if: ${{ steps.dl.outputs.success == 'true' }}
+        run: |
+          echo 'body<<EOF' >> $GITHUB_ENV
+          echo '' >> $GITHUB_ENV
+          echo '## :x: DANGER :x:' >> $GITHUB_ENV
+          echo 'This pull request has modified workflows that created output. Close this now.' >> $GITHUB_ENV
+          echo '' >> $GITHUB_ENV
+          echo 'EOF' >> $GITHUB_ENV
+
       - name: "Comment on PR"
-        if: ${{ needs.test-pr.outputs.payload }}
         id: comment-diff
         uses: carpentries/actions/comment-diff@main
         with:
-          pr: ${{ env.NR }} 
-          body: |
-            This pull request contains modified workflows and no preview will be created.
-
-            **Please inspect the changes for any malicious content.**
+          pr: ${{ env.NR }}
+          body: ${{ env.body }}
 

.github/workflows/pr-post-remove-branch.yaml

@@ -11,8 +11,10 @@ jobs:
     name: "Delete branch from Pull Request"
     runs-on: ubuntu-latest
     if: >
-      ${{ github.event.workflow_run.event == 'pull_request' &&
-      github.event.workflow_run.conclusion == 'success' }}
+      github.event.workflow_run.event == 'pull_request' &&
+      github.event.workflow_run.conclusion == 'success'
+    permissions:
+      contents: write
     steps:
       - name: 'Download artifact'
         uses: carpentries/actions/download-workflow-artifact@main
@@ -23,7 +25,7 @@ jobs:
         id: get-pr
         run: |
           unzip pr.zip
-          echo "::set-output name=NUM::$(<./NUM)"
+          echo "NUM=$(<./NUM)" >> $GITHUB_OUTPUT
       - name: 'Remove branch'
         uses: carpentries/actions/remove-branch@main
         with:

.github/workflows/pr-preflight.yaml

@@ -0,0 +1,39 @@
+name: "Pull Request Preflight Check"
+
+on:
+  pull_request_target:
+    branches:
+      ["main"]
+    types:
+      ["opened", "synchronize", "reopened"]
+
+jobs:
+  test-pr:
+    name: "Test if pull request is valid"
+    if: ${{ github.event.action != 'closed' }}
+    runs-on: ubuntu-latest
+    outputs:
+      is_valid: ${{ steps.check-pr.outputs.VALID }}
+    permissions:
+      pull-requests: write
+    steps:
+      - name: "Get Invalid Hashes File"
+        id: hash
+        run: |
+          echo "json<<EOF
+          $(curl -sL https://files.carpentries.org/invalid-hashes.json)
+          EOF" >> $GITHUB_OUTPUT
+      - name: "Check PR"
+        id: check-pr
+        uses: carpentries/actions/check-valid-pr@main
+        with:
+          pr: ${{ github.event.number }}
+          invalid: ${{ fromJSON(steps.hash.outputs.json)[github.repository] }}
+          fail_on_error: true
+      - name: "Comment result of validation"
+        id: comment-diff
+        if: ${{ always() }}
+        uses: carpentries/actions/comment-diff@main
+        with:
+          pr: ${{ github.event.number }}
+          body: ${{ steps.check-pr.outputs.MSG }}