🎁 Adding PR previews

.github/workflows/docs.yml

@@ -1,19 +1,24 @@
-name: docs
+name: Docs
 
 on:
   push:
     branches:
       - master
       - main
+  pull_request:
+    branches:
+      - '**'
+
 env:
   SITE_DIR: "gh-pages"
+
 jobs:
   build_site:
     name: "Build site with Antora"
-    runs-on: [ubuntu-latest]
+    runs-on: [ubuntu-24.04]
     steps:
       - name: Checkout
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
       - name: "Generate site using antora site action"
         uses: kameshsampath/antora-site-action@master
         with:
@@ -23,23 +28,86 @@ jobs:
         with:
           name: site
           path: "${{ github.workspace }}/${{ env.SITE_DIR }}"
+
   deploy_site:
-    runs-on: [ubuntu-latest]
+    permissions:
+      contents: write
+      pull-requests: write
+      repository-projects: write
+      id-token: write
+    runs-on: [ubuntu-24.04]
     needs: [build_site]
     name: "Deploy GitHub Pages"
+    if: github.event_name != 'pull_request'
     steps:
       - name: Checkout
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
       - name: Download generated site
         uses: actions/download-artifact@v4
         with:
           name: site
           path: "${{ github.workspace }}/${{ env.SITE_DIR }}"
       - name: Deploy to GitHub Pages
-        uses: JamesIves/[email protected]
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          folder: "${{ env.SITE_DIR }}"
+          commit-message: "[CI] Publish Documentation for ${{ github.sha }}"
+
+  # Based on : https://daiyi.co/blog/pr-previews-for-github-pages/
+  deploy_preview:
+    permissions:
+      contents: write
+      pull-requests: write
+      repository-projects: write
+      id-token: write
+    env:
+      PR_PATH: pull-${{ github.event.number }}
+    runs-on: [ ubuntu-24.04 ]
+    needs: [ build_site ]
+    name: "Deploy preview for PR"
+    if: github.event_name == 'pull_request'
+    steps:
+      - name: Comment on PR
+        uses: hasura/[email protected]
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          repository: ${{ github.repository }}
+          number: ${{ github.event.number }}
+          id: deploy-preview
+          message: "Starting deployment of preview for ${{ github.event.pull_request.head.sha }} ⏳..."
+
+      - name: Set base URL for preview
+        run: echo "BASE_URL=https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/${{ env.PR_PATH }}" >> "$GITHUB_ENV"
+
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Download generated site
+        uses: actions/download-artifact@v4
+        with:
+          name: site
+          path: "${{ github.workspace }}/${{ env.SITE_DIR }}"
+
+      - name: Deploy PR preview
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          folder: "${{ env.SITE_DIR }}"
+          target-folder: "${{ env.PR_PATH }}"
+          commit-message: "[CI] Publish Preview for PR #${{ github.event.number }}"
+
+      - name: Update comment
+        uses: hasura/[email protected]
         with:
-          # ACCESS_TOKEN: # optional
-          GITHUB_TOKEN: "${{ github.token}}"
-          FOLDER: "${{ env.SITE_DIR }}"
-          BRANCH: "gh-pages"
-          COMMIT_MESSAGE: "[CI] Publish Documentation for ${{ github.sha }}"
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          repository: ${{ github.repository }}
+          number: ${{ github.event.number }}
+          id: deploy-preview
+          message: |
+            A preview of ${{ github.event.pull_request.head.sha }} is uploaded and can be seen here:
+
+            ✨ ${{ env.BASE_URL }} ✨
+
+            Changes may take a few minutes to propagate.
+
+            The source is here: https://github.com/${{ github.repository }}/tree/gh-pages/${{ env.PR_PATH }}

.github/workflows/pr-close.yml

@@ -0,0 +1,37 @@
+name: PR Close
+on:
+  pull_request:
+    types: [closed]
+
+jobs:
+  delete_preview:
+    permissions:
+      contents: write
+      pull-requests: write
+      repository-projects: write
+      id-token: write
+    name: Delete preview for PR
+    runs-on: [ ubuntu-24.04 ]
+    env:
+      SITE_DIR: "gh-pages"
+      PR_PATH: pull-${{ github.event.number }}
+    steps:
+      - name: Make empty dir
+        run: "mkdir -p ${{ env.PR_PATH }}"
+
+      - name: Removing PR preview
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          folder: "${{ env.SITE_DIR }}"
+          target-folder: "${{ env.PR_PATH }}"
+          commit-message: "[CI] Delete Preview for PR #${{ github.event.number }}"
+
+      - name: Comment on PR
+        uses: hasura/[email protected]
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          repository: ${{ github.repository }}
+          number: ${{ github.event.number }}
+          id: deploy-preview
+          message: "🪓 PR closed, deleted preview at https://github.com/${{ github.repository }}/tree/gh-pages/${{ env.PR_PATH }}"