Work with environments

Create staging, fork service configuration, and manage pull-request previews.

Copy page

Create an environment to run a separate set of services. Start empty, fork an existing environment’s configuration, or create a pull-request preview with an expiry policy. A fork does not copy secrets or stored data.

Before you start

• Have a product with Deployment connected. Its production environment already exists.
• Choose a name of up to 80 characters and a slug of up to 40 characters. Slugs must be unique in the product; production is reserved.
• A fork or preview needs a base environment in ready status.
• For MCP, use a product-scoped token with Deployment write for creating, forking or reconciling, read for inspection, and admin for preview policy changes or deletion.

1. Create an environment

For an empty environment, choose New environment in the Product App’s Environments list, or call deployment_environment_create. A slug is derived from the name unless you supply one.

For a copy, call deployment_environment_fork with the ready base environment and the new name. The copy includes:

The fork automatically deploys copied services with at least one replica and provisions copied databases. Add the missing secrets and redeploy services that require them. A paused job stays paused in the fork.

2. Wait for readiness

Read the environment status with deployment_environment_get.

Use Environment → Settings → Overview to rename or reconcile the environment. deployment_environment_reconcile retries preparation or teardown after a failed state. Renaming changes the name; the slug remains fixed.

3. Configure previews if needed

In the base environment, open Settings → Preview Policy, or use deployment_preview_policy_set.

Choose New preview in the Environments list’s Previews section, or call deployment_preview_environment_create. The preview is tied to a pull request and gets slug pr-<number> and name PR #<number>.

Creation is refused if the policy is disabled, its preview limit is reached, a preview for that pull request exists, or the base is not ready. Fork exclusions still apply: set secrets separately and do not expect production data.

New commits on the pull request redeploy repository-backed services and reset the lifetime. Closing or merging the pull request schedules deletion after a 15-minute grace period. Inactivity also expires the preview. Cleanup runs every few minutes, so teardown may begin after the deadline. You can delete a preview from the banner above its canvas or with deployment_preview_environment_delete.

Verify it works

Confirm the new environment is ready, then inspect its services, variables and domains. In a fork, check that generated hostnames differ from the base and required secrets have been set. Open an active service’s generated URL and verify the staging or preview behavior before sharing it.

What stays separate

Environment and service variables, services, release histories, volumes and environment-managed databases are separate records. Private networking does not cross environment boundaries. Product-level variables are inherited, and product-level Managed Postgres can be attached across environments; see storage choices.

Delete an environment

deployment_environment_delete stops the environment’s workloads and removes its services and release histories. The status becomes deprovisioning while resources are released. Read any teardown failure before retrying reconciliation.

The environment delete action refuses production. Do not use environment deletion as a backup or recovery workflow.