OrbitsDocs
esc
    Open Orbits
    Build and deployDeployments

    Deployments

    What starts a deployment, its states and build steps, build logs, deployment addresses, and how to promote, roll back, redeploy and cancel.

    A deployment is one build of one commit. It never changes after it's built: a new push, a new variable or a new setting makes a new deployment. Changing what production serves only moves a pointer from one deployment to another.

    You find them on a project's Deployments page, and across every project on the team's Deployments page.

    What starts a deployment

    TriggerWhen
    createYou create a project from a repository: its first production deployment starts at once.
    gitA push. The production branch builds production, any other branch a preview (see Git providers).
    manualYou deploy by hand, with orbits deploy, or an upload completes.
    redeployYou redeploy an existing deployment.
    promoteYou promote a preview to production.

    To deploy a branch by hand from the CLI:

    Terminal
    $ orbits deploy --prod                     # the production branch's newest commit$ orbits deploy --branch feature/checkout  # a preview of another branch

    Owners, admins and members can deploy, redeploy, promote, roll back and cancel. Viewers can read everything but change nothing.

    A project that runs as a function needs Pro to deploy, redeploy or promote. On Free, what is live keeps running, but new builds of it are refused, and a build started by a push fails with "Pro plan required". See plans.

    States and steps

    StateMeaning
    queuedWaiting for a builder. Shown as building.
    buildingRunning its steps.
    readyBuilt. A production deployment is now live; a preview has its address.
    failedA step failed. Nothing it built went live.
    canceledCanceled by someone, or skipped by the ignored build step.

    Every build goes through the same six steps, each with its own time: Queued, Cloning repository, Installing packages, Building, Uploading and Going live. A step can also be skipped when there's nothing to do in it.

    When a build fails, the deployment page shows why, from the build's own output (for example "Type error in lib/cart.ts, line 42"), and which step stopped. Jump to error scrolls the log to the line.

    Build logs

    The deployment page shows the build log grouped under its steps, with errors in red. While a build runs, the log streams live: lines appear within a second of the build printing them. A build keeps at most 5,000 log lines.

    From the terminal:

    Terminal
    $ orbits logs dpl_…        # a deployment's build log$ orbits logs dpl_… -f     # follow it as it builds

    Through the API, read the lines in pages, or follow them as server-sent events, which also tell you when steps change and when the build has ended. See the deployments API.

    Build logs are about building. For what your app prints and the requests it serves, see runtime logs.

    Preview and production

    Each deployment is either:

    • Production, built from the production branch (or promoted). The one production serves is marked current. Production keeps serving the current deployment until a new one is ready, so visitors never see a half-built site.
    • Preview, built from another branch, with its own address. See previews.

    The Production only filter on the Deployments page shows the deployments that have served production at some point (went_live in the API). The other filters are search (commit message, branch, sha or author), environment, status and branch.

    Deployment addresses

    Every deployment has its own address once its commit is known:

    text
    https://<project>-<first 7 characters of the commit>.theorbits.app

    For example https://storefront-a1f9c2e.theorbits.app. It answers while the deployment is production, or the newest ready preview of its branch. The project's own addresses (<project>.theorbits.app and its custom domains) always serve the current production deployment.

    A few seconds after a deployment is ready, Orbits loads its home page and takes a screenshot of the first screen (1280 by 800). It's on the deployment page, the inspector and the project card. Failed and canceled deployments, and workers, don't get one.

    The deployment page's Open Graph section shows how a link to the deployment looks when it's shared on X, LinkedIn, Facebook or Slack, from the tags on its home page, and warns when, for example, the image is a relative URL some link bots can't resolve.

    The same browser visit checks the page for errors and a blank first screen; see deployment warnings.

    Promote

    Promote takes a ready preview to production. Orbits rebuilds its commit with production's environment variables, as a new production deployment, and that goes live when it's ready. The current version stays live until then.

    Promoting a commit that is already live, or a deployment that isn't ready, is refused. Promoting also turns auto-deploy back on after a rollback.

    Roll back

    Roll back points production at an earlier production build straight away. Nothing is rebuilt, so it takes moments. You can roll back to any of the last three builds that served production.

    After a rollback, auto-deploy pauses, so the next push to the production branch doesn't replace the build you went back to. Pushes still build; they just don't go live. The toast's Undo puts back what production served before. To turn auto-deploy back on, choose Turn it back on from the project's overview (or promote a deployment).

    Terminal
    $ orbits deployments rollback

    Redeploy

    Redeploy builds the same commit again, in the same environment, as a new deployment. A production redeploy takes over when it's ready; production keeps serving the current build until then. Choose:

    • Use the build cache: faster, reuses packages from the last build.
    • Clean build: slower, starts from scratch. Useful when the cache is out of date.

    Redeploy after changing environment variables or build settings, so production picks them up. A deployment that failed before its commit was known rebuilds its branch's newest commit. For an upload project, the archive must still be one of the last five uploads.

    Terminal
    $ orbits deployments redeploy

    Cancel

    Cancel deployment stops a queued or building deployment. A queued one is canceled at once; a building one stops within a few seconds. Nothing it built goes live. A finished deployment can't be canceled.

    Commit statuses

    For projects from Git, each deployment sets a status on its commit, Orbits – <project>, linked to the deployment's page: pending, then passed or failed. See commit statuses.

    Notifications

    A failed deployment shows in the bell and, depending on your team's settings, in email and Slack. So can a production deployment going live. See notifications.

    Through the API

    Listing, creating, redeploying, promoting, rolling back and cancelling deployments, and reading their logs and screenshots, are in the deployments API.

    Was this page helpful?

    Updated