Adding PR preview

Author: cardil

.github/workflows/docs.yml

@@ -14,7 +14,7 @@ env:
 jobs:
   build_site:
     name: "Build site with Antora"
-    runs-on: [ubuntu-latest]
+    runs-on: [ubuntu-24.04]
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -27,8 +27,14 @@ 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'
@@ -41,10 +47,65 @@ jobs:
           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 }}"
+  
+  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 ⏳..."
+
+      - 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.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 }}/