• Create a fork
• Update your fork
  • From the UI
  • From the command line
  • With repository mirroring
• Merge changes back upstream
• Unlink a fork
• Check a fork’s storage usage
• Related topics
• Troubleshooting
  • Error: An error occurred while forking the project. Please try again
  • Removing fork relationship fails

Forks

A fork is a personal copy of another Git repository, placed in the namespace of your choice. Your copy contains the upstream repository’s content, including all branches, tags, and CI/CD job configurations. You can create merge requests from your fork to target the upstream repository. Individual commits can also be cherry-picked from your fork into the upstream repository.

If you have write access to the original repository, you don’t need a fork. Instead, use branches to manage your work. If you don’t have write access to a repository you want to contribute to, fork it. Make your changes in your fork, then submit them through a merge request to the upstream repository.

To create a confidential merge request, use a personal fork of a public repository.

Create a fork

To fork an existing project in GitLab:

1. On the project’s homepage, in the upper-right corner, select Fork ().
2. Optional. Edit the Project name.
3. For Project URL, select the namespace your fork should belong to.
4. Add a Project slug. This value becomes part of the URL to your fork. It must be unique in the namespace.
5. Optional. Add a Project description.
6. Select one of the Branches to include options:
   • All branches (default).
   • Only the default branch. Uses the --single-branch and --no-tags Git options.
7. Select the Visibility level for your fork. For more information about visibility levels, read Project and group visibility.
8. Select Fork project.

GitLab creates your fork, redirects you to the new fork’s page, and logs the fork’s creation in the audit log.

If you intend to contribute changes upstream frequently, consider setting a default target for your fork.

Update your fork

A fork can fall out of sync with its upstream repository, and require an update:

• Ahead: Your fork contains new commits not present in the upstream repository. To sync your fork, create a merge request to push your changes to the upstream repository.
• Behind: The upstream repository contains new commits not present in your fork. To sync your fork, pull the new commits into your fork.
• Ahead and behind: Both the upstream repository and your fork contain new commits not present in the other. To fully sync your fork, create a merge request to push your changes up, and pull the upstream repository’s new changes into your fork.

To sync your fork with its upstream repository, update it from the GitLab UI or the command line. GitLab Premium and Ultimate tiers can also automate updates by configuring forks as pull mirrors of the upstream repository.

From the UI

Prerequisites:

• You must create your fork from an unprotected branch in upstream repository.

To update your fork from the GitLab UI:

1. On the left sidebar, select Search or go to.
2. Select View all my projects.
3. Select the fork you want to update.

4. Below the dropdown list for branch name, find the Forked from () information box to determine if your fork is ahead, behind, or both. In this example, the fork is behind the upstream repository:

   

5. If your fork is ahead of the upstream repository, select Create merge request to propose adding your fork’s changes to the upstream repository.
6. If your fork is behind the upstream repository, select Update fork to pull changes from the upstream repository.
7. If your fork is ahead and behind the upstream repository, you can update from the UI only if GitLab detects no merge conflicts:
   • If your fork contains no merge conflicts, you can select Create merge request to propose pushing your changes to the upstream repository, Update fork to pull changes down to your fork, or both. The type of changes in your fork determine which actions are appropriate.
   • If your fork contains merge conflicts, GitLab shows a step-by-step guide to update your fork from the command line.

From the command line

You can also choose to update your fork from the command line.

Prerequisites:

• You must download and install the Git client on your local machine.
• You must create a fork of the repository you want to update.

To update your fork from the command line, follow the instruction in use Git to update a fork.

With repository mirroring

A fork can be configured as a mirror of the upstream if all these conditions are met:

1. Your subscription is Premium or Ultimate.
2. You create all changes in branches (not main).
3. You do not work on merge requests for confidential issues, which requires changes to main.

Repository mirroring keeps your fork synced with the original repository. This method updates your fork once per hour, with no manual git pull required. For instructions, read Configure pull mirroring.

Merge changes back upstream

When you are ready to send your code back to the upstream repository, create a new merge request as described in When you work in a fork. When successfully merged, your changes are added to the repository and branch you’re merging into.

Unlink a fork

Removing a fork relationship unlinks your fork from its upstream repository. Your fork then becomes an independent repository.

Prerequisites:

• You must be a project owner to unlink a fork.

To remove a fork relationship:

1. On the left sidebar, select Search or go to and find your project.
2. Select Settings > General.
3. Expand Advanced.
4. In the Remove fork relationship section, select Remove fork relationship.
5. To confirm, enter the project path and select Confirm.

GitLab logs the unlink operation in the audit log. When you unlink a fork that uses a hashed storage pool to share objects with another repository:

• All objects are copied from the pool into your fork.
• After the copy process completes, no further updates from the storage pool are propagated to your fork.

Check a fork’s storage usage

Your fork uses a deduplication strategy to reduce the storage space it needs. Your fork can access the object pool connected to the source repository.

For more information and to check the storage use, see View project fork storage usage.

Related topics

• GitLab community forum: Refreshing a fork
• Prevent project forking outside group
• Understand how Git LFS works with forks

Troubleshooting

Error: An error occurred while forking the project. Please try again

This error can be due to a mismatch in instance runner settings between the forked project and the new namespace. See Forks in the Runner documentation for more information.

Removing fork relationship fails

If removing the fork through the UI or API is not working, you can attempt the fork relationship removal in a Rails console session:

p = Project.find_by_full_path('<project_path>')
u = User.find_by_username('<username>')
Projects::UnlinkForkService.new(p, u).execute