In %15.11 we are releasing this feature here together with https://gitlab.com/gitlab-org/gitlab/-/issues/384166+. ### Release notes Managing your fork just got easier. When your fork is behind, select **Update fork** to catch it up with upstream changes. When your fork is ahead, select **Create merge request** to contribute your change back to the upstream project. Both operations previously required you to use the command line. See how many commits your fork is ahead (or behind) on your project's main page and at **Repository > Files**. If merge conflicts exist, the UI gives guidance on how to resolve them using Git from the command line.  ### Problem to solve In order to keep my fork up to date, I have to merge contents from the upstream. Without this feature here, this can only be done on the command line and is very manual and time-consuming. It is difficult for users that are inexperienced with git. ### Proposal This issue here creates a "sync" button according to the logic below on **each branch of the fork** allowing users to **update** their branch **with new commits from the upstream project's main branch**. There should be a rate limit of 6 sync requests per hour per branch, to prevent resource-intensive misuse. #### UI change :art: [Figma file](https://www.figma.com/file/osDavgsfqLSRX6ik60NqLP/Forking?node-id=61%3A24215&t=JxmLISRDUXTs466d-1) To help users understand which branch they are syncing from we should display the branch of the upstream repository in the fork widget. For example, display `Gitlab Org / Gitlab Shell : main` instead of `Gitlab Org / Gitlab Shell` #### Scenario 1: Sync when 10 commits behind upstream Performs fast-forward merge and upon completion, an alert is shown to indicate sync success. * [Design: Behind](https://gitlab.com/gitlab-org/gitlab/-/issues/330243/designs/sync_behind.png) * [Prototype](https://www.figma.com/proto/osDavgsfqLSRX6ik60NqLP/Forking?page-id=28%3A7916&node-id=49%3A11046&viewport=-444%2C263%2C0.2&scaling=min-zoom&starting-point-node-id=49%3A11046) #### Scenario 2: Sync when 2 commits ahead, 10 commits behind upstream Performs fast-forward merge and upon completion, an alert is shown to indicate sync success. * [Design: Ahead behind](https://gitlab.com/gitlab-org/gitlab/-/issues/330243/designs/sync_ahead_behind.png) * [Prototype](https://www.figma.com/proto/osDavgsfqLSRX6ik60NqLP/Forking?page-id=28%3A7916&node-id=49%3A13614&viewport=-444%2C263%2C0.2&scaling=min-zoom&starting-point-node-id=49%3A13614&show-proto-sidebar=1) #### Scenario 3: Sync when 2 commits ahead, 10 commits behind upstream (conflicts) When there is a merge conflict with the upstream, we would require the user to manually resolve the conflict. We provide the steps on how to do this in a modal. * [Design: Sync conflict](https://gitlab.com/gitlab-org/gitlab/-/issues/330243/designs/sync_conflict.png) * [Prototype](https://www.figma.com/proto/osDavgsfqLSRX6ik60NqLP/Forking?page-id=28%3A7916&node-id=49%3A14016&viewport=-444%2C263%2C0.2&scaling=min-zoom&starting-point-node-id=49%3A14016&show-proto-sidebar=1) #### Modal for resolving conflicts Discussion reference: https://gitlab.com/gitlab-org/gitlab/-/issues/330243/designs/3_-_overview_conflict.png#note_1285330696 === MODAL BODY START === **Resolve merge conflicts manually** The upstream changes could not be synchronised to this project due to file conflicts. You must resolve the conflicts manually: **Step 1.** Fetch the latest changes from the upstream repository's default branch: ``` git fetch <source-url> <source-default-branch> ``` **Step 2.** Check out to a new branch, and merge the changes from the upstream project's default branch. You likely need to resolve conflicts during this step. ``` git checkout <current-branch-name> git merge FETCH_HEAD ``` **Step 3.** Push the updates to remote: ``` git commit git push ``` === MODAL BODY END === #### Scenario 4: Rate limited When the user hits the limit of syncs per branch per hour then we replace the Sync button with the text "Limit of 6 sync requests/hr reached". * [Design: Rate limited - Replace Sync button with text](https://gitlab.com/gitlab-org/gitlab/-/issues/330243/designs/4_-_rate_limited.png) ### Alternative approaches users can take Described in https://forum.gitlab.com/t/refreshing-a-fork/32469/2?u=dnsmichi #### Local sync with a cloned fork on the CLI ``` git remote add upstream https://gitlab.com/upstream_user_group/project.git || true && git fetch upstream && git checkout main && git pull upstream main && git push origin main ``` #### Repository mirroring (Pull) Use the upstream repository as source. That's a Premium+ feature. - https://docs.gitlab.com/ee/user/project/repository/repository_mirroring.html#pulling-from-a-remote-repository - https://docs.gitlab.com/ee/user/project/repository/forking_workflow.html#repository-mirroring <!-- triage-serverless v3 PLEASE DO NOT REMOVE THIS SECTION --> *This page may contain information related to upcoming products, features and functionality. It is important to note that the information presented is for informational purposes only, so please do not rely on the information for purchasing or planning purposes. Just like with all projects, the items mentioned on the page are subject to change or delay, and the development, release, and timing of any products, features, or functionality remain at the sole discretion of GitLab Inc.* <!-- triage-serverless v3 PLEASE DO NOT REMOVE THIS SECTION --> ### Availability and Testing New E2E test to update a branch of a fork with new commits from upstream using the new "Sync" button required (created https://gitlab.com/gitlab-org/quality/quality-engineering/team-tasks/-/issues/1610).