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

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

image

  • 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
  • Add table displaying previously created mirrors
    • Row should include Source branch and Mirror branch data
    • Row should include a Remove mirroring button
      • Clicking button removes the mirror relationship

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

Links / references

Edited by Mike Nichols