Fetch new upstream contents when fork is behind

In %15.11 we are releasing this feature here together with Allow users to merge from a forked repository (#384166 - closed).

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

🎨 Figma file

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
• Prototype

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
• Prototype

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
• Prototype

Modal for resolving conflicts

Discussion reference: #330243[3_-_overview_conflict.png] (comment 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

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

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.

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 gitlab-org/quality/quality-engineering/team-tasks#1610).