Gitlab Rename Branch

Renaming a branch in GitLab is straightforward, but the exact steps depend on what kind of branch you’re dealing with. Here’s how to handle it.

Why rename a branch?

The most common reason is moving away from master as the default branch name. Maybe your team decided to switch to main, or maybe you just want a naming convention that fits your workflow better. Whatever the case, GitLab doesn’t have a single “rename” button for branches. The process is: create the new branch from the old one, update GitLab’s default branch setting if needed, then delete the old branch.

Two things to check first

Before you start, figure out the status of the branch you want to rename:

1. Is it the default branch for your project?
2. Is it a protected branch?

If the answer to either is yes, you’ll need to use the GitLab web interface for part of the process. You can’t delete a default or protected branch from the command line.

Scenario 1: Regular branch (not default, not protected)

This is the easy case. You can do everything from the terminal.

First, switch to the branch you want to rename:

git checkout <old_branch_name>

Rename it locally:

git branch -m <new_branch_name>

If you’ve already pushed the old branch to the remote, push the new one and set up tracking:

git push origin -u <new_branch_name>

Then delete the old remote branch:

git push origin --delete <old_branch_name>

That’s it. The new branch has all the same commit history as the old one.

Scenario 2: Renaming the default branch

This is the scenario most people care about. The process starts the same way on the command line, but you’ll hit a wall when trying to delete the old branch.

First, rename locally and push:

git checkout <old_branch_name>
git branch -m <new_branch_name>
git push -u origin <new_branch_name>

Next, update the remote HEAD reference so it points to your new branch:

git symbolic-ref refs/remotes/origin/HEAD refs/remotes/origin/<new_branch_name>

Now try deleting the old branch from the remote:

git push origin --delete <old_branch_name>

If the old branch is the default, GitLab rejects the delete:

remote: GitLab: The default branch of a project cannot be deleted.
To gitlab.www.bitslovers.com:/gitlab-rename-branch/devops-api.git
 ! [remote rejected] temp2 (pre-receive hook declined)
error: failed to push some refs to '[email protected]:gitlab-rename-branch/devops-api.git'

You need to change the default branch in GitLab first.

Changing the default branch in GitLab

Go to your project, then navigate to Settings > Repository. Scroll down to the “Default branch” section.

Gitlab Rename Branch - Repository Configuration

Select your new branch from the dropdown and save.

Gitlab Rename Branch - Change the Default Branch

After saving, you can delete the old branch:

git push origin --delete <old_branch_name>

What if the old branch is also protected?

If the branch is protected, you’ll get a different error:

remote: GitLab: You can only delete protected branches using the web interface.
To gitlab.www.bitslovers.com:/gitlab-rename-branch/devops-api.git
 ! [remote rejected] temp3 (pre-receive hook declined)
error: failed to push some refs to '[email protected]:/gitlab-rename-branch/devops-api.git'

In this case, go to Code > Branches in GitLab, find the old branch, click More actions, then choose Delete protected branch. You’ll need to type the branch name to confirm.

Gitlab Rename Branch - Delete Protected Branch

Note: only users with the Maintainer or Owner role can delete protected branches.

After renaming the default branch

A few things to keep in mind once you’ve made the switch:

• Tell your team. Everyone needs to update their local clones. They should pull the new default branch and update any open merge requests that target the old branch.
• Update references in your code. Check your CI/CD config, Dockerfiles, scripts, and documentation for any hardcoded references to the old branch name.
• GitLab handles URL redirects. If someone has a bookmarked URL pointing to a file on the old branch, GitLab redirects them to the new default branch instead of showing a 404.

Related articles

How to use the Gitlab CI Variables

Effective Cache Management with Maven Projects on Gitlab.

Pipeline to build Docker in Docker on Gitlab.

How to Autoscaling the Gitlab Runner.

How to execute Cloud Formation on Gitlab.

How to use Gitlab CI: Deploy to elastic beanstalk