Recipe: PR Preview Builds

Every pull request against your docs (or annotated source) repo can get its own preview deployment — reviewers see the rendered result, not a wall of MDX diff.

With the GitHub App (recommended)

If you connected your repo via the Syntext GitHub App, this already works:

1. Open a PR → a preview build starts automatically (opened, new pushes, and reopened all trigger rebuilds)
2. The build produces an isolated preview URL
3. Merge to your production branch → a production build deploys

Nothing to configure.

With a Manual Webhook

Add a webhook for push + pull_request events pointing at https://api.syntext.dev/v1/webhooks/github — see Webhooks.

From CI (any provider)

Trigger a preview build explicitly with the API or CLI:

on: pull_request

jobs:
docs-preview:
runs-on: ubuntu-latest
steps:
  - uses: actions/checkout@v4
  - uses: syntext-dev/syntext/action@v1
    with:
      api-key: ${{ secrets.SYNTEXT_API_KEY }}
      preview: true

stx deploy --preview --branch "$BRANCH_NAME"

curl -X POST https://api.syntext.dev/v1/projects/$PROJECT_ID/builds \
-H "Authorization: Bearer $SYNTEXT_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "branch": "'$BRANCH_NAME'", "isPreview": true }'

Getting the Preview URL into the PR

Poll the build until it's deployed, then comment the URL:

BUILD_ID=$(stx deploy --preview --json | jq -r '.buildId')

# poll
until [ "$(stx build status $BUILD_ID --json | jq -r '.status')" = "deployed" ]; do
  sleep 5
done

URL=$(stx build status $BUILD_ID --json | jq -r '.previewUrl')
gh pr comment "$PR_NUMBER" --body "📖 Docs preview: $URL"