add automatic preview deployments

.github/workflows/mintlify-trigger-preview.yml

@@ -0,0 +1,137 @@
+---
+name: Trigger Mintlify Preview Deployment
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+  workflow_dispatch:
+
+# Avoid duplicate preview triggers for the same PR.
+concurrency:
+  group: mintlify-preview-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  trigger-preview:
+    runs-on: ubuntu-latest
+
+    # Secrets are not available to PRs from forks.
+    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
+
+    steps:
+      - name: Trigger Mintlify preview deployment (capture response)
+        id: call
+        env:
+          MINTLIFY_API_KEY: ${{ secrets.MINTLIFY_API_KEY }}
+          MINTLIFY_PROJECT_ID: ${{ secrets.MINTLIFY_PROJECT_ID }}
+          BRANCH: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.ref || github.ref_name }}
+        run: |
+          set -euo pipefail
+
+          if [ -z "${MINTLIFY_API_KEY:-}" ] || [ -z "${MINTLIFY_PROJECT_ID:-}" ]; then
+            echo "Missing required secrets."
+            echo "Set secrets.MINTLIFY_API_KEY (admin key starting with mint_) and secrets.MINTLIFY_PROJECT_ID."
+            exit 1
+          fi
+
+          response="$(curl -sS -X POST \
+            "https://api.mintlify.com/v1/project/preview/${MINTLIFY_PROJECT_ID}" \
+            -H "Authorization: Bearer ${MINTLIFY_API_KEY}" \
+            -H "Content-Type: application/json" \
+            --data "{\"branch\":\"${BRANCH}\"}")"
+
+          echo "response<<EOF" >> "$GITHUB_OUTPUT"
+          echo "$response" >> "$GITHUB_OUTPUT"
+          echo "EOF" >> "$GITHUB_OUTPUT"
+
+      - name: Parse response
+        id: parse
+        env:
+          RESPONSE: ${{ steps.call.outputs.response }}
+        run: |
+          set -euo pipefail
+          python - <<'PY'
+          import json
+          import os
+          import sys
+
+          response = os.environ.get("RESPONSE", "")
+          try:
+            data = json.loads(response) if response else {}
+          except Exception:
+            print("Failed to parse Mintlify API response as JSON.", file=sys.stderr)
+            print(response, file=sys.stderr)
+            sys.exit(1)
+
+          status_id = data.get("statusId", "")
+          preview_url = data.get("previewUrl", "")
+          error = data.get("error", "")
+
+          if error and not (status_id or preview_url):
+            print(f"Mintlify API error: {error}", file=sys.stderr)
+            sys.exit(1)
+
+          out = os.environ["GITHUB_OUTPUT"]
+          with open(out, "a", encoding="utf-8") as f:
+            f.write(f"status_id={status_id}\n")
+            f.write(f"preview_url={preview_url}\n")
+          PY
+
+      - name: Comment preview link on PR
+        if: github.event_name == 'pull_request'
+        uses: actions/github-script@v8
+        env:
+          PREVIEW_URL: ${{ steps.parse.outputs.preview_url }}
+          STATUS_ID: ${{ steps.parse.outputs.status_id }}
+          BRANCH: ${{ github.event.pull_request.head.ref }}
+        with:
+          script: |
+            const previewUrl = process.env.PREVIEW_URL || '';
+            const statusId = process.env.STATUS_ID || '';
+            const branch = process.env.BRANCH || '';
+
+            const lines = [];
+            lines.push('## Mintlify preview');
+            lines.push('');
+            if (previewUrl) {
+              lines.push(`- **Preview URL**: ${previewUrl}`);
+            }
+            if (statusId) {
+              lines.push(`- **Status ID**: \`${statusId}\``);
+            }
+            if (branch) {
+              lines.push(`- **Branch**: \`${branch}\``);
+            }
+
+            const body = lines.join('\n');
+
+            const comments = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+            });
+
+            const existing = comments.data.find(c =>
+              c.user?.type === 'Bot' && (c.body || '').includes('## Mintlify preview')
+            );
+
+            if (existing) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: existing.id,
+                body,
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                body,
+              });
+            }
+