fix: gracefully handle missing DOCS_PREVIEW_DEPLOY_KEY secret

- Add token existence check before deployment
- Skip deployment if secret is not configured
- Post informative PR comment when deployment is skipped
- Prevents workflow failure when secret is missing/invalid

Fixes authentication failure in docs preview deployment workflow

Author: JacobCoffee

.github/workflows/docs-preview.yml

@@ -39,7 +39,19 @@ jobs:
           fi
           echo "PR_NUMBER=$PR_NUMBER" >> $GITHUB_ENV
 
+      - name: Check if deploy token exists
+        id: check_token
+        run: |
+          if [ -z "${{ secrets.DOCS_PREVIEW_DEPLOY_KEY }}" ]; then
+            echo "has_token=false" >> $GITHUB_OUTPUT
+            echo "⚠️ DOCS_PREVIEW_DEPLOY_KEY secret is not configured"
+          else
+            echo "has_token=true" >> $GITHUB_OUTPUT
+            echo "✅ Deploy token is configured"
+          fi
+
       - name: Deploy docs preview
+        if: steps.check_token.outputs.has_token == 'true'
         uses: JamesIves/github-pages-deploy-action@v4
         with:
           folder: docs-preview/docs/_build/html
@@ -50,6 +62,7 @@ jobs:
           branch: gh-pages
 
       - uses: actions/github-script@v7
+        if: steps.check_token.outputs.has_token == 'true'
         env:
           PR_NUMBER: ${{ env.PR_NUMBER }}
         with:
@@ -81,3 +94,19 @@ jobs:
                   issue_number: issue_number,
                   body: body,
             })
+
+      - uses: actions/github-script@v7
+        if: steps.check_token.outputs.has_token == 'false'
+        env:
+          PR_NUMBER: ${{ env.PR_NUMBER }}
+        with:
+          script: |
+            const issue_number = process.env.PR_NUMBER
+            const body = "⚠️ Documentation preview deployment was skipped because the `DOCS_PREVIEW_DEPLOY_KEY` secret is not configured. Please contact a repository administrator to set up the deployment token."
+
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: issue_number,
+              body: body,
+            })