Renaming the default branch
Contents:
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
Note:
The CLI assumes that you are running this command within a local copy of your repository, so the --force
flag is included above to bypass that.
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
Note:
The CLI assumes that you are running this command within a local copy of your repository, so the --force
flag is included above to bypass that.
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>
Note:
Deactivating any environment is a destructive operation, and can result in data loss. Since you are deactivating what was once the production branch for your site, it’s recommended that you perform the switch to a new default branch during non-peak hours for your site. As always, be sure to take a backup of master
beforehand; you can always restore this backup to main
afterwards.
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
tomain
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:
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
Note:
Deactivating any environment is a destructive operation, and can result in data loss. Since you are deactivating what was once the production branch for your site, it’s recommended that you perform the switch to a new default branch during non-peak hours for your site. As always, be sure to take a backup of master
beforehand; you can always restore this backup to main
afterwards.
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.