Master to Main with GitLab
To be honest, this article from Wired gives a good perspective on why you should or should not do this. Read it first.
Read it? Good. Now if you still want to do this, here is a template that we followed for each of our GitLab repos. The same procedure should work for GitLab and GitLab Enterprise.
Before you start: Make sure you have the permissions to do this.
Update CI and docs (.gitlab-ci.yml && README.md)
I recommend just running a search-replace through your project and looking for
master. Most of those occurrences will probably need to change to
main. Noteworthy examples are
.gitlab-ci.yml and the Contribute section of your
README.md file. I prefer to commit this change directly to
master since it will automatically be part of the next step.
Update default branch
This moves the
master branch to become
main. It automatically deals with the history and reflog for you.
git branch -m master main
git push -u origin main
Set default branch in GitLab
In the repository settings (Settings > Repository), update the Default Branch.
Update protected branches
In the repository settings (Settings > Repository), update the Protected branches. You probably want to have the same settings for
main as the old
master had. Then set that No one is allowed to push or merge to
master. That way you and your colleagues will get errors when old habits kick in and you try to interact with the wrong branch.
Now you are ready to delete the
master branch from GitLab. Don’t worry, the settings we did above to protect people from trying to interact with
master will still be in place. You reach this view via Repository > Branches in the left hand menu.
Merge requests will need updating. They are, however, safe since
master is protected and deleted.
People will need to update their local clone. Luckily, with the protection we put in place, no one will be able to accidentally push any code to the old branch.
git checkout master
git branch -m master main
git branch --unset-upstream
git branch -u origin/main
git symbolic-ref refs/remotes/origin/HEAD refs/remotes/origin/main
Alternatively, one can just delete the local project and do a fresh clone.
Default branch name for new repos
When you create a new repo in GitLab, the default branch will be
master. You can change this default by going to (Admin Area > Settings > Repository > Default initial branch name), and setting your custom name there. This currently only works on GitLab Core and up, but not on GitLab.com.
Bonus: Do you have any separate tools that look at master branches of repositories?
Often branch names will live in CI configurations. Either hardcoded through a UI, or committed to a config file. You will know your tools best so make sure to update any tools outside the repositories as well.
In our case, we have a separate tool that goes through all of our repositories and gets the licencing information from all the imported modules and compiles them into a file that we can publish. This tool just assumes that there is a
master branch, so we needed to update this.
This is not a big nor difficult change. If you have many repos then this is a bit of a rinse and repeat process, and can probably be scripted using GitLab’s API.
All cred goes to Scott Hanselman who did all the heavy lifting with this information. I just added some information specific to GitLab. Make sure to check out his article on renaming your default git branch from master to main.