Custom environments

By default, all teams use three environments when developing their project: Production, Preview, and Development. However, teams can also create custom environments to suit their needs. To learn more about the limits for each plan, see limits.

Custom environments allow you to configure customized, pre-production environments for your project, such as staging or QA, with branch rules that will automatically deploy your branch when the branch name matches the rule. With custom environments you can also attach a domain to your environment, set environment variables, or import environment variables from another environment.

Custom environments are designed as pre-production environments intended for long-running use. This contrasts with regular preview environments, which are designed for creating ephemeral, short-lived deployments.

Team members with Owner or Project Administrator permissions can create custom environments through the Vercel dashboard.

1. From the Vercel dashboard, ensure your team is selected in the scope selector, and select the project that you wish to configure custom environments for.
2. Navigate to the Settings tab and go to Environments.
3. Click the Create Environment button.
4. Enter your environment name. Only letters, numbers, underscores, and hyphens are allowed.
5. Optionally, choose the settings for your environment:
   • Branch Tracking: Choose the branch that you want to track for this environment.
   • Attach Domain: Choose whether you want to attach a domain to this environment.
   • Import variables from another environment: Choose whether you want to attach the environment variables from another environment.
6. Click Create Environment.

1. Before interacting with your custom environment in the CLI, you'll need to follow the steps to create your environment through the Vercel dashboard.
2. Use your normal workflows, but specify the environment as shown in the supported commands section. For example:
   terminal

   vercel env add MY_API_KEY staging
   vercel pull --environment=staging
   vercel deploy --target=staging

Supported CLI commands include:

• vercel deploy
  • Use the --target flag to deploy to a specific environment.
• vercel redeploy
  • Use the --target flag to redeploy to a specific environment.
• vercel build
  • Use the --target flag to build for a specific environment.
• vercel pull
  • Use the --environment flag to pull from a specific environment.
• vercel env
  • Use the environment name as an argument to manage environment variables for a specific environment.

With custom environments, you can choose the branch that you want to track for the environment. You can also track the same branch for multiple environments (for example, main).

To enable branch tracking, toggle the Branch Tracking option and specify a branch name, prefix, or suffix.

It may be necessary for your team to use a persistent URL for your custom environment, making it easier for your team to share and identify the environment. You can attach a domain to your environment, which will point to the latest successful build for that environment.

Once you add the domain URL, you'll need to configure the DNS settings to point to Vercel.

When you create an environment, you can choose to do an initial sync of all environment variables from another environment. This is useful when you want to create an environment that is similar to another environment, but with a few changes.

This creates a single environment on Vercel that is then referenced by multiple projects. When you update the environment variable, it will update the environment variable for all environment that reference it.

If you want to update the value of an environment variable for specific environment, you should detach the environment variable and update it.

When you detach an environment variable, Vercel will create a copy of the environment variable and exclusively assign the duplicated copy to your selected environment. The selected environment will be removed from the original environment variable, and changes you make to the copied environment variable will only affect the selected environment.

For example, if you detach the MY_API_KEY environment variable from the my-staging environment, the my-staging environment will have its own copy of the MY_API_KEY environment variable. Changes to the MY_API_KEY environment variable in the my-staging environment will not affect the original environment variable.

1. From the Vercel dashboard, select your project, navigate to the Settings tab and go to Environments.
2. Select your environment from the list
3. In the Environment Variables section, click the Detach button next to the environment variable you want to unsync.
4. Click the Detach button to confirm.
5. The environment variable will be duplicated and assigned to the selected environment. You can now edit the environment variable for the selected environment.

Once you've created your custom environment, you can redeploy to it using the Vercel dashboard or the Vercel CLI.

To redeploy to your custom environment using the Vercel dashboard:

1. From the Vercel dashboard, select your project, navigate to the Deployments tab.
2. Find your deployment in the list of deployments.
3. From the context menu, click the Redeploy button next to the deployment you want to redeploy.
4. From the drop-down list, select the environment you want to redeploy to and click the Redeploy button.

This will create a new deployment using the same source code as your current one, but with the latest configuration from your Project Settings.

Alternatively, to redeploy from the Vercel CLI, use the following command where ENVIRONMENT is the name of your custom environment:

vercel redeploy --target=ENVIRONMENT

Custom environments are available at no additional cost on the Pro and Enterprise plans. The number of custom environments you can create is based on your plan:

• Pro: 1 custom environment per project
• Enterprise: 12 custom environments per project