Previews

The three preview hostnames every deployment gets, and how to protect them before a build goes live.

Every deployment is reachable before you activate it. That is the point of a preview: you check the build in a real server environment — real build output, real gateway calls — while your production domain still serves the previous deployment.

Three hostnames per deployment

Each deployment generates three hostnames on the platform's sites domain, and they differ in how long they stay meaningful:

HostnameShapeStays pointed at
Unique<id>.sites.revenexx.ioThis exact deployment, forever
Commitcommit-<commit-hash>.sites.revenexx.ioThe deployment built from that commit
Branchbranch-<branch-name>-<hash>.sites.revenexx.ioThe latest deployment from that branch

The unique one is the permanent address of one build — use it in a review comment or a bug report, where you want the link to keep showing the thing you were looking at.

The commit hostname is keyed to the commit hash, so it's the natural link to attach to a pull request or a CI status.

The branch hostname is the one that moves. It follows the latest build from a branch, which makes it the right link to hand to a stakeholder — "staging is always here" — without re-sending a URL after every push. The trailing hash keeps one branch name from colliding across sites, so don't try to construct these by hand; read them from the deployment.

This is also why commit- and branch- are reserved prefixes on custom domains.

Protecting a preview

A preview host is a real host on the public internet. Before a customer's unreleased storefront is on one, put access control in front of it. Three mechanisms combine:

  • Basic auth — one or more username/password credentials. The simplest way to hand a build to a customer without publishing it.
  • An IP allowlist — addresses and CIDR ranges that get through without a login, for internal networks and monitoring.
  • Path rules — an exclude list of paths that stay reachable without a login (a health check, a webhook receiver), and an include list which, when set, inverts the default: only those paths need a login and everything else is public.

They resolve in that order of specificity: an allowlisted IP wins, then an excluded path, then — if an include list exists — only listed paths are protected, and otherwise everything is.

That last rule is the one to be careful with. Setting an include list makes the rest of the site public. If your intent is "protect everything except the health check", use the exclude list, not the include list.

Preview protection is configured in Cockpit, per domain, under Experience Studio → Domains. The endpoints behind it are not exposed on the public gateway, so this cannot be scripted from a partner integration — plan for it as a one-time setup step rather than something your CI does.

Finding a deployment's preview URLs

Over the API, fetch the deployment:

Shell
curl -s 'https://api.revenexx.com/v1/sites/<SITE_ID>/deployments/<DEPLOYMENT_ID>' \
  -H 'X-Revenexx-Tenant: <tenant-slug>' \
  -H 'X-Revenexx-Api-Key: <api-key>'

Or list them to find the one you want:

Shell
revenexx sites list-deployments --site-id <SITE_ID>

What to check on a preview

A preview catches the class of problem that never appears in npm run dev, because dev mode runs against mocked services and an unminified build. Worth checking every time:

  • Server-rendered pages return real HTML — view source, don't just look at the rendered page.
  • The data domains you switched from mock to live actually resolve, and failures degrade gracefully.
  • Branding is applied on first paint, with no flash of the default palette.
  • The paths you excluded from basic auth really are reachable, and the ones you didn't really aren't.

Related

Was this page helpful?