pull requests will create a website preview

.github/workflows/build-preview.yml

@@ -0,0 +1,55 @@
+# Zola build workflow.
+
+# Setting it up:
+#   Adjust the variables below, under env.
+#
+#   It is a general limitation of gh-actions that they cannot make the very first
+#   deploy to gh-pages.  It will seem to work, but not appear on the CDN to be
+#   online.  You need to go to settings and set the gh-pages branch, then future
+#   deploys will work.  See
+#   https://github.com/marketplace/actions/github-pages-action#%EF%B8%8F-first-deployment-with-github_token
+
+name: Build and deploy website preview
+
+env:
+  ZOLA_VERSION: "0.18.0"
+  CNAME: "coderefinery.org"
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    # if this build is a PR build and the PR is NOT from a fork
+    if: github.event_name == 'pull_request' && github.repository == github.event.pull_request.head.repo.full_name
+
+    steps:
+    - name: Checkout repository and submodules
+      uses: actions/checkout@v4
+      with:
+        submodules: recursive
+
+    - name: Install zola
+      run: |
+        set -x
+        wget -O - \
+           "https://github.com/getzola/zola/releases/download/v${ZOLA_VERSION}/zola-v${ZOLA_VERSION}-x86_64-unknown-linux-gnu.tar.gz" \
+        | sudo tar xzf - -C /usr/local/bin
+
+    - name: Generate HTML
+      run: zola build --base-url "https://${{ env.CNAME }}/previews/PR${{ github.event.number }}"
+
+    - name: Deploy website
+      uses: JamesIves/github-pages-deploy-action@releases/v3
+      with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          BRANCH: gh-pages
+          FOLDER: ./public
+          TARGET_FOLDER: "previews/PR${{ github.event.number }}" # The website preview is going to be stored in the previews subfolder

.github/workflows/build.yml → .github/workflows/build-upon-push-or-merge.yml

@@ -1,22 +1,18 @@
 # Zola build workflow.
 
-# Prerequisites:
-# - zola writes output to public/
-# - variables below set correctly
-#
 # Setting it up:
+#   Adjust the variables below, under env.
+#
 #   It is a general limitation of gh-actions that they cannot make the very first
 #   deploy to gh-pages.  It will seem to work, but not appear on the CDN to be
 #   online.  You need to go to settings and set the gh-pages branch, then future
 #   deploys will work.  See
 #   https://github.com/marketplace/actions/github-pages-action#%EF%B8%8F-first-deployment-with-github_token
 
-name: Build/deploy website
+name: Build and deploy website upon push or merge to main
 
 env:
-  ZOLA_VERSION: "0.17.2"
-  MAIN_BRANCH: "main"
-  TARGET_BRANCH: "gh-pages"
+  ZOLA_VERSION: "0.18.0"
   CNAME: "coderefinery.org"
 
 on:
@@ -27,25 +23,29 @@ on:
     branches:
       - main
 
-permissions:
-  contents: write
-
 jobs:
   build:
     runs-on: ubuntu-latest
+
+    # only run on push to main branch or merge to main branch (not on prs that are under review)
+    if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+
     steps:
     - name: Checkout repository and submodules
       uses: actions/checkout@v4
       with:
         submodules: recursive
+
     - name: Install zola
       run: |
         set -x
         wget -O - \
            "https://github.com/getzola/zola/releases/download/v${ZOLA_VERSION}/zola-v${ZOLA_VERSION}-x86_64-unknown-linux-gnu.tar.gz" \
         | sudo tar xzf - -C /usr/local/bin
+
     - name: Generate HTML
       run: zola build
+
     # Add CNAME, either (first one used)
     # - file in the root
     # - the environment variable set above
@@ -60,8 +60,8 @@ jobs:
             echo -n ${{ env.CNAME }} > public/CNAME
             echo "Used CNAME from the action workflow file"
         fi
-    - name: Deploy to gh-pages
-      if: ${{ github.event_name == 'push' && github.ref == format('refs/heads/{0}', env.MAIN_BRANCH) }}
+
+    - name: Deploy website
       uses: peaceiris/actions-gh-pages@v3
       with:
         github_token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/link-to-preview.yml

@@ -0,0 +1,16 @@
+name: Link to preview in PR conversation
+
+on:
+  pull_request:
+    types: [opened, reopened]
+
+jobs:
+  link-to-preview:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Create PR comment
+        if: github.event_name == 'pull_request' && github.repository == github.event.pull_request.head.repo.full_name # if this is a pull request build AND the pull request is NOT made from a fork
+        uses: thollander/actions-comment-pull-request@71efef56b184328c7ef1f213577c3a90edaa4aff
+        with:
+          message: 'Once the build has completed, you can preview your PR at this URL: https://${{ github.event.pull_request.base.repo.name }}/previews/PR${{ github.event.number }}/'
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/remove-preview-after-merge.yml

@@ -0,0 +1,25 @@
+# from https://github.com/CliMA/ClimaTimeSteppers.jl
+name: Remove preview once PR is merged or closed
+
+on:
+  pull_request:
+    types: [closed]
+
+jobs:
+  remove-preview-after-merge:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout gh-pages branch
+        uses: actions/checkout@v4
+        with:
+          ref: gh-pages
+      - name: Delete preview and history + push changes
+        run: |
+            if [ -d "previews/PR${{ github.event.number }}" ]; then
+              git config user.name "GH workflow"
+              git config user.email "email@example.org"
+              git rm -rf "previews/PR${{ github.event.number }}"
+              git commit -m "delete preview"
+              git branch gh-pages-new $(echo "delete history" | git commit-tree HEAD^{tree})
+              git push --force origin gh-pages-new:gh-pages
+            fi