Environments vs Preview Deployments

Stackpad has two ways to run multiple versions of your application: environments and preview deployments. They solve different problems and have different trade-offs.

At a glance

	Environments	Preview Deployments
Created by	You (manually)	Automatically on push to feature branch
Lifetime	Persistent — until you delete it	Ephemeral — cleaned up when branch is deleted
Infrastructure	Fully isolated (own DB, cache, network)	Shares database and cache of parent environment
What gets cloned	All services (web, DB, cache, tools)	Only git-based services (web apps)
Own database	Yes — fresh credentials, separate data	No — uses the catch-all environment’s database
Cron jobs	Active	Disabled (safety measure)
Use case	Staging, QA, demo, long-lived branches	Code review, PR previews, quick testing

How environments work

When you create an environment, Stackpad clones every service from the production environment into a new, isolated copy:

• A new Docker network is created
• All databases, caches, and services get their own containers
• Fresh credentials are generated and auto-injected
• The environment is linked to a Git branch for automatic deploys

Environments are persistent. They run until you delete them. Use them for staging, QA, or any branch that needs its own full stack.

See Environments for setup instructions.

How preview deployments work

Preview deployments are triggered automatically when you push to a feature branch that doesn’t match any environment’s linked branch. Here’s the flow:

1. You push to feature/auth
2. GitHub webhook fires
3. Stackpad checks: does any environment have branch = "feature/auth"?
4. No match — falls through to the catch-all environment
5. Stackpad clones only the git-based web services into the catch-all environment
6. Each preview gets a unique subdomain (e.g. feature-auth-web--myapp.stackpad.eu)
7. Push again to the same branch — the existing preview is redeployed (no duplicates)
8. Delete the branch on GitHub — the preview is automatically cleaned up

What previews share

This is the most important thing to understand: preview deployments share the catch-all environment’s infrastructure. They don’t get their own database, cache, or network. Your preview web app connects to the same DATABASE_URL as every other preview in that environment.

Database safety

Because previews share a database, do not test destructive database migrations in preview deployments. A bad migration in one preview affects all other previews and the catch-all environment itself. Use a dedicated environment if you need to test schema changes safely.

When to use which

Use an environment when:

• You need a separate database (e.g. staging with its own data)
• You’re running long-lived branches (develop, release/*)
• You need to test database migrations safely
• You want a QA or demo environment for stakeholders
• You need cron jobs running in the non-production branch

Use preview deployments when:

• You want automatic PR previews for code review
• The change is frontend or API-only (no schema changes)
• You want a quick, disposable preview of a feature branch
• You don’t need isolated data — sharing the dev database is fine

The catch-all environment

Preview deployments require a catch-all environment. This is an environment with the catch-all flag enabled, which accepts pushes from any branch that doesn’t match a specific environment.

A common setup:

Environment	Branch	Catch-all
Production	main	No
Staging	develop	No
Development	—	Yes

In this setup:

• Pushes to main deploy to Production
• Pushes to develop deploy to Staging
• Pushes to any other branch create a preview in Development

What’s next?

• Environments — create and manage environments
• Preview deployments — configure automatic previews
• Environment variables — how variable cascading works across environments