Edit page

Platform.sh considers master to be the default branch for all projects, making Master the default production environment. Soon you will be able to select your default branch during the project creation steps, but until that time this guide will show you how to manually make the switch yourself.

You can complete some of these steps through the management console, but since all can be completed with the CLI those commands alone are listed. Be sure to install the CLI if you have not already done so. It’s assumed you are changing the default branch of your project on Platform.sh from master to main. If using another name for the default branch, update the commands accordingly.

Projects without external integrations 

The steps below assume:

• You already have a project on Platform.sh containing your code.
• No external source integrations have been set up for the project. That is, the Platform.sh project contains your primary remote repository for the site.

1. Create the Main environment 

To start, create a new environment off master called main:

$ platform environment:branch main master --title=Main -p <Project ID> --force

main is currently the child of master, so use the below command to remove its parent and make it a top-level branch:

$ platform environment:info -p <Project ID> -e main parent -

At this point, all of your environments, active and inactive, are still children of master. In the next step, you will deactivate master, which will not work if it still has child environments associated with it. Before going any further, take the time to update each environment’s parent to main:

$ platform environment:info -p <Project ID> -e <BRANCH> parent main

2. Reconfigure the default branch 

First, you will need to deactivate the master environment with the following CLI command:

$ platform environment:delete master --no-delete-branch -p <Project ID>

Once master has been deactivated, you can then set the project’s default_branch property to main:

$ platform project:info default_branch main -p <Project ID>

Finally, delete the master enviroment completely.

$ platform environment:delete master --delete-branch -p <Project ID>

Setting up an external integration on a new project 

The steps below assume:

• You have an external repository on GitHub, GitLab, or BitBucket you are trying to integrate with Platform.sh.
• That repository’s default branch is not master.

1. Create a new project 

First, create an empty project with the Platform.sh CLI command platform create:

$ platform create --title='Main Project' --region=us-3.platform.sh --plan=development --environments=3 --storage=5 --no-set-remote

This will create a new project with master as the default branch by default. Modify the flags to fit your use case, or skip them and the CLI will ask you to set them individually during creation. Copy the Project ID provided when the command completes, and substitute the value in the steps below. You can also visit the provided management console URL for the project (i.e. https://console.platform.sh/<USER>/<Project ID>) to verify the steps as you go along.

The project you just created is empty, that is, there is no code initialized on it’s Master environment. You will need to have something on that environment to begin with in order to create the main branch, so you can initialize it with a template for now:

$ platform environment:init -p <Project ID> -e master https://github.com/platformsh-templates/hugo.git

Then, create the “Main” environment:

$ platform environment:branch main master --title=Main -p <Project ID> --force

main is currently the child of master, so use the below command to remove its parent and make it a top-level branch:

$ platform environment:info -p <Project ID> -e main parent -

2. Deactivate the Master environment 

You will need to deactivate the master environment with the following CLI command:

$ platform environment:delete master --no-delete-branch -p <Project ID>

3. Make “Main” the default branch 

First, update the project’s default_branch property to main:

$ platform project:info default_branch main -p <Project ID>

At this point, while the repository considers main to be the default branch for the project, master is still considered to be the parent branch of main. You can change this by updating main to have a parent of null with the command:

$ platform environment:info -p <Project ID> -e main parent -

You have already deactivated Master, so all that’s left now is to delete the master branch from the remote repository with one final authenticated request.

$ platform environment:delete master --delete-branch -p <Project ID>

You will then be left with “Main” as your top-level parent environment for the project.

4. Setup the integration 

Place the command to integrate Platform.sh with your external GitHub, GitLab, or BitBucket repository that has already been set up with main as the default branch. Select the settings you would like for the integration, but in most cases the default settings are best. The last stage will provide a warning:

Warning: adding a 'github' integration will automatically synchronize code from the external Git repository.
This means it can overwrite all the code in your project.

Are you sure you want to continue? [y/N] y

which will override the code on the “Main” environment - the template you started with - with the contents of the main branch of your external repository. You can now consult the rest of the migration steps to finish migrating your site to Platform.sh.

Updating externally integrated projects 

The steps below assume:

• You have already integrated an external repository GitHub, GitLab, or BitBucket.
• You are trying to safely change the name of your default branch from master to main on both your external repository and on a Platform.sh project.

1. Create the main branch 

Within your local copy of the external repository, create the main branch and push:

$ git checkout master && git pull origin master
$ git checkout -b main
$ git push origin main

Then activate it on Platform.sh

$ platform environment:activate main -p <Project ID>

2. Clean up repository 

Most external services do not yet automatically remap to a new default branch, and in order to preserve your data on Platform.sh, it’s best to take a moment to prepare all of your work in progress around master to instead compare to main.

First, close any open pull requests and resubmit them against main. Be sure to rebase your local brances with git rebase --onto main master if you still plan on continuing to work on them after the default branch switch. Once you resubmit them, they will appear under the “main” environment on Platform.sh.

3. Change the default branch on the external Git service 

Platform.sh supports external Git integrations to a number of services, so follow the linked instructions below for changing the default branch to main for your provider:

• GitHub
• GitLab
• BitBucket

4. Deactivate the Master environment 

You will need to deactivate the master environment. Since it is currently the default branch, it is protected, and so the normal platform environment:delete CLI command will not work at this stage. This restriction will soon be removed, but for now you can get around this by placing an authenticated cURL request on the project’s API with the following CLI command to deactivate it:

$ platform project:curl -X POST -p <Project ID> environments/master/deactivate 

5. Make “Main” the default branch 

Update the project’s default_branch property with another authenticated request:

$ platform project:info default_branch main -p <Project ID>

At this point, while the repository considers main to be the default branch for the project, master is still considered to be the parent branch of main. You can change this by updating main to have a parent of null with the command:

$ platform environment:info -p <Project ID> -e main parent -

You can now delete the master branch from your external repository.