Forking workflow · Repository · Project · User · Help · GitLab

Forking workflow · Repository · Project · User · Help · GitLab
Admin message
Due to an influx of spam, we have had to require each new account to be manually approved. Please register an account and then write an email to
accountsupport@archlinux.org
to get it approved. Sorry for the inconvenience.
Forks
Tier: Free, Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
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
Version history
Introduced
in GitLab 16.6.
To fork an existing project in GitLab:
On the project's homepage, in the upper-right corner, select
Fork
{fork}
).
Optional. Edit the
Project name
For
Project URL
, select the
namespace
your fork should belong to.
Add a
Project slug
. This value becomes part of the URL to your fork.
It must be unique in the namespace.
Optional. Add a
Project description
Select one of the
Branches to include
options:
All branches
(default).
Only the default branch
. Uses the
--single-branch
and
--no-tags
Git options
Select the
Visibility level
for your fork. For more information about
visibility levels, see
project and group visibility
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
Version history
Generally available
in GitLab 16.0. Feature flag
synchronize_fork
removed.
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:
You must create your fork from an
unprotected branch
in the upstream project.
To update your fork from the GitLab UI:
In the top bar, select
Search or go to
Select
View all my projects
Select the fork you want to update.
Below the dropdown list for branch name, find the
Forked from
{fork}
information box to determine if your fork is ahead, behind, or both. In this example,
the fork is behind the upstream project:
If your fork is
ahead
of the upstream project, select
Create merge request
to propose adding your fork's changes to the upstream project.
If your fork is
behind
the upstream project, select
Update fork
to pull changes from the upstream repository.
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:
You must
download and install the Git client
on your local machine.
You must
create a fork
of the project you want to update.
To update your fork from the command line, follow the instructions in
use Git to update a fork
With repository mirroring
Tier: Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
A fork can be configured as a mirror of the upstream project if all these conditions are met:
Your subscription is GitLab Premium or GitLab Ultimate.
You create all changes in branches (not
main
).
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.
Unlink a fork
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:
In the top bar, select
Search or go to
and find your project.
Select
Settings
General
Expand
Advanced
In the
Remove fork relationship
section, select
Remove fork relationship
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
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. 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
Project
find_by_full_path
''
User
find_by_username
''
Projects
::
UnlinkForkService
new
).
execute
Error:
User is not allowed to import projects
When forking a project using a service account, you might receive an error that states:
{"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.