Branch Preview Deployments In Orbit

Branch previews build every non-production, non-staging branch you push to its own isolated URL, so you can click through a change in a real environment before it merges. This guide covers turning them on, where the URLs come from, how previews are cleaned up, and how to stop preview builds leaking production secrets.

Enabling Branch Previews

Open your project in Orbit.
Open the Settings tab.
Find the Runtime section and turn on Branch previews.

Once enabled, every push to a branch that is neither your production branch nor your staging branch triggers a build and deploys it to its own preview environment.

Branch previews toggle in Orbit project settings

Branch previews are a per-project toggle, not a paid add-on. They are available on every Orbit plan, including the free Launch plan. What differs by plan is how many environments a single project can have at once: Launch allows 2 (production plus one preview), Liftoff 4, and Apex 11. Once a project is at its environment limit, further branches will not get their own preview until you delete one.

Preview URLs

A preview gets a hostname derived from its branch name: the name is lowercased, every character that is not a letter, digit or hyphen becomes a hyphen, runs of hyphens collapse, and the result is truncated to 48 characters and prefixed with branch-.

Branch	Preview hostname
`redesign`	`branch-redesign.kaps.run`
`feat/new-checkout`	`branch-feat-new-checkout.kaps.run`
`JB/Fix_Cart`	`branch-jb-fix-cart.kaps.run`

Preview URLs are publicly reachable by anyone who has the link. They are not indexed or advertised, but they are not access-controlled either. Do not use a preview to review anything that must not leave your team, and do not point a preview at production data. If you need a protected pre-production environment, use a staging environment instead: staging supports a password and an IP allowlist under Settings, in the Staging: access protection and Staging: IP allowlist sections.

Where Previews Appear

The project Overview tab has a Preview deployments section listing every active preview. Each row shows:

The branch name, and a PR #number badge linking to the pull request when the branch has one open
The current status (QUEUED, BUILDING, or live)
How long ago it deployed
A link to open the preview URL
View logs to open the deployment detail page
A delete button

Each preview is a fully isolated environment with its own URL, its own build and its own environment variables. Nothing it does can affect production.

The project Branches tab gives the same information organised per branch, which is easier to scan when you have several open at once.

Environment Variables In Previews

This is the part worth getting right. A variable scoped to All environments (project-wide) is injected into preview builds, and a preview URL is public.

Keep production credentials scoped to your production environment only.
Give previews test-mode or sandbox credentials for third-party services.
Never leave a production database URL or a live payment key at project-wide scope.

The full mechanics, including how to add a production-only variable and how staging inheritance works, are in Setting Environment Variables Per Environment.

Build Logs For a Preview

Click View logs next to any preview to open its deployment detail page. Previews get the same treatment as production deployments: full streaming build log, build phases, commit and author, artifact size, cache hit or cold build, detected framework and package manager, and the AI diagnosis button when a build fails.

Deleting a Preview

Click the delete button on the preview row and confirm.

Deleting a preview removes the environment and its entire build history, not just the current deployment. It cannot be undone. The branch itself is untouched, so pushing to it again creates a fresh preview from scratch, with no history and a cold build cache.

Automatic Cleanup

You do not have to tidy up after yourself.

When a pull request is closed or merged, its preview environment is paused immediately and stops serving. Visitors get a 404 rather than a stale build.
Deleting a branch pauses that branch's preview the same way.
Paused previews are garbage-collected about a day later: the source tarballs, build artifacts and build caches are deleted and the environment is archived.

You can also expire previews on a schedule. In Settings, find Preview expiry and choose Never, 7, 14, 30 or 60 days. Previews older than that are paused automatically and cleaned up within 24 hours.

On a busy repository, set Preview expiry to 14 or 30 days. Every active preview counts against your project's environment limit, and expired ones are the usual reason a new branch quietly fails to get a preview.

Approval and Previews

If Require approval for production is enabled under Deploy protection, it applies to production only. Preview builds are not held for approval.

To stop a specific preview deploying further changes without deleting it, pause the environment from the Environments tab. New deploys to a paused environment are skipped until you resume it.

Troubleshooting

A branch pushed but no preview appeared. Check, in order: is Branch previews on in Settings, then Runtime? Is the branch actually your staging branch (staging deploys to staging, not to a preview)? Does the branch match one of your Branch ignore patterns, for example dependabot/*? Is the project already at its environment limit for your plan?

The preview built but shows a 404. The build succeeded but the output directory is probably wrong for this branch. Check Output directory in Settings, and remember a branch can change the build output without changing the setting. See Configuring Your Build Command and Output Directory.

The preview shows an older commit. Pushing a new commit while a build for the same branch is still running cancels the in-flight build and starts a new one. If you see a cancelled deployment followed by a running one, that is expected. Wait for the second build.

A closed PR's preview is still reachable. Pausing happens on the webhook event. If the provider connection was disconnected when you closed the PR, the event never arrived. Delete the preview manually from the Overview tab.