Deployments and environments

Every product in your factory ships through environments. An environment is one running copy of your product — a preview, a staging site, production — with its own version, its own hostname, its own deploy rules and its own history.

This page covers where products deploy to, what starts a deploy, and what you can see and undo afterwards.

Where products deploy to

Your factory has a default deploy target, set in Settings → Deployment. A product can override it, and a single environment can override the product:

factory default  →  product  →  environment

Pick a mode first, because it decides everything else:

Mode	What happens
GitOps	Your repository owns the deploy. Sapient writes and maintains the CI workflow; your own pipeline ships on merge, wherever it already ships to. There is no target for us to choose, so the provider grid is switched off.
Managed	Sapient deploys directly through the provider’s API after the deploy gate. Choose the provider below.

Taking over a workflow you already own is refused

If your repository already has its own deploy workflow, Sapient will not overwrite it. That is a hard refusal, not a warning you can click through.

Managed targets: Vercel, Netlify, Cloudflare, Cloud Run, AWS, and Sapient Deploy — Sapient’s own hosting, which needs no account at all. Connect them under Settings → Connectors — see the connectors overview.

Project name, build command and output directory are detected from the product’s repository the first time it deploys. Set them on the environment only if the detected values are wrong.

What starts a deploy

Each environment has a trigger, set on its own page:

Trigger	Meaning	Status today
Manual only	Nothing ships until someone presses Deploy now or signs the pipeline’s per-story deploy approval.	Active
When a sprint completes	Stories finish and merge without deploying. When the sprint’s last story lands, one release approval opens; signing it ships the whole sprint in a single production deploy.	Active
On every pull request	A throwaway copy per open PR, torn down when it merges.	Recorded, not yet running
Promote from another environment	Follows an upstream deploy after a soak you set.	Recorded, not yet running

Two triggers are configuration, not automation — yet

You can set On every pull request and Promote from another environment today, and the setting is saved and shown everywhere. But nothing runs them on a schedule yet: deploys still happen when someone presses Deploy now or when a release approval ships one. The environment page says so rather than showing a countdown for a timer that will not fire.

Releasing a whole sprint at once

With the production trigger set to When a sprint completes, no story ships on its own — each one finishes, merges, and rests as done. The moment the sprint’s last story lands, one approval appears in your inbox naming the sprint and every story in it. Signing it runs a single production deploy that contains all of them, and only then do the stories read deployed.

Three honesty rules apply:

• An unmerged story blocks the release. If a story is finished but its pull request is still open, the build would not contain it — so the release approval will not open, and an incident tells you which pull requests to merge (or which stories to cancel).
• Rejecting the release keeps everything parked at done. Nothing ships, and you are not asked again for the same set of stories. A story completed later reopens a fresh release approval covering everything still waiting.
• Stories without a sprint keep the per-story approval. There is no release to batch them with.

Nothing ships to production without you

Deploys are governed by your approval and spend policy, and there are two paths:

• The engineering pipeline opens an approval for you to sign — per story under a manual trigger, or one per release under a sprint trigger. Nothing ships until you do.
• Deploy now, on an environment page, asks to deploy immediately. If your policy allows it, it runs. If it does not, it is refused and tells you why — it is not queued behind your back.

Settings → Deployment → Production release policy records how you want releases handled: whether they should go automatically once staging has held healthy, how long that soak should be, who signs when it is off, and whether a bad-health reading should roll a release back.

The release policy is saved, not yet acted on

Those preferences are stored and shown on every environment, but no scheduler runs them yet — nothing releases on its own today. Automatic release is on our roadmap.

The environment page

Open an environment from the product page, from Settings → Deployment, or from the engineering release pipeline.

• Header — health, hostname, running version, when it last deployed, and Deploy now, Roll back and Logs & traces.
• How this environment gets deployed — the trigger, the branch it deploys, and (for a promoted environment) the source, the soak, whether every story must have passed verification, and whether a health breach upstream should cancel the promotion.
• Deploy setup — target, mode, project, branch, where it serves, and your custom domain.
• Secrets — the variable names this environment injects and where each is stored. Values are never stored in Sapient and are never shown anywhere in the app; only an owner or maintainer can see even the names.
• Delivery metrics — deploy frequency, change failure rate and time to restore over 24 hours, 7 days or 30 days.
• Deploy history — every deploy into this environment, what started it, and whether it stuck.

A dash means “not measured”, never zero

A metric with nothing behind it shows — and explains why, rather than a zero that would read as a real measurement. A brand-new environment has not deployed anything, so it has nothing to measure.

Lead time currently always shows a dash: it is the time from merge to deploy, and merge timestamps are not recorded on pull requests yet.

Rolling back

Roll back restores the deploy that previously served an environment. You can also restore a specific earlier deploy from the history list.

A rollback is gated exactly like a deploy — rolling production back is as consequential as shipping to it, so it opens the same approval. It is recorded as its own entry in the history rather than quietly resurrecting an old one.

Some providers cannot roll back through their API. When that is the case Sapient says so and asks you to redeploy the previous version instead.

The environment ladder

Settings → Deployment → Environment ladder is the set of environments you want a new product to start with — typically Preview, Staging and Production, each with its branch and trigger.

It is a template. Editing the ladder never changes the environments a product already has; add or remove those on the product itself.

Not yet applied automatically

Creating a product does not yet create these environments for you — add them on the product with Add an environment. Applying the ladder at product creation is on our roadmap.

Adding an environment

On a product page, use Add an environment. Name it (canary, demo, EU — anything), optionally copy the deploy setup from an existing environment, and choose how it gets deployed.

Copying deploy setup copies the target and branch. It does not copy secrets: those are written through the connector that owns them, so they are attached per environment rather than duplicated.

A new environment starts empty, with no metrics and no history, until something ships to it.