Deploying Your Project

Once a repository is connected, Orbit deploys on every push to your production branch: it clones the commit, installs dependencies, runs your build, packages the output and starts serving it. This guide covers the full deploy cycle, how to trigger one by hand, and the controls that decide when a deploy is allowed to go live.

How Automatic Deploys Work

Every push to the branch set as Production branch in Settings, then Git, triggers a deploy. Orbit then:

1. Receives the push event from GitHub, GitLab or Bitbucket.
2. Queues a deployment and assigns it a build slot.
3. Clones your repository at that exact commit.
4. Restores your cached node_modules if build cache is available on your plan.
5. Runs your install command (npm ci, yarn install or pnpm install, detected from your lockfile).
6. Runs your build command.
7. Packages the output directory into a deployment artifact and uploads it.
8. Switches the environment to serve the new artifact.

The deployment detail page shows these as named Build phases: Clone, Cache restore, Install, Cache save, Build, Upload, Done. Most projects finish in one to three minutes.

Deploy Statuses

Watching a Build In Progress

The project Overview shows the current build with a live-streaming log in the Latest build panel. Click Full details to open the deployment detail page, which adds a build progress bar, an estimated time remaining, the queue position, and the build timeline broken down by phase.

If your plan allows more than one concurrent build and they are all busy, the page tells you so plainly: it shows how many of your concurrent build slots are in use and starts your deployment automatically when one frees up. You can see every build in flight across all your projects at Orbit, then Queue.

Triggering a Deploy By Hand

There are four ways to deploy without pushing a new commit.

Redeploy the Latest Commit

1. Open the project.
2. Open the Deployments tab.
3. Click the deployment you want, to open its detail page.
4. Click Retry build. Use More retry options, then Retry with cleared cache, if you suspect a stale cached dependency.

Deploy Now

The Deploy now button on the Deployments tab queues a fresh build of the current head of your production branch.

Schedule a Deploy

A deployment can be scheduled for a future time. Orbit snapshots the commit at the moment you schedule it, so the build that runs later is the code you approved, not whatever landed in the meantime.

Deploy Hooks

A deploy hook is a secret URL that queues a build when something sends it a POST request. Use them to rebuild from a headless CMS, a cron job or a CI pipeline. Set them up on the project's Hooks tab. See Triggering Deployments Via Deploy Hooks.

Build Settings

Orbit detects sensible defaults for most projects. Override any of them in Settings, then Build settings:

Leave a field blank to keep the auto-detected value. Full detail, including per-framework values and the mistakes that cause a first deploy to fail, is in Configuring Your Build Command and Output Directory.

Deciding When a Deploy Is Allowed

Orbit has several independent gates. All of them live in Settings.

Deploy Locks

Use a lock to freeze production during an incident, a maintenance window or a code freeze.

1. Open the project.
2. Click Lock deploys.
3. Add an optional reason.

While locked, push-triggered deployments are silently skipped and a banner reads Production deploys are locked with your reason. Manual deploys still work, which is deliberate: a lock stops accidental deploys, not the fix you are trying to ship. Click Unlock deploys to lift it.

Require Approval For Production

Turn on Require approval for production under Deploy protection. Push-triggered production deploys then pause at Awaiting approval until someone opens the deployment and clicks Approve or Reject. Panel deploys and deploy hooks are not affected.

Require Staging Success First

Require staging success before production holds a push-triggered production deploy until the staging environment has deployed the same commit successfully. Someone can still approve manually to skip the wait.

CI Required Checks

Gate deploys on your own CI under CI required checks. On GitHub, enter comma-separated Actions job names and all must pass. On GitLab, any non-empty value waits for the whole pipeline. A CI failure cancels the Orbit deploy automatically.

Deploy Freeze Schedule

Deploy freeze schedule blocks push-triggered deploys outside approved windows: a weekend block, an allowed hour range, or both. All times are UTC. Manual deploys and deploy hooks are unaffected.

Skipping Builds You Do Not Need

• Ignored paths: comma-separated glob patterns. If every file in a push matches, the build is skipped. *.md,docs/** stops documentation commits triggering deploys.
• Branch ignore patterns: pushes from matching branches are skipped entirely. dependabot/*,renovate/* is the common case.
• Git tag deploys: deploy to production when a matching tag is pushed, using a glob like v*.

Build Cache

Orbit caches node_modules between builds on the Liftoff and Apex plans. When a cached install is used, the deployment shows a Cache hit badge and the install phase is dramatically shorter. A cold build shows Cold build instead.

To force a full reinstall, open Settings, then Clear build cache, and confirm. The next deployment for each environment runs a full install from scratch.

When a Deploy Goes Wrong

Orbit can catch a bad deploy for you rather than leaving it live:

• Auto-rollback on failure restores the last healthy deployment automatically if a production deploy fails.
• Health check fetches a path you choose after every production deploy. A non-2xx response within 15 seconds restores the previous healthy deployment.
• Smoke tests run GET requests against up to 10 paths after each successful deploy and record pass or fail. Combined with auto-rollback, a failing smoke test rolls the deploy back.

To undo a deploy yourself, see Rolling Back a Deployment. To work out why a build failed, see Troubleshooting Failed Builds.