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 usemain
and notmaster
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 |
|
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
main
gitlab-org/gitlab#320794 (closed)
Step 1 - Execute pipelines on Being main
a protected branch, pipelines need to be executed on it, just like we currently do for master
, *-auto-deploy-*
, and *-stable-*
branches.
main
branch for gitlab-org/gitlab
and for gitlab-org/gitlab-foss
Step 2 - Create 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.
master
to main
Step 3 - Mirror commits from Note: This step requires additional investigation
Automatically mirror commits from master
to main
, options so far:
- Adding a script that uses
rules:if
into thegitlab-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
master
to main
Step 4 - Create a redirect from 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
main
Step 5 - Change the GitLab repositories default branch to Note: This step should be coordinated with teamDelivery
Change Canonical, Security and Dev repositories default branch to main
in Settings > Repository > Default branch
- Canonical https://gitlab.com/gitlab-org/gitlab/
- Security https://gitlab.com/gitlab-org/security/gitlab
- Dev https://dev.gitlab.org/gitlab/gitlab-ee
main
Step 6 - Ensure developers and community contributors use - Communicate this change broadly to the engineering and infrastructure department.
- This should likely be owned by a marketing team https://gitlab.com/gitlab-com/marketing/corporate_marketing/corporate-marketing/-/issues/3211
- 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 tomaster
- Ensure merge requests are now targeting
main
instead ofmaster
- For developers, we can ask them to update their merge request to target
main
- Open question: What to do with community contributions?
- For developers, we can ask them to update their merge request to target
Step 7 - Adjust remaining dependencies
-
broken-master
Slack channel - This one should track failures onmain
now.- Slack channel should be renamed too.
- Adjust GitLab documentation to refer to
main
instead ofmaster
- https://gitlab.com/gitlab-org/gitlab/-/issues/321878 - Update release-tools to interact with
gitlab-org/gitlab
default branch &416 (closed)
master
branch
Step 8 - Remove 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
main
Step 9 - Consider what other projects' default branch can be changed to - GitLab Omnibus - https://gitlab.com/gitlab-org/omnibus-gitlab
- Gitaly gitlab-org/gitaly#3107
- Workhorse https://gitlab.com/gitlab-org/gitlab-workhorse
- www-gitlab-com https://gitlab.com/gitlab-com/www-gitlab-com
- Runner https://gitlab.com/gitlab-org/gitlab-runner
- GDK gitlab-org/gitlab-development-kit#1116 (closed)
- GitLab Pages - https://gitlab.com/gitlab-org/gitlab-pages
Projects already using main
as default branch:
- Shell gitlab-org/gitlab-shell#489 (closed)
- 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 forgitlab-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 tomain
") - 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)
-
teamDelivery highlighted the steps that will require involvement from the team ( "Step 2: Create
-
March 17th, 2021
- Call with
@sean_carroll
and@mayra-cabrera
to discuss current status and next steps, see #1357 (comment 531831543)
- Call with