---
title: "Recipe: PR Preview Builds"
description: "Get an isolated preview deployment for every pull request, automatically."
---

# 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](/api-reference/webhooks/overview).

## From CI (any provider)

Trigger a preview build explicitly with the API or CLI:

<CodeGroup>
```yaml GitHub Actions
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
```

```bash CLI
stx deploy --preview --branch "$BRANCH_NAME"
```

```bash API
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 }'
```
</CodeGroup>

## Getting the Preview URL into the PR

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

```bash
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"
```

<Note>
Preview builds count toward your monthly build quota. They're isolated from production — search indexes and the AI assistant always serve the production build.
</Note>