Project forking workflow

Whenever possible, it’s recommended to work in a common Git repository and use branching strategies to manage your work. However, if you do not have write access for the repository you want to contribute to, you can create a fork.

A fork is a personal copy of the repository and all its branches, which you create in a namespace of your choice. This way you can make changes in your own fork and submit them through a merge request to the repository you don’t have access to.

Creating a fork

Forking a project is, in most cases, a two-step process.

  1. On the project’s home page, in the top right, click the Fork button.

    Fork button

  2. Click a namespace to fork to. Only namespaces you have Developer and higher permissions for are shown.

    noteThe project path must be unique within the namespace.

    Choose namespace

The fork is created. The permissions you have in the namespace are your permissions in the fork.

cautionWhen a public project with the repository feature set to Members Only is forked, the repository is public in the fork. The owner of the fork must manually change the visibility. This is being fixed in #36662.

Repository mirroring

You can use repository mirroring to keep your fork synced with the original repository. You can also use git remote add upstream to achieve the same result.

The main difference is that with repository mirroring, your remote fork is automatically kept up-to-date.

Without mirroring, to work locally you must use git pull to update your local repository with the upstream project, then push the changes back to your fork to update it.

cautionWith mirroring, before approving a merge request, you are asked to sync. Because of this, automating it is recommended.

Read more about How to keep your fork up to date with its origin.

Merging upstream

When you are ready to send your code back to the upstream project, create a merge request. For Source branch, choose your forked project’s branch. For Target branch, choose the original project’s branch.

noteWhen creating a merge request, if the forked project’s visibility is more restrictive than the parent project (for example the fork is private, the parent is public), the target branch defaults to the forked project’s default branch. This prevents potentially exposing the private code of the forked project.

Selecting branches

Then you can add labels, a milestone, and assign the merge request to someone who can review your changes. Then click Submit merge request to conclude the process. When successfully merged, your changes are added to the repository and branch you’re merging into.

Removing a fork relationship

You can unlink your fork from its upstream project in the advanced settings.