π 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.mdindex 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 samefor `updates.md` and any page the release touched.@@ -125,7 +127,7 @@ gh pr create --base published-docs --title "docs: publish main to published-docsgh 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 validatorin 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 thePR 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.ymlnew file mode 100644index 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