This blog post has not been updated since publishing in 2016, so it contains outdated information. For an up-to-date source, please see the documentation on Repository Mirroring.
Have you ever wondered how to keep a fork automatically up-to-date with its origin (upstream)?
In this post we'll show you how to do that on GitLab!
Fork
As you most likely know, a fork is a copy of a Git repository "connected" with the project you forked from (upstream). When you collaborate on code, it's pretty common forking a project, cloning to your local machine, making the changes you're up to, pushing to your fork, and submitting a merge request (MR) to merge your code into the original project.
You fork a repository whenever you want to contribute to a project which you don't have access to, as it's not your own or your team's. This is how open source projects hosted by GitLab get so much collaboration from the community.
When you are a member of a project (or a group), it's easier using the GitLab Flow, or branching strategy, since anyone in your team can pull your branch and preview your changes locally. By the way, with our brand-new solution for this, called Review Apps, you can preview your apps in a per-branch basis, for each MR submitted to GitLab, directly from a link generated by GitLab. Review Apps came to bring the GitLab Workflow up to the next level! 🙌
The Problem
When you fork a project and clone it to your local computer, you'll eventually need to update it with the master branch of the upstream project (or whatever the default branch is set to). That way you will be able to checkout an up-to-date branch to work from. If you do not do that, you are very likely to stumble upon merge conflicts in the end, since the copy of the code you're working could be out-of-date.
To prevent this, first you'd need to pull the upstream, push to the remote, checkout a new branch from the master branch up-to-date, then finally start working on your changes. This takes time, and if you forget to do it, can cause a lot of pain. This process takes some time to complete, and turns out to be annoying if you need to do this multiple times a day. That's why we could use a better solution.
The Solution
GitLab can do that for you with no pain! Yay! What you need to do is very simple: enable GitLab Repository Mirroring!
First. Mirror your fork:
Under your forked project's Settings, navigate to Mirror Repository:
Second. Add the upstream's path to the field Git repository URL, then enable automatic mirroring:
Third. Set up the mirror user: it's the user whose new commits to the upstream project will be attributed to in your fork.
Done! Once an hour, GitLab will pull the upstream for you, and keep your fork up-to-date!
By doing so, you only need to proceed as you usually do for your own projects (pull, checkout a new branch, and push your commits). All the rest GitLab does for you!
Simple, isn't it?
The Secret
In order to pull without authentication from an upstream repository you are contributing to, the project should be public in the first place. Also, the Repository's Feature Visibility settings of the upstream project needs to be set to Everyone with access:
You can find them in your project's Settings () > Edit Project.
Note that you can mirror private projects as well, but you'd need to be a member of the project or the group it belongs.
What is Your Solution?
We would love to know how you do that! Do you have a different solution? You can certainly help others. Please share them in the comments, so everyone from the community can decide which solution is the best for them. Thank you!
Conclusion
Hopefully, we provided you with an easy solution for keeping your fork up-to-date. Remember, you can even mirror repositories hosted in other Git platforms!
Cool! I'm looking forward to hearing from you: feedback, questions, and suggestions are very welcome! Leave your comment below, and/or tweet at us @GitLab! We our community!
