How To Change Default Branch in Gitlab?

In GitLab, the default branch is the main working branch for your project, typically set as "main" or "master". This branch serves as the primary point for collaboration, code reviews, and deployments. However, there are times when you may need to change the default branch to reflect naming conventions, feature developments, or team preferences.

Changing the default branch in GitLab can simplify your workflow and improve project organization. In this article, we will walk you through the process of changing the default branch in GitLab.

There are two primary ways to change the default branch in GitLab

1. Using GitLab Web Interface

Step 1: Navigate to Your Repository

• Log in to your GitLab account.
• Go to the project for which you want to change the default branch.

Step 2: Access the Project Settings

• On the left sidebar, click on Settings.
• From the dropdown, select Repository.

Step 3: Locate the Default Branch Setting

Scroll down to the Default branch section.

Step 4: Select the New Default Branch

• Use the dropdown menu under Default branch to select the desired branch.
• Click on the Save changes button to apply the new default branch.

Step 5: Verify the Change

• Check the top of the repository to confirm that the default branch has been updated.
• Ensure that the new default branch reflects across merge requests, CI/CD settings, and other relevant areas.

2. Using Git Commands

If you prefer command-line interaction, you can change the default branch by pushing the new branch and updating settings:

Step 1: Create and Push the New Branch:

If the branch does not exist yet, create it and push it to the remote:

git checkout -b new-default-branch
git push origin new-default-branch

Step 2: Set the New Branch as Default Using GitLab API:

You can use GitLab's API to set the default branch. First, ensure you have a GitLab API token with the necessary permissions.

Use the following curl command to update the default branch:

curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
--data "default_branch=new-default-branch" \
"https://gitlab.com/api/v4/projects/<project_id>"

Step 3: Verify the Change:

Check your GitLab repository settings or use the GitLab API to verify that the default branch has been updated.

Updating Local Clones After Changing the Default Branch

Once the default branch has been changed, it’s important for all team members to update their local clones:

Step 1: Fetch the Latest Changes:

git fetch origin

Step 2: Switch to the New Default Branch:

git checkout new-default-branch

Step 3: Set the Local Default to Match the Remote

If necessary, update your local configuration to set the new branch as the default:

git symbolic-ref refs/remotes/origin/HEAD refs/remotes/origin/new-default-branch

Step 4: Clean Up Old Branch References

If the old default branch is no longer needed, you can delete it locally and remotely:

git branch -d old-default-branch
git push origin --delete old-default-branch