Deployment environments
Testing → staging → production stages under a project — Duplicate, Promote, protected production, and how they differ from Variables.
What is an environment?
A deployment environment is a named stage under a project: typically testing → staging → production. Each stage has its own copy of the service graph, per-stage variables, git branch routing, and optional custom domains.
Naming: Workspace = team + billing. Environment = stage (this page). Variables = env keys on project / group / service — see Variables. Never say “workspace env” when you mean Variables.
Every project always has a production environment. Extra persistent stages are created with Duplicate. Free plans are production-only; Starter and Pro can add more (see Pricing).
Hierarchy
Workspace → Project → Environments → Services + Databases (per environment).
Services in different environments share a logical pairing key (logicalKey) so Promote and the “Open in Staging/Production” jump know which rows match.
Pipeline & switcher
With deployment environments enabled:
- Project Overview becomes a Pipeline board — one column per persistent environment (left → right by position).
- The header environment switcher sets the active stage (
?environment={slug}; remembered per project). - Manage environments (from the switcher) renames, reorders, sets preview-base, protects, or deletes non-production stages.
Duplicate
Duplicate clones an existing environment’s graph into a new slug (for example staging):
| Copies | Does not copy |
|---|---|
| Services (new IDs, same names / logical keys) | Secret values (keys are created blank) |
| Non-secret variable values | Production / source data |
| Empty managed Postgres (optional) | Custom domain routes (you bind stages separately) |
| Env group attachments on cloned services |
Default git branches often match the slug (staging). Prefer turning auto-deploy off on production when you add a soak stage so only Promote (or an explicit deploy) goes live.
Quota: Free cannot create a second persistent environment (402). Starter ≤ 3, Pro ≤ 10. Duplicated services and databases also count toward service/DB caps.
Promote
Promote moves a soaked image digest (or rebuilds a static site at the same git SHA) from a source environment into a target — it is not a git merge.
- Soak on staging (git push or manual deploy).
- Open Promote → on the pipeline (or
bytstack environment promote). - Confirm pairing (matched / missing counterparts), hosts on protected targets, and optional “create missing services.”
Production is protected by default: only owners/admins can promote into it, reveal secrets there, or bind custom domains to the stage. Developers may still promote into unprotected environments when permitted.
CLI: stage promote is
bytstack environment promote. Sharing a variable to project scope remainsbytstack env promote(Share to project in the UI).
Sync (config drift)
After Duplicate, if you add a service or variable key to one stage, use Sync to propagate config only into another stage:
- Creates missing services (same
logicalKey) and empty databases - Copies missing variable keys (secrets blank)
- Reports domain route differences (you still bind stages manually)
UI: Manage environments → Sync from…. CLI: bytstack environment sync production --to staging --dry-run.
Git vs Promote
| Path | When to use |
|---|---|
| Git-track | Each environment has its own branch + autoDeploy (e.g. staging → staging column). |
| Promote | One build soaks on staging; the same artifact goes to production without a second rebuild (digest path). |
Static sites and services with bake env at build may rebuild at the same SHA so target-environment variables are applied.
Domains
Custom domains bind to persistent environments only (Patterns A/B). Previews never get customer custom routes. See Custom domains.
Variables
Keys are shared conceptually across stages; values overlay per environment. After Duplicate, fill blank secrets on the new stage. ${{service.name.URL}} and similar references resolve inside the current environment. Details: Variables.
Key rules
- Workspace ≠ Environment ≠ Variables — billing team vs stage vs env keys.
- Free = production only; Starter for staging (up to 3); Pro up to 10.
- Duplicate never copies secret values or data — keys blank; DBs empty when cloned.
- Promote copies the image (digest), not a git merge by default.
- Custom domains on persistent stages only — not PR previews.
${{service.name.URL}}is in-environment — never another stage’s host.- Production is protected — owner/admin for promote-in, secrets, and domain binds.
CLI
bytstack environment list
bytstack environment duplicate --from production --name Staging --slug staging --yes
bytstack environment select staging
bytstack env pull --scope project --file .env.staging
bytstack environment promote staging --to production --yes --watchSee CLI.
Plan caps
| Plan | Persistent environments |
|---|---|
| Free | 1 (production only) |
| Starter | 3 |
| Pro | 10 |
Ephemeral PR previews do not consume this cap. Full limits: Pricing.