### Release notes TODO <!-- What is the problem and solution you're proposing? This content sets the overall vision for the feature and serves as the release notes that will populate in various places, including the [release post blog](https://about.gitlab.com/releases/categories/releases/) and [Gitlab project releases](https://gitlab.com/gitlab-org/gitlab/-/releases). " --> ### 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 (https://gitlab.com/gitlab-org/gitlab-shell/-/issues/489), 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)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#delaney-development-team-lead) * [Sasha (Software Developer)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#sasha-software-developer) * [Devon (DevOps Engineer)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#devon-devops-engineer) * [Sidney (Systems Administrator)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#sidney-systems-administrator) * [Rachel (Release Manager)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#rachel-release-manager) * [Priyanka (Platform Engineer)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#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](https://gitlab.com/gitlab-org/gitlab/-/issues/285459/designs/State_-_error.png) * `Add mirror` button * Disabled by default * Becomes enabled if a valid branch and mirror name have been selected/entered [screenshot](https://gitlab.com/gitlab-org/gitlab/-/issues/285459/designs/State_-_filled.png) * 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 <!-- See the Feature Change Documentation Workflow https://docs.gitlab.com/ee/development/documentation/workflow.html#for-a-product-change * Add all known Documentation Requirements in this section. See https://docs.gitlab.com/ee/development/documentation/feature-change-workflow.html#documentation-requirements * If this feature requires changing permissions, update the permissions document. See https://docs.gitlab.com/ee/user/permissions.html --> ### Availability & Testing <!-- This section needs to be retained and filled in during the workflow planning breakdown phase of this feature proposal, if not earlier. What risks does this change pose to our availability? How might it affect the quality of the product? What additional test coverage or changes to tests will be needed? Will it require cross-browser testing? Please list the test areas (unit, integration and end-to-end) that needs to be added or updated to ensure that this feature will work as intended. Please use the list below as guidance. * Unit test changes * Integration test changes * End-to-end test change See the test engineering planning process and reach out to your counterpart Software Engineer in Test for assistance: https://about.gitlab.com/handbook/engineering/quality/test-engineering/#test-planning --> ### What does success look like, and how can we measure that? <!-- Define both the success metrics and acceptance criteria. Note that success metrics indicate the desired business outcomes, while acceptance criteria indicate when the solution is working correctly. If there is no way to measure success, link to an issue that will implement a way to measure this. Create tracking issue using the the Snowplow event tracking template. See https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/issue_templates/Snowplow%20event%20tracking.md --> ### What is the type of buyer? This should be Core ### Is this a cross-stage feature? No, this is entirely within ~"group::source code" ### Links / references