Branching
A branch is an isolated environment for one line of work. Every branch in a project owns its own services, deployments, and any databases created on it, so preview deploys never share Compute resources with production. One caveat: a database your app reaches through a DATABASE_URL environment variable is only as isolated as that variable's value. Give previews their own preview-scoped DATABASE_URL. See Environment variables for details.
A platform branch usually matches a Git branch name, but in Prisma it is a real resource that owns its own services and databases:
How Compute organizes resources and isolates branchesStep 1 of 3
Your first deploy creates the project, its default production branch, and the infrastructure that runs it: an app, a database, and its production-scoped variables.
Every branch has a role:
- The first branch in a project is your production branch, usually
main. It's protected and durable: with deploy on push set up, pushes to your default Git branch deploy to it, and automated cleanup never touches it. - Every other branch is a preview by default: disposable resources for testing changes before they merge.
To learn more, see the Deployments docs.
Commands that take a branch resolve it in this order:
--branch <name>, if you pass it.- Your active Git branch.
main.
Inside a Git repo, running service list from feature/search targets the feature/search branch automatically. To target a branch explicitly:
bunx prisma service list --branch feature/searchpnpm prisma service list --branch feature/searchyarn prisma service list --branch feature/searchnpx prisma service list --branch feature/searchInspect platform branches:
bunx prisma branch listpnpm prisma branch listyarn prisma branch listnpx prisma branch listListing branches doesn't expand the services and databases inside them. Use the service and postgres commands to inspect those.
Listing branches doesn't expand the services and databases inside them. Use the service and postgres commands to inspect those.
You rarely create branches manually. They are created automatically:
- From GitHub: when a repo is connected, creating a Git branch creates the matching platform branch, and your repository's deploy workflow deploys each push to it as a preview. To set this up, see the GitHub integration docs.
- From the CLI: commands that target a branch that doesn't exist yet, such as
service create --branch feature/searchor a Composer stage deploy, create it.
Connecting GitHub doesn't create branches retroactively. It aligns your default branch with the repo's default branch and wires up automation for future events.
When GitHub is connected, deleting a Git branch tears down the matching platform branch, as long as it isn't your production or default branch. Those are always left alone.
- Environment variables: preview values and per-branch overrides.
- Deploy on push: a preview environment for every branch you push.
- GitHub integration: keep platform branches in sync with your repo.