Intra-project branch mirroring
Release notes
TODO
Problem to solve
Git is transitioning from having a default branch of master
to having a default branch of main
. At GitLab, we're planning to update the default branch for all our projects, but we have lots of downstream tooling that depends on the master
branch.
Starting with gitlab-shell as a test case (gitlab-shell#489 (closed)), we've created main
already, and made it into the default branch. We are going to be manually mirroring changes from main
into master
until we can safely delete master
.
Wouldn't it be better if GitLab could automatically update master
to be equal to main
every time main
is updated?
We could also have created main
as a new branch and delayed changing the default branch until all downstreams were updated - this ability would be just as useful then, too.
There may be some equivalent problems to do with keeping multiple branches in sync with git-flow
Intended users
- Delaney (Development Team Lead)
- Sasha (Software Developer)
- Devon (DevOps Engineer)
- Sidney (Systems Administrator)
- Rachel (Release Manager)
- Priyanka (Platform Engineer)
User experience goal
The user should be able to create branches that are identical to another branch in everything but name.
Proposal
Add new section to Repository Settings called Mirroring Branches
Allow user to pick a branch that currently exists (source), and enter the name of a branch that does not exist (new branch will be created as part of this operation).
The latter is created immediately as a read-only mirror of the former. Nothing - including admin users or deploy keys - can change what that branch points to.
Whenever a push is made to the former, the latter is updated to reflect the new state of the former.
CI and other processes run for the mirror branch as normal.
Essentially, this feature is intra-project push mirroring, but will instead call Gitaly to update the branch ref whenever a push occurs on the "source" branch.
Design proposal
- Add section
Mirroring Branches
to the Repository Settings page - Add area
Mirror a branch
with the following:- Dropdown
Source branch:
to allow a user to select from a list of existing branches - Input field
Mirror branch name:
- Blank by default
- Requires at least 1 character
- On input, if the user enters a name that matches an existing branch, display error screenshot
-
Add mirror
button- Disabled by default
- Becomes enabled if a valid branch and mirror name have been selected/entered screenshot
- Dropdown
- Add table displaying previously created mirrors
- Row should include
Source branch
andMirror branch
data - Row should include a
Remove mirroring
button- Clicking button removes the mirror relationship
- Row should include
Permissions and Security
Mirrored branches should only be available to project administrators or above
Documentation
Availability & Testing
What does success look like, and how can we measure that?
What is the type of buyer?
This should be Core
Is this a cross-stage feature?
No, this is entirely within groupsource code