Build and deployPreviews
Preview deployments
Every branch you push gets a preview with its own address. Branch addresses follow a branch's newest preview, and you choose who can open previews.
A preview is a deployment of any branch other than the production branch. It lets you, your team and your reviewers try a change on a real address before it reaches production. Production is never affected by a preview.
How previews are made
When Preview pull requests is on in the project's settings (it is by default), every push to a branch other than the production branch builds a preview of that commit. Previews use the project's Preview environment variables.
If the branch has an open pull request (a merge request on GitLab), the preview carries its number, so you can find it from the pull request. On GitHub, GitLab and Bitbucket, the commit shows the Orbits – <project> status, which reads "Preview ready" when the preview is up and links to its deployment page. See commit statuses.
You can also build a preview of any branch by hand:
$ orbits deploy --branch feature/checkoutPreviews are built from branches pushed to the repository itself. Pull requests from forks are ignored unless Build pull requests from forks is on in the integration's settings.
Preview addresses
Each preview has two addresses.
| Address | Example | Serves |
|---|---|---|
| The deployment's own | storefront-a1f9c2e.theorbits.app | That one commit, while it's the branch's newest ready preview |
| The branch address | storefront-git-feat-apple-pay.theorbits.app | Whatever the branch's newest ready preview is, so it stays the same as you push |
The branch address is <project>-git-<branch>.theorbits.app, with the branch name made safe for an address (a long one is shortened and given a short hash). Use the address Orbits shows rather than building it yourself. The project's Domains page lists the branch addresses under Follows the branch.
To serve a branch on a domain of your own, such as staging.example.com, add the domain and choose Serve a preview branch. See custom domains.
How long previews are served
Orbits serves the newest ready preview of each branch. An older preview of the same branch stops answering once a newer one is ready.
A preview that hasn't been replaced for a while (14 days) stops being served too, and its address stops answering. Push to the branch again, or redeploy the preview, to bring it back.
On Pro, at most three previews of a project are served at once, the most recently built ones; when a fourth is ready, the oldest stops. Production isn't counted and is never stopped. A preview that stops can be redeployed.
Promote a preview
When a preview looks right, Promote it: Orbits rebuilds its commit with production's variables and makes that production when it's ready. See promote.
Who can open previews
Production is always public. Previews are protected by the project's Deployment protection setting, Who can open preview links:
| Choice | Who gets in |
|---|---|
| Anyone with the link | Anyone. |
| Team members only | Members of the project's team, after signing in to Orbits. The default for new projects. |
| Password | Anyone with the preview password. |
Protection is checked on every request to a preview, at its deployment address and its branch address.
Password
Choose Password, then set the Password for previews (at least 8 characters). A visitor to a preview sees a password page; the right password is remembered in that browser for 12 hours. Changing the password asks everyone for it again. Use Change the password to set a new one; Orbits never shows the current one.
Team members only
A visitor who isn't signed in is sent to Orbits to sign in. A member of the team then gets straight in, and the browser is remembered for 12 hours. Someone not in the team is told they don't have access.
Changing deployment protection is for owners and admins.
Turning previews off
Turn off Preview pull requests under Git in the project's settings, and pushes to other branches stop building. Turning off Deploy every push stops all builds from pushes, production included.
Disconnecting the Git provider also stops previews; existing deployments keep working. See disconnecting.