Skip to content

Change default branch name for GitLab project (gitlab-org/gitlab)

Problem statement

As part of https://gitlab.com/groups/gitlab-org/-/epics/3600 GitLab has worked towards providing users flexibility in choosing a default branch name for their repositories both at the instance-level as well as the group-level.

Internal GitLab projects are still using master as its default branch name, something we'd like to change to main in order to align with Git's new default branch name as well as the community at large.

Exit criteria

  • gitlab-org/gitlab should use main and not master as the default branch.

DRI

Product Engineering
@sarahwaldner @sean_carroll

Requirements

Following steps need to be addressed before continuing changing the default branch. These steps can be executed in parallel.

Status Step
✅ Update release tools to interact with project's default branch &383 (closed)
⏳ Adjust all secondary projects that depend on gitlab-org/gitlab hardcoded master 6 out of 11 are completed, see list below

Satellite projects that might depend on a hard-coded gitlab-org/gitlab master branch, the list was taken from the engineering projects page

Ready for change Project Issue Action required? Using main
✅ GitLab QA gitlab-org/gitlab-qa#609 (closed) Yes ✅
✅ Gitaly gitlab-org/gitaly#3399 (closed) No ✅
✅ Runner gitlab-org/gitlab-runner#27401 (closed) No ❌
✅  Shell gitlab-org/gitlab-shell#493 (closed) No ✅
✅ GitLab build images gitlab-org/gitlab-build-images#45 (closed) No ❌
✅ GitLab Pages gitlab-org/gitlab-pages#527 (closed) No ❌
⏹ GDK gitlab-org/gitlab-development-kit#1141 (closed) Yes ✅
⏹  Merge train https://gitlab.com/gitlab-org/merge-train/-/issues/14 Yes ❌
⏹ Omnibus gitlab-org/omnibus-gitlab#5912 Yes ❌
⏹ GitLab Cloud Native Helm Chart / CNG gitlab-org/charts/gitlab#2499  Yes ❌
⏹ GitLab Docs https://gitlab.com/gitlab-org/gitlab-docs/-/issues/910 Yes ✅ (https://gitlab.com/gitlab-org/gitlab-docs/-/issues/1025)
List of other secondary projects with no action required

After a quick investigation, it appears none of the following projects depend on gitlab-org/gitlab master branch, therefore no issue was created for any of them:

  • GitLab Elastic Search Indexer
  • GitLab Orchestrator
  • Cookbook-Omnibus Gitlab
  • Terraform Files
  • License Dot
  • CustomersDot (Subscription Portal)
  • GitLab License
  • GitLab Version
  • GitLab Helm Repository
  • Container Registry

Plan to change GitLab default branch

Step 1 - Execute pipelines on main gitlab-org/gitlab#320794 (closed)

Being main a protected branch, pipelines need to be executed on it, just like we currently do for master, *-auto-deploy-*, and *-stable-* branches.

Step 2 - Create main branch for gitlab-org/gitlab and for gitlab-org/gitlab-foss

Note: This step should be coordinated with teamDelivery

main branch should be protected and only the Delivery team should be allowed to push. Protected branches are automatically propagated to Security and Dev, as such we don't require to create main on those repos.

Step 3 - Mirror commits from master to main

Note: This step requires additional investigation

Automatically mirror commits from master to main, options so far:

  • Adding a script that uses rules:if into the gitlab-ci.yml
  • Extending our scheduled merge train so every time a divergence is detected between master and main a merge train is executed (this is the same strategy we use on the early-merge phase of a security release to bring Security repo up to date with Canonical changes)
  • Dogfooding and building our own feature into GitLab to mirror branches within the same project - gitlab-org/gitlab#285459

Step 4 - Create a redirect from master to main

There are many documentation links that use master, eventually those will need to be fixed (we have an item on step 7), in the meantime to avoid broken links, we should create a redirect from master to main, so when someone visits https://gitlab.com/gitlab-org/gitlab/-/commits/master it's automatically redirected to https://gitlab.com/gitlab-org/gitlab/-/commits/main

Step 5 - Change the GitLab repositories default branch to main

Note: This step should be coordinated with teamDelivery

Change Canonical, Security and Dev repositories default branch to main in Settings > Repository > Default branch

Step 6 - Ensure developers and community contributors use main

  • Communicate this change broadly to the engineering and infrastructure department.
  • From this point, only the Delivery team should be allowed to push to master
  • Mirror on step 3 should be flipped, so every time someone pushes a commit into main this one is automatically propagated to master
  • Ensure merge requests are now targeting main instead of master
    • For developers, we can ask them to update their merge request to target main
    • Open question: What to do with community contributions?

Step 7 - Adjust remaining dependencies

Step 8 - Remove master branch

Changing GitLab default branch will require a communication plan (see https://gitlab.com/gitlab-com/marketing/corporate_marketing/corporate-marketing/-/issues/3211), as an aside we'll likely need to give a few months (so the community can adjust whatever tools they have) before deleting master from gitlab-org/gitlab

Step 9 - Consider what other projects' default branch can be changed to main

  1. GitLab Omnibus - https://gitlab.com/gitlab-org/omnibus-gitlab
  2. Gitaly gitlab-org/gitaly#3107 (closed)
  3. Workhorse https://gitlab.com/gitlab-org/gitlab-workhorse
  4. www-gitlab-com https://gitlab.com/gitlab-com/www-gitlab-com
  5. Runner https://gitlab.com/gitlab-org/gitlab-runner
  6. GDK gitlab-org/gitlab-development-kit#1116 (closed)
  7. GitLab Pages - https://gitlab.com/gitlab-org/gitlab-pages

Projects already using main as default branch:

  1. Shell gitlab-org/gitlab-shell#489 (closed)
  2. GitLab Elasticsearch Indexer - gitlab-org/gitlab-elasticsearch-indexer#71 (closed)

Development log

  • Jan 6st, 2021: Requirements were added (update release tools and secondary projects), those need to be completed before changing the default branch name for GitLab
  • Jan 12th, 2021: Release tooling adjustments were completed. We're ready to start the testing #1441 (closed)
  • Jan 16th, 2021: Given the tight release scheduled for the upcoming weeks, it was decided to postpone the testing until February 1st. #1441 (comment 487988335)
  • February 15th, 2021 Daily auto-deployments, Release Candidates, and Security Release process were successfully tested using main branch for gitlab-org/gitlab
  • February 19th, 2021 First requirement: Update release tooling to interact with main branch completed.
  • March 3rd, 2021
    • teamDelivery highlighted the steps that will require involvement from the team ( "Step 2: Create main branch" and "Step 5: Change the GitLab repositories default branch to main")
    • After finishing the first requirement, teamDelivery is not actively working on this issue, DRI's from this point are @sean_carroll, and @danielgruesso, see #1357 (comment 521377780)
  • March 17th, 2021
Edited by Sean Carroll