Add PR preview functionality with Netlify

.github/workflows/deploy.yml

@@ -0,0 +1,110 @@
+# Build, and deploy to either GitHub Pages (production), or Netlify (PR previews)
+name: "Build and deploy"
+
+on:
+  # "Production" deployments run on branch
+  push:
+    branches: ["main"]
+
+  # Preview deployments run on PRs
+  pull_request:
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+
+# Sets permissions of the GITHUB_TOKEN
+permissions:
+  # For GitHub Pages:
+  contents: "read"
+  pages: "write"
+  id-token: "write"
+  # For PR preview comments:
+  pull-requests: "write"
+
+
+# Allow one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+
+# Default to bash in login mode
+# https://github.com/mamba-org/provision-with-micromamba#IMPORTANT
+defaults:
+  run:
+    shell: "bash -l {0}"
+
+
+jobs:
+  # Build job
+  build:
+    runs-on: "ubuntu-latest"
+    steps:
+      - name: "Checkout"
+        uses: "actions/checkout@v3"
+
+      - name: "Install Conda environment"
+        uses: "mamba-org/setup-micromamba@v1"
+        with:
+          environment-file: "conda-lock.yml"
+          environment-name: "ci"
+          cache-env: true
+
+      - name: "Render Quarto website"
+        run: "quarto render ./content"
+
+      - name: "Upload site artifact"
+        uses: "actions/upload-pages-artifact@v1"
+        with:
+          path: "./content/_site"
+
+
+  # Deploy preview to Netlify IFF this action triggered by PR
+  # Based on: https://github.com/quarto-dev/quarto-web/blob/main/.github/workflows/preview.yml
+  deploy_preview:
+    if: "github.event_name == 'pull_request'"
+    runs-on: "ubuntu-latest"
+    needs: "build"
+    steps:
+      - name: "Download site artifact"
+        uses: "actions/download-artifact@v3"
+        with:
+          # The name of artifacts created by `actions/upload-pages-artifact` is always "github-pages"
+          name: "github-pages"
+          path: "./_site"
+
+      - name: "Untar site artifact"
+        run: "tar --directory ./_site -xvf ./_site/artifact.tar "
+
+      - name: "Deploy preview to Netlify"
+        uses: "nwtgck/actions-netlify@v2"
+        env:
+          NETLIFY_SITE_ID: "${{ secrets.NETLIFY_SITE_ID }}"
+          NETLIFY_AUTH_TOKEN: "${{ secrets.NETLIFY_AUTH_TOKEN }}"
+        with:
+          publish-dir: "./_site"
+          production-deploy: false
+          github-token: "${{ secrets.GITHUB_TOKEN }}"
+          deploy-message: "Deploy from GHA: ${{ github.event.pull_request.title }}"
+          alias: "deploy-preview-${{ github.event.pull_request.number }}"
+          # these all default to 'true'
+          enable-pull-request-comment: true
+          enable-commit-comment: false
+          enable-commit-status: true
+          overwrites-pull-request-comment: false
+        timeout-minutes: 1
+
+
+  # Deploy to GH Pages IFF this action triggered by push
+  deploy:
+    if: "github.event_name == 'push'"
+    runs-on: "ubuntu-latest"
+    needs: "build"
+    environment:
+      name: "github-pages"
+      url: "${{ steps.deployment.outputs.page_url }}"
+    steps:
+      - name: "Deploy to GitHub Pages"
+        id: "deployment"
+        uses: "actions/deploy-pages@v1"

doc/pr-previews.md

@@ -0,0 +1,40 @@
+# PR previews
+
+I configured PR previews to deploy to a Netlify site. Not because I'm expecting a flood
+of PRs, but as a learning exercise about what tools are available for providing PR
+previews for community-driven website projects.
+
+
+## Netlify configuration
+
+1. Link GitHub account
+1. Create a new site, without integrating with a Git repo. We're going to build with
+   GitHub Actions, so we just need a plain boring site, which Netlify doesn't seem to
+   want us to be able to do easily. This approach minimizes permissions granted to
+   Netlify.
+    * Select the option to browse for a folder on your computer
+    * `mkdir /tmp/netlify-site && echo "Hello world" > /tmp/netlify-site/index.html`
+    * Browse to and upload `/tmp/netlify-site`
+1. Get the "Site ID" from the "Site configuration" menu, and save it as a repo secret.
+1. Generate a "Personal Access Token" in
+   [user settings](https://app.netlify.com/user/applications#personal-access-tokens),
+   and save it as a repo secret.
+
+
+## GitHub configuration
+
+We're using [nwtgck/actions-netlify](https://github.com/nwtgck/actions-netlify) to push
+the build as a [deploy preview](https://docs.netlify.com/site-deploys/deploy-previews/)
+on Netlify.
+
+
+## Notes
+
+It would be really nice to be able to deploy previews on GitHub Pages, but it's not
+easy. If you're using the "old" branch-based usage pattern with GitHub Pages, an action
+exists, and it's [unclear](https://github.com/rossjrw/pr-preview-action/issues/21) when
+or whether it will ever support the new action-based deployment pattern.
+
+Luckily, it [looks like](https://github.com/orgs/community/discussions/7730) GitHub [is
+working on this](https://github.com/actions/deploy-pages/pull/61), but has not provided
+any form of commitment to complete this feature.