Skip to content

πŸš€ The fast, Pythonic way to build MCP servers and clients.

ci: deploy docs through Mintlify's admin API and wait for a verdict (#4996)

nate nowack75d50ffb683b
diff --git a/.claude/skills/release/SKILL.md b/.claude/skills/release/SKILL.md
index 4571814b5..28a133d56 100644
--- a/.claude/skills/release/SKILL.md
+++ b/.claude/skills/release/SKILL.md
@@ -95,17 +95,19 @@ one gets a follow-up patch, never a re-tag.
gh pr merge <n> --merge --admin
```
- Then read Mintlify's verdict on the new tip. The check-run is the only signal
- that a deploy happened; the merge alone proves nothing. It starts within a
- minute of the merge and `conclusion` is `null` until it finishes:
+ Merging pushes `published-docs`, which runs the `Deploy docs` workflow: it asks
+ Mintlify's admin API for a deployment of the tip and waits for the verdict.
+ That run is the signal that the site changed; the merge alone proves nothing.
```bash
- git fetch origin published-docs
- sha=$(git rev-parse origin/published-docs)
- gh api repos/PrefectHQ/fastmcp/commits/$sha/check-runs \
- --jq '.check_runs[] | select(.name=="Mintlify Deployment") | .conclusion, .output.text'
+ gh run watch $(gh run list --workflow "Deploy docs" --branch published-docs --limit 1 --json databaseId --jq '.[0].databaseId') --exit-status
```
+ A red run prints Mintlify's summary and logs; fix the cause on `main` and
+ publish again. If Mintlify's queue is backed up (status.mintlify.com), the run
+ waits up to 40 minutes; re-run it with
+ `gh workflow run deploy-docs.yml --ref published-docs` once their incident clears.
+
Verify through the markdown endpoints, which bypass the HTML edge cache:
`curl -fsS https://gofastmcp.com/changelog.md | grep -c "<pun>"`, and the same
for `updates.md` and any page the release touched.
@@ -125,7 +127,7 @@ gh pr create --base published-docs --title "docs: publish main to published-docs
gh pr merge <n> --merge --admin
```
-Then repeat the check-run and endpoint verification from step 7.
+Then watch the `Deploy docs` run and verify the endpoints as in step 7.
## Template: notes file for a patch
@@ -137,17 +139,13 @@ connections instead of raising.
## Gotchas
-- Mintlify keeps its per-file hashes even when a deploy fails on a parse error, so
- the next successful deploy only rebuilds files changed since the failure. After
- fixing a parse error, make a small wording edit to every path the failed run
- listed under "Updating targeted paths", merge that to `main`, and publish by hand.
- `--generate-notes` copies PR titles verbatim; a title containing `<1`, `{`, or `}`
breaks MDX. `scripts/changelog_entry.py` wraps those in backticks; the validator
in step 4 catches anything it misses.
-- No Mintlify check-run on the new `published-docs` tip within a few minutes means
- Mintlify never picked the merge up, and there is no CLI trigger. Read
- https://status.mintlify.com first; their deploy queue backs up during incidents
- and the merge deploys on its own once it drains.
+- Mintlify's GitHub App also deploys on its own, but it only rebuilds files
+ changed since the last commit it recorded, and it records commits it failed on
+ or skipped. Only the `Deploy docs` run's verdict counts; its API-triggered
+ deployment is what brings a page a skipped deploy left stale back in line.
- Without `--notes-start-tag`, a prerelease tag becomes the changelog start and the
PR list is silently truncated.
- Maintenance releases publish packages and notes but never repoint `published-docs`;
diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml
new file mode 100644
index 000000000..fa57c150f
--- /dev/null
+++ b/.github/workflows/deploy-docs.yml
@@ -0,0 +1,82 @@
+name: Deploy docs
+
+# Mintlify's GitHub App deploys published-docs on its own, but it rebuilds only
+# files changed since the last commit it recorded, and it records commits it
+# failed on or never processed. This job asks Mintlify's admin API for a
+# deployment of the current tip and waits for a verdict, so a publish either
+# ends with a confirmed live deploy or a red run that names the reason.
+
+on:
+ push:
+ branches: [published-docs]
+ workflow_dispatch:
+
+concurrency:
+ group: deploy-docs
+ cancel-in-progress: false
+
+jobs:
+ deploy:
+ name: Trigger Mintlify deployment and wait
+ runs-on: ubuntu-latest
+ timeout-minutes: 45
+ env:
+ MINTLIFY_API_KEY: ${{ secrets.MINTLIFY_API_KEY }}
+ MINTLIFY_PROJECT_ID: ${{ secrets.MINTLIFY_PROJECT_ID }}
+ steps:
+ - name: Require credentials
+ run: |
+ if [ -z "$MINTLIFY_API_KEY" ] || [ -z "$MINTLIFY_PROJECT_ID" ]; then
+ echo "::error::MINTLIFY_API_KEY and MINTLIFY_PROJECT_ID must be set as repository secrets."
+ exit 1
+ fi
+
+ - name: Trigger deployment
+ id: trigger
+ run: |
+ response=$(curl -fsS -X POST \
+ -H "Authorization: Bearer $MINTLIFY_API_KEY" \
+ "https://api.mintlify.com/v1/project/update/$MINTLIFY_PROJECT_ID")
+ status_id=$(echo "$response" | jq -r '.statusId // empty')
+ if [ -z "$status_id" ]; then
+ echo "::error::Mintlify did not return a statusId: $response"
+ exit 1
+ fi
+ echo "status_id=$status_id" >> "$GITHUB_OUTPUT"
+ echo "Triggered Mintlify update $status_id for $GITHUB_SHA"
+
+ - name: Wait for verdict
+ env:
+ STATUS_ID: ${{ steps.trigger.outputs.status_id }}
+ run: |
+ for _ in $(seq 1 120); do
+ body=$(curl -fsS \
+ -H "Authorization: Bearer $MINTLIFY_API_KEY" \
+ "https://api.mintlify.com/v1/project/update-status/$STATUS_ID")
+ status=$(echo "$body" | jq -r '.status')
+ case "$status" in
+ success)
+ echo "Deployment succeeded."
+ echo "$body" | jq -r '.summary // empty'
+ echo "$body" | jq -r '.commit.files // {} | to_entries[] | "\(.key): \(.value | length)"'
+ echo "$body" | jq -r '.logs[]? | tostring' | tail -40
+ exit 0
+ ;;
+ failure)
+ echo "::error::Mintlify deployment failed."
+ echo "$body" | jq -r '.summary // empty'
+ echo "$body" | jq -r '.logs[]? | tostring' | tail -80
+ exit 1
+ ;;
+ queued|in_progress)
+ sleep 20
+ ;;
+ *)
+ echo "::error::Unexpected status: $status"
+ echo "$body"
+ exit 1
+ ;;
+ esac
+ done
+ echo "::error::Mintlify deployment did not finish within 40 minutes."
+ exit 1