---
title: How to set up a staging environment on Vercel
description: Set up a staging environment on Vercel with custom environments, staged production deployments, or a branch-based preview workflow. Includes Vercel Connect support for custom environments.
url: /kb/guide/set-up-a-staging-environment-on-vercel
canonical_url: "https://vercel.com/kb/guide/set-up-a-staging-environment-on-vercel"
published: 2026-09-09
last_updated: 2026-09-09
authors: Ben Sabic
related:
  - /docs/deployments/environments
  - /docs/domains/working-with-domains/add-a-domain-to-environment
  - /kb/guide/vercel-connect
  - /docs/connect/pricing
  - /docs/cli/deploying-from-cli
  - /docs/domains/working-with-domains/add-a-domain
  - /docs/domains/working-with-domains/assign-domain-to-a-git-branch
  - /docs/environment-variables/managing-environment-variables
  - /docs/deployments/promoting-a-deployment
  - /docs/connect
  - /docs/connect/concepts/project-links
  - /docs/connect/concepts/triggers
install_vercel_plugin: npx plugins add vercel/vercel-plugin
---

Staging environments let you verify changes in a live, production-like setting before your users see them. Vercel supports staging through custom environments, staged production deployments, and branch-based preview workflows, so you can pick the approach that matches your team's release process and plan.

Each workflow below includes setup steps and the relevant CLI commands. You'll also learn how to scope Vercel Connect token access and webhook triggers to a custom environment, so staging deployments can use connectors without touching production.

## Overview

In this guide, you'll learn how to:

- Create a custom environment for staging with branch tracking, a domain, and its own variables
  
- Scope Vercel Connect token access and triggers to a custom environment
  
- Stage a production deployment and promote it after verification
  
- Set up a branch-based staging workflow on any plan, including Hobby
  

## Choosing a staging workflow

| Workflow                      | Use it when                                                                                  | Availability               |
| ----------------------------- | -------------------------------------------------------------------------------------------- | -------------------------- |
| Custom environment            | You need a named environment with its own branch tracking, domain, and variables             | Pro and Enterprise         |
| Staged production deployment  | You want to verify a build with production configuration before assigning production domains | All plans                  |
| Branch-based preview workflow | You want a persistent staging branch with a domain and branch-specific variables             | All plans, including Hobby |

These workflows complement each other. Many teams pair a custom environment for day-to-day staging with staged production deployments as a final check before release.

## Setting up a custom environment for staging

Custom environments let Pro and Enterprise teams define pre-production environments like `staging` or `qa` directly in the dashboard, without external workarounds or multiple projects. Pro plans include one custom environment per project, and Enterprise plans include 12, with additional capacity available in packs of five for $50 per month. To learn more, see [Custom environments](https://vercel.com/docs/deployments/environments#custom-environments).

To create one:

1. Go to your project's **Settings** > **Environments** in the Vercel dashboard.
   
2. Click **Create Environment** and name it, for example `staging`.
   
3. Configure the environment with any of the following options.
   

| Option                                                                                                         | What it does                                                                                                    |
| -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| [Branch tracking](https://vercel.com/docs/deployments/environments#branch-tracking)                            | Automatically deploys to the environment when a pushed branch name matches the rule                             |
| [Attach a domain](https://vercel.com/docs/domains/working-with-domains/add-a-domain-to-environment)            | Gives the environment a persistent URL, such as `staging.example.com`, that always serves its latest deployment |
| Environment variables                                                                                          | Sets values scoped to this environment, such as staging database credentials                                    |
| [Import variables](https://vercel.com/docs/deployments/environments#import-variables-from-another-environment) | Seeds the environment with variables copied from another environment                                            |

After setup, push to a matching branch to deploy to staging. You can also work with the environment from the Vercel CLI:

```bash
# Deploy to a custom environment named "staging"
vercel deploy --target=staging

# Pull environment variables from "staging"
vercel pull --environment=staging

# Add an environment variable to "staging"
vercel env add MY_KEY staging
```

### Using custom environments with Vercel Connect

[Vercel Connect](https://vercel.com/kb/guide/vercel-connect) lets your deployments request provider tokens (for services like Slack) and receive verified webhooks through connectors. Connect supports custom environments, so a staging deployment can use a connector without enabling it for Production, Preview, or Development.

In the dashboard, custom environments appear alongside the built-in environments when you add or edit a project on a connector. From the CLI, pass the environment's slug to `--environment`:

```bash
vercel connect attach slack/acme-slack --environment staging
```

Passing `--environment` replaces the default environments, so this project link only allows token requests from `staging` deployments. If the calling environment isn't on the project link, the token request fails with `ClientNotEnabledForEnvironmentError`.

Trigger destinations can also target a custom environment, so Connect forwards incoming webhooks to your staging deployment:

```bash
vercel connect attach slack/acme-slack --environment staging --triggers \
  --trigger-environment staging --trigger-path /api/slack-events
```

Before targeting a custom environment with triggers, deploy to it and [assign it a verified domain](https://vercel.com/docs/domains/working-with-domains/add-a-domain-to-environment). Vercel Connect forwards events through that domain, so it must serve the environment's latest deployment directly rather than redirect to another location.

Project links control which deployments can request tokens, but they don't restrict a provider token after it's issued. When environments need provider-level isolation, create a separate connector for each environment and request only the scopes it needs. Vercel Connect is generally available on all plans and is billed per token request; custom environments require a Pro or Enterprise plan. See [Vercel Connect pricing](https://vercel.com/docs/connect/pricing) for included allowances and rates.

## Staging and promoting production deployments

In addition to a staging environment, you can create staged production deployments that aren't immediately assigned to your production domains. This lets you verify your production build, with production environment variables, before making it live to your users.

### Creating a staged production deployment

1. Go to your project's **Settings** > **Environments** > **Production** section.
   
2. Disable the **Auto-assign Custom Production Domains** option under the **Branch Tracking** settings.
   

When you push to your production branch, Vercel creates a production deployment but does not assign it to your domains. The deployment appears as **Staged** in the dashboard, and you can verify it via the generated URL.

### Promoting a staged deployment

After verification:

1. Navigate to the **Deployments** tab and select your staged production deployment.
   
2. Click the **(...)** menu in the top-right corner.
   
3. Select **Promote to Production** and confirm.
   

Promotion assigns your production domains to the deployment without a rebuild, so the change takes effect immediately.

You can also run this workflow from the [Vercel CLI](https://vercel.com/docs/cli/deploying-from-cli#deploying-a-staged-production-build) to support custom CI scripts:

```bash
# Create a production deployment without assigning production domains
vercel deploy --prod --skip-domain

# Promote the staged deployment when you're ready
vercel promote your_deployment_url_here
```

If you discover a problem after promoting, `vercel rollback` instantly restores the previous production deployment.

Staged production deployments use production environment variables, so testing can access production services and data. Use a custom environment or the branch-based workflow below when you need separate staging resources.

## Setting up a branch-based staging workflow

For Hobby users, or teams that can't use custom environments, you can build a staging workflow from a preview branch by assigning it a dedicated domain and branch-specific environment variables.

### 1\. Add a staging domain

1. Go to your dashboard and select your project, then select the **Settings** tab.
   
2. In the **Domains** section, [add a custom domain](https://vercel.com/docs/domains/working-with-domains/add-a-domain) such as `staging.example.com` and configure its DNS records.
   
3. Follow the steps to [assign it to a Git branch](https://vercel.com/docs/domains/working-with-domains/assign-domain-to-a-git-branch), selecting **Preview** and entering your staging branch name.
   

> **Warning:** When you add a domain, Vercel first assigns it to your default branch. Click **Edit** on the domain and assign it to your staging branch.

### 2\. Add branch-specific environment variables

1. In the same **Settings** tab, open the **Environment Variables** section.
   
2. [Add your environment variables](https://vercel.com/docs/environment-variables/managing-environment-variables#declare-an-environment-variable), select the **Preview** environment, and scope them to your staging branch.
   

Branch-specific variables override other variables with the same name, so you don't need to replicate every existing Preview variable. Add only the values you want to override, such as a staging database URL:

```bash
# Applies to all preview branches
DATABASE_URL=postgres://preview_db_url_here

# Overrides DATABASE_URL on the "staging" branch only
DATABASE_URL=postgres://staging_db_url_here
```

### 3\. Deploy your staging branch

Push to your staging branch to create a preview deployment at your staging domain. Environment variables apply at build time, so after adding or changing them, redeploy your latest staging [preview deployment](https://vercel.com/docs/deployments/environments#preview-environment-pre-production) to pick up the new values. When testing is complete, merge the branch into your production branch and keep the staging branch for future changes.

## Next steps

- Learn more about [environments on Vercel](https://vercel.com/docs/deployments/environments), including custom environments
  
- Read about [promoting deployments](https://vercel.com/docs/deployments/promoting-a-deployment) and instant rollback
  
- Explore [Vercel Connect](https://vercel.com/docs/connect) concepts, including [project links](https://vercel.com/docs/connect/concepts/project-links) and [triggers](https://vercel.com/docs/connect/concepts/triggers)
  
- See [assigning a domain to a Git branch](https://vercel.com/docs/domains/working-with-domains/assign-domain-to-a-git-branch) for the branch-based workflow