Default branch rename redirect
Release notes
As part of the larger effort to rename Git's default initial branch in a GitLab project from master
to main
, we are adding a automatic redirect to streamline the experience for you. Previously, when projects rename the default branch. e.g. from master
to main
, all current URLs including the default branch in the URL path, will result in 404s - not found
. This is a frustrating experience when you are trying to navigate between branches in a project. Now if you navigate to a file path whose ref branch got renamed, and you will be redirected to the new source file path automatically.
Problem to solve
When projects rename the default branch, e.g. from master
to main
, all current URLs including the default branch in the URL path, will result in 404s - not found.
Documentation deep links might be more visibly affected, for example https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/master/doc/howto/gitpod.md
which I had linked in a slide deck.
https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/howto/gitpod.md
is the corrected path.
User experience goal
Navigate to a file path whose ref branch got renamed, and get redirected to the new source file path automatically.
Optional: Add a note to update bookmarks, similar to the project move/rename redirect.
Proposal
When addressing the immediate prior name of the default branch in a URL, automatically redirect to the current default branch. In the above example:
https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/master/doc/howto/gitpod.md
automatically redirects to
https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/howto/gitpod.md
For MVC we will address it only for the prior name of the default branch (for example, if it has been renamed more than once, we won't redirect any versions prior to the immediate predecessor)
Original proposal
Use the project rename and redirect functionality, and track a change of the default branch name.
Alternatively, add a config setting to enable this re-direct for projects.
Rough UX:
[ ] Redirect default branch names
Old target: [ master ] New target: [ main ]
Further details
This may affect performance depending on how the redirect is matched.
https://gitlab.com/userorgroup/project/-/blob/[master]/path/to/file.md
https://gitlab.com/userorgroup/project/-/blob/[main]/path/to/file.md
I'd suggest to use redirect permanent
, making browsers cache the redirect on the client side. This removes stress on the server.
For short term solutions for GitLab.com infra, we could use Nginx redirects in production.
Resources:
- GitLab pages redirect: gitlab-pages#24 (closed)
- Project rename redirects: gitlab-foss#17361 (closed)
Inspired by https://twitter.com/twitchih/status/1385597550237978626?s=27
Documentation
If this gets a project setting, corresponding docs with screenshots need to be added. A permission model update is required then too.
Availability & Testing
As a project setting, add rspec tests including permission checks.
What does success look like, and how can we measure that?
No reports on URL 404s after renaming a branch.