An environment is an isolated deployment target within an app. Each environment has its own deployments, variables, custom domains, and gateway policies.
Production and preview#
Every app gets two environments:
| Environment | Purpose |
|---|---|
| Production | Serves live traffic. |
| Preview | For testing branches before merging. |
Unkey creates both environments automatically when you create a project. You don't need to set them up manually.
Custom environments beyond production and preview are not yet available.
Branch mapping#
When you connect a GitHub repository, Unkey maps branches to environments:
- Pushes to the default branch (typically
main) deploy to production. - Pushes to any other branch deploy to preview.
Each push creates a new deployment in the corresponding environment.
Environment-scoped configuration#
Configuration is scoped per environment, so production and preview can differ:
- Variables: Different database URLs, API keys, and feature flags for each environment
- Custom domains: Production might use
api.acme.comwhile preview uses auto-generated domains - Regions and instances: Run production in multiple regions with higher instance counts, and preview in a single region
- Gateway policies: Apply stricter rate limits or authentication rules in production
Sticky domains#
Each environment has a sticky domain that always points to the latest deployment in that environment:
When a new deployment reaches the Ready state, the environment domain updates automatically. You don't need to reconfigure DNS or update your clients.
Production environments also get a live domain without the environment name:
See Wildcard domains for the full domain naming pattern.
Deployments per environment#
An environment can have many deployments, but only one is active at a time.
In production, when a new deployment goes live, the previous one stops after 30 minutes. Stopped deployments are available for rollbacks, but take longer to serve traffic because their containers need to start again.
In preview environments, deployments stay running as long as they receive traffic. Idle preview deployments (zero requests for 1 hour) automatically stop to free up resources.