Upsun User Documentation

Rename the default environment

Back to home

On this page

Try Upsun for 15 days
After that, enjoy the same, game-changing Upsun features for less with the First Project Incentive!¹ A monthly $19 perk!
Activate your 15-day trial
¹Terms and conditions apply

You can set the name of your default/production environment when creating a project. To change it after project creation, follow the steps below. For consistency, the steps are all given using the CLI.

The examples below are based off of changing the default environment from old to main. Replace these names with what suits your situation.

If your site is already live, remember that deactivating an environment is a destructive operation that can result in data loss. To minimize potential issues, take the following steps:

  • Switch the default environment during non-peak hours.
  • Keep your data by taking a backup of the old environment
  • Reduce your DNS time-to-live (TTL) to a minimum.

Requirements Anchor to this heading

If you have a domain set for your default environment, remove it before changing the default branch. Otherwise you get an error that default domain must be a valid project domain.

To change the default branch, you need to be an admin for the project

Note on source integrations Anchor to this heading

The following steps depend of whether your project has a source integration.

If it doesn’t, Upsun is your primary remote repository for the project. If it does, GitHub, GitLab, or BitBucket hosts your primary remote repository for the project.

1. Create a main environment Anchor to this heading

In your local copy of your repository, create a new environment from old called main:

upsun environment:branch main old

2. Copy settings Anchor to this heading

If you have variables or other settings specific to your default environment, add those to the main environment.

For example, you may have variables for your production environment set to not be inheritable (such as if you set them with --inheritable=false through the CLI). These variables aren’t added automatically to child environments and so you need to add them to the main environment manually.

If you want the main environment to send emails, turn on outgoing email.

3. Make main a top-level branch Anchor to this heading

To have main be your default, it needs to not be a child of old. Use the following command to remove its parent and make it a top-level branch:

upsun environment:info -e main parent -

4. Make main the parent for other environments Anchor to this heading

You probably have other environments that are children of old. For each environment, update its parent to main:

upsun environment:info -e <ENVIRONMENT_NAME> parent main

5. Deactivate the old branch Anchor to this heading

To change your default branch, you first need to deactivate the existing default branch to remove protections. Deactivate the old environment without deleting it by running the following CLI command:

upsun environment:delete --no-delete-branch old

6. Set main as the default branch Anchor to this heading

Once old has been deactivated, set the project’s default branch to main:

upsun project:info default_branch main

7. Update DNS records Anchor to this heading

Whether or not you’re using a CDN, if your site is live you have probably added a Upsun address somewhere when configuring a custom domain. If you have a CDN, it’s with the CDN provider. If you don’t have a CDN, it’s probably a CNAME record.

In either case, the setting probably has the old environment name as part of it. Update the setting to use the new environment name.

Verify that the new URL is correct by comparing it to the result from this command:

upsun environment:info edge_hostname

8. Optional: Delete the old environment Anchor to this heading

If you no longer want the old environment, such as to stop accidental use, delete it completely:

upsun environment:delete --delete-branch old