ContextQMD
Back to Gitlabhq

Forks

doc/user/project/repository/forking_workflow.md

18.11.211.1 KB
Original Source

{{< details >}}

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

A fork is a personal copy of another project, created in the namespace of your choice. Your fork contains a copy of the upstream project's repository and some project settings, but not project content like issues, merge requests, or wiki pages. You can create merge requests from your fork to target the upstream project. Individual commits can also be cherry-picked from your fork into the upstream project.

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

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

[!note] If the upstream project is archived, the fork relationship is automatically removed. Merge requests that were closed due to a broken fork relationship are not reopened if the fork relationship is later restored.

For more information, see archive a project.

Create a fork

{{< history >}}

{{< /history >}}

To fork an existing project in GitLab:

  1. On the project's homepage, in the upper-right corner, select Fork ({{< icon name="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, see 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 project, 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 project, 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 project.

From the UI

{{< history >}}

{{< /history >}}

When you update a fork from the UI, the following repository protection settings on the fork are bypassed:

  • Push rules configured on the fork.
  • File locking applied to files in the fork.

This behavior prevents synchronization failures when the upstream project and fork have different protection configurations. The synchronization process pulls changes from the upstream repository and applies them directly to the fork.

Prerequisites:

To update your fork from the GitLab UI:

  1. In the top bar, 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 ({{< icon name="fork" >}}) information box to determine if your fork is ahead, behind, or both. In this example, the fork is behind the upstream project:

  5. If your fork is ahead of the upstream project, select Create merge request to propose adding your fork's changes to the upstream project.

  6. If your fork is behind the upstream project, select Update fork to pull changes from the upstream repository.

  7. If your fork is ahead and behind the upstream project, 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 project, 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 update your fork from the command line.

Prerequisites:

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

With repository mirroring

{{< details >}}

  • Tier: Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

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

  1. Your subscription is GitLab Premium or GitLab 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 project. This method updates your fork once per hour, with no manual git pull required. For instructions, see configure pull mirroring.

[!warning] With mirroring, before approving a merge request, you are asked to sync. You should automate it.

Merge changes back upstream

When you are ready to send your code back to the upstream project, create a new merge request as described in when you work in a fork. When successfully merged, your changes are added to the upstream repository.

After your merge request is merged upstream, the branch in your fork is not automatically considered Merged for bulk deletion purposes. The branch is only considered merged if your fork's default branch contains those changes. To mark these branches as merged in your fork, update your fork to sync with the upstream project.

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

Prerequisites:

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

[!warning] If you remove a fork relationship, you can't send new merge requests to the source. Any existing open merge requests from the fork to the source are also closed. If anyone has forked your project, their fork also loses the relationship. To restore the fork relationship, use the Project forks API.

To remove a fork relationship:

  1. In the top bar, 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.

Delete a fork

Deleting a fork permanently removes the project and all its contents, including the fork relationship. This action is the same as deleting any other project.

To delete a fork, see delete a project.

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 project.

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

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. For more information, see using instance runners in forked projects.

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:

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

Error: User is not allowed to import projects

When forking a project using a service account, you might receive an error that states:

plaintext
{"message":["Namespace is not valid","User is not allowed to import projects"]}

This issue occurs because service accounts are bot users and cannot fork projects to their personal namespace, even if their project limit has been increased.

When using a service account to fork a project, the workaround is to specify a target group namespace using either namespace_id or namespace_path in the Project forks API. The service account must be a member of the target group with the Developer, Maintainer, or Owner role.