Previews

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:

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 teammate — "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.

Who can open a preview

Preview hostnames are not public. All three require a signed-in Cockpit user who is a member of your tenant. A request without that session is redirected to a Cockpit sign-in page instead of getting the build. Revoking someone's tenant membership revokes their access to previews as well.

This has two practical consequences:

• A link to a preview is no use to someone outside your tenant. To show a customer or stakeholder a build, add them to the tenant, or point a domain at the site and protect it as described below.
• A monitor, a visual-regression job or a crawler can't fetch a preview anonymously.

A domain you point at a site is a different case. It serves the active deployment to anyone, so the next section is about that.

Protecting a domain

A custom domain 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 keep an unreleased storefront on a real domain private.
• 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.

Finding a deployment's preview URLs

Over the API, fetch the deployment:

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:

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.
• Environment variables are the site's own: a preview runs with the same variables as your production deployment, not a separate set, so it talks to the same tenant data.
• On a domain you protected, the paths you excluded from basic auth really are reachable, and the ones you didn't really aren't.

Related

• Deployments — statuses, and what ready means
• Instant rollbacks — promoting a previewed deployment, and going back
• Domains — pointing a real domain at the site