OutworxOutworx Docs
PR preview deploys · Pro and Business

Every pull request gets its own docs URL.

Push the spec from your CI workflow with --preview and Outworx spins up a throwaway version that never becomes the default, expires in 14 days, and renders a banner with the PR number, commit SHA, and branch. Reviewers click through. No staging tier to provision.

Pro and BusinessReplaces: Vercel preview deploys (for docs) · Netlify deploy previews
Open a PR previewRead the guide
docs.outworx.io/payments-api/preview/247
PreviewPR #247 · feat/checkout-v2 · 8f3a1c0Not production. Expires in 12 days.
Payments API
pr-247
POST/v2/checkoutNew

Create a checkout session with line items and an optional idempotency key.

Request body

{
  "currency": "usd",
  "items": [...],
  "idempotency_key": "..."
}

14 days

TTL, rolls forward on every push

3 lines

In your GitHub workflow YAML

pg_cron

Daily prune at 03:17 UTC

hidden

Excluded from default version list

Push semantics

One flag flips a regular push into a preview.

Same CLI verb, same upload endpoint, same response shape. The --preview flag — plus the GitHub-supplied PR / commit / branch — routes the push to the preview path with full version isolation.

.github/workflows/docs.yml
on: pull_request
- uses: outworx/upload-spec-action@v1
  with:
    token: ${{ secrets.OUTWORX_TOKEN }}
    project: payments-api
    spec: openapi.yaml
    preview: true
    pr: ${{ github.event.pull_request.number }}
    commit: ${{ github.event.pull_request.head.sha }}
    branch: ${{ github.event.pull_request.head.ref }}
1

CI runs the upload action

`outworx/upload-spec-action@v1` with `preview: true` plus the GitHub-supplied PR number, commit SHA, and branch. The composite action wraps `npx @outworx/cli` so there's no Docker pull on every run.

2

Server detects preview semantics

The v1 API endpoint reads `?preview=true&pr=42&commit=…&branch=…`, validates the PAT can write previews, and stamps `is_preview=true` plus the PR metadata onto the new version row.

3

Preview URL is published

The hosted preview lives at `/<slug>/preview/<pr>` with a banner showing the PR number, commit, and branch. Banner links back to the GitHub PR thread for round-tripping.

4

Re-pushes update the row

Every commit on the PR republishes via the same flow. Same row updated, TTL rolled forward, embeddings + cached MCP types invalidated. Customers reviewing the preview see the latest spec without a stale-cache trap.

Version isolation

Customers see your shipped versions. Reviewers see the PR's.

Preview rows live alongside release versions in project_versions but skip the public default-version dropdown unless you pass ?include_previews=true. Separate plan cap keeps previews from crowding out release versions.

  • Hidden from `GET /api/v1/projects/:slug/versions` by default. Pass `?include_previews=true` for admin tooling.

  • Banner on `/<slug>/preview/<pr>` shows the PR number, commit SHA, and branch — and links back to the GitHub PR thread.

  • Re-push the same label as commits land on the PR. Existing row is updated, TTL rolls forward, no 409.

Public version dropdown

  • v2default
  • v1legacy

Reviewers visiting the public docs see only the shipped versions.

?include_previews=true

  • v2default
  • v1legacy
  • pr-247preview · 14d
  • pr-251preview · 12d

Admin tooling sees previews alongside release versions.

14-day rolling TTL

Active PRs keep their preview. Stale PRs prune themselves.

Every push pushes the expiry forward by 14 days. A slow review keeps its preview; an abandoned PR auto-cleans up. Pruning runs in pg_cron at 03:17 UTC, offset from the audit-log + customizations prunes so they don't fight for connection budget.

  • Day 0

    First push opens the preview

    `is_preview = true`, `preview_expires_at = day 14`. Banner shows PR #247 · commit 8f3a1c0 · feat/checkout-v2.

  • Day 5

    Reviewer asks for a copy tweak

    New commit lands. Same row updated, TTL rolls forward to day 19.

  • Day 12

    Final commit before merge

    Same row updated again, TTL rolls forward to day 26.

  • Day 26

    Pruner sweeps the row

    If the PR closed without merge or the team forgot to clean up, pg_cron hard-deletes the row at 03:17 UTC. Cascade clears the preview's request log + cached MCP types.

Plan tiers

Previews on every paid plan.

Free

—

  • No PR preview deploys
  • Standard versions only
  • Upgrade to enable
Most popular

Pro

5 active previews

  • PR preview deploys with `--preview`
  • 5 active previews per project
  • 14-day rolling TTL
  • GitHub Action wrapper
  • Preview banner with PR + commit + branch

Business

20 active previews

  • Everything in Pro
  • 20 active previews per project
  • Audit-log entries on every preview push
  • RBAC: Editor + Viewer roles can push previews
  • Priority support

Pairs well with

CLI + GitHub Action

The CLI is what runs the preview push. `outworx push --preview --pr 42` from any CI runner; three-line action wrapper for GitHub-hosted CI.

Spec Diff

Pair the preview URL with the spec diff comment on the PR — reviewers see what changed AND what it renders as without leaving GitHub.

Audit Log

Every preview push writes a `PREVIEW_CREATED` row with the PR / commit / branch metadata. SOC2 evidence dump captures every preview that touched production.

Spec review on the PR, not after merge.

Pro plan unlocks `--preview` deploys for $9/month flat. Three lines in your workflow file and every PR gets its own clickable docs URL.

Start freeCompare plans