/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
Guides Recipes Recipe: PR Preview Builds

Recipe: PR Preview Builds

Get an isolated preview deployment for every pull request, automatically.

2 min read

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.

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.

Note

Preview addresses always fit DNS limits. A preview is served at <branch>--<subdomain>.syntext.dev; when that first part would be longer than 63 characters, the branch part is shortened and ends in a short code, such as …-page-m-e202f7--testing-docs.syntext.dev. Shorter branches keep their exact address. Always use the URL stx deploy prints (or the build's deployUrl) rather than building the address yourself.

From CI (any provider)

Trigger a preview build explicitly with the API or CLI:

GitHub ActionsCLIAPI
on: pull_request
jobs:
docs-preview:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: curl -fsSL https://get.syntext.dev | sh
- run: stx deploy --preview --branch "${{ github.head_ref }}" --token "$SYNTEXT_API_KEY"
env:
SYNTEXT_API_KEY: ${{ secrets.SYNTEXT_API_KEY }}

The CLI uploads your working copy; the API builds a Git-connected project from the branch in its repository. A build of any branch other than the project's production branch is a preview.

Getting the Preview URL into the PR

stx deploy waits for the build, so its --json output already carries the URL:

bash
URL=$(stx deploy --preview --branch "$BRANCH_NAME" --json --token "$SYNTEXT_API_KEY" | jq -r '.url')
gh pr comment "$PR_NUMBER" --body "📖 Docs preview: $URL"

After an API trigger, poll Get Build until status is deployed and read deployUrl.

Note

Preview builds count toward your monthly build quota. They're isolated from production: search on a preview uses that preview's own index and never changes production's, and the AI assistant always answers from the production build. See Production and preview builds.

Was this page helpful? Yes No
Product
Resources
Company
© 2026 SyntextBuilt with Syntext