GitLab's repository mirroring feature allows you to easily keep a fork of a project up to date by automatically synchronizing changes from the upstream repository. However, sometimes you may encounter errors when trying to update your fork using this feature. In this post, I will provide some common troubleshooting steps to help you resolve these errors and get your fork up to date.
The basics of mirroring a repository or updating a fork in GitLab
So you have forked a GitLab repository, and now your fork is out of sync with the upstream repo. Great, what to do?
As this is a big inconvenience, some people try to use the built-in GitLab repository mirroring feature that GitLab offers by going to the forked project and selecting "Settings" > "Repository" and expanding the "Mirroring repositories" section.
The configuration seems straightforward. However, things don't go as planned, and issues soon appear. Let's explore some common problems.
Select box for Mirror direction is disabled
If the "Mirror direction" selection is grayed out and disabled, this is a strong indicator that you are on a free GitLab.com plan or are using GitLab CE on your own infrastructure.
This select option is almost the root of all evil and causes a lot of confusion in terms of using this feature. [3][4] Let me explain.
First, there are two concepts we need to clarify:
- Downstream repository— this is your fork
- Upstream repository — this is from where you forked
When mirroring repositories, there are two directions:
- Pull — A pull mirror get its changes from an upstream repository (it does not need to be on GitLab) and copies them into the downstream repository. This would be ideal for updating a fork.
- Push-— A push mirror is the opposite of a pull mirror as it pushes changes to another repository (it essentially creates a copy). This approach makes sense when you want to back up your GitLab repository to other Git hosting services like GitHub or your self-hosted Git server.
Since, in this case, the mirror direction is set to "Push", any configuration you make will most likely result in a failure since you actually want to do the opposite: to update your fork with the change from the remote.
In conclusion, unless you upgrade to a paid GitLab plan (for this feature, GitLab Premium), you can't use this feature to update your fork, as you can't configure a pull mirror.
Creating well-researched and to-the-point content requires a lot of time and energy. If this was helpful and you wish to support me, please leave a comment, share, and press that 👏 a few times (up to 50 times). And consider subscribing to Medium.
The page is stuck on "The remote repository is being updated…"
If after a few minutes nothing happens, you can try refreshing the page and looking into the section "Mirrored repositories". Most likely, an error has occurred.
To view the error, simply hover over the "Error" label. This should display the error that has occurred.
The requested URL returned error: 301
When you sync, you may get this error:
13:get remote references: create git ls-remote: exit status 128, stderr: "fatal: unable to access 'https://gitlab.com/gitlab-com/www-gitlab-com/': The requested URL returned error: 301\n".
You need to ensure that the URL provided does not do a 301 Redirect and lead to another URL.
As you can see from the documentation, redirects are not followed. It is best to copy the URL by using the "Clone" button on the repository you wish to mirror.
Git repository URL — This field is required.
This error can be very confusing as it is clear you have supplied a value for this field.
In this case, if you wish to use SSH, you need to specify the protocol before the address. However, even how a new error will appear:
Remote mirrors url is blocked: URI is invalid
Remote mirrors url is blocked: URI is invalid
The problem seems to be the colon character (:) in the address, which needs to be replaced with a forward slash (/). [2]
Could not read Username for 'https://gitlab.com': terminal prompts disabled
Another error you can get is the following:
13:push to mirror: git push: exit status 128, stderr: "fatal: could not read Username for 'https://gitlab.com': terminal prompts disabled\n".
In this case, it seems that you have not supplied a username.
Make sure you understand the significance of the "Mirror direction" setting (see "Select box for Mirror direction is disabled").
HTTP Basic: Access denied. The provided password or token is incorrect or your account has 2FA enabled and you must use a personal access token instead of a password
This is an indication that your account has 2FA enabled, which it should, and don't even think about disabling that. To fix this issue, you need to create a personal access token or a project token.
Apart from this, make sure you understand the significance of the "Mirror direction" setting (see "Select box for Mirror direction is disabled").
13:push to mirror: git push: exit status 128, stderr: "remote: HTTP Basic: Access denied. The provided password or token is incorrect or your account has 2FA enabled and you must use a personal access token instead of a password. See https://gitlab.com/help/topics/git/troubleshooting_git#error-on-git-fetch-http-basic-access-denied\nfatal: Authentication failed for 'https://gitlab.com/gitlab-com/www-gitlab-com.git/'\n".
Conclusion
I hope this tutorial helped you debug your problem while configuring your GitLab repository mirror. Leave a comment in the section below if you have any questions. I would love to hear from you!
Thank you for sticking with this article until the end. If you enjoyed it, please leave a comment, share, and press that 👏 a few times (up to 50 times). It will help others discover this information, and maybe it will help someone else as well.
Follow me on Medium and YouTube if you're interested in more tutorials like this.
Want to learn more about Gitlab CI?
I am not only writing posts, but I am also an online instructor. So if you are interested in learning more about Gitlab CI, maybe you want to take a look at my Gitlab CI: Pipelines, CI/CD, and DevOps for Beginners online course.
References
[1] GitLab (n.d.). Repository mirroring. GitLab Docs. Retrieved January 7, 2023, from https://docs.gitlab.com/ee/user/project/repository/mirror/
[2] GitLab (n.d.). Mirror SSH URL is seen as invalid. GitLab FOSS Issues. Retrieved January 7, 2023, from https://gitlab.com/gitlab-org/gitlab-foss/-/issues/59032
[3] GitLab (n.d.). Refreshing a Fork. GitLab Forum. Retrieved January 7, 2023, from https://forum.gitlab.com/t/refreshing-a-fork/32469
[4] Ramos, M. (2016, December 1). How to keep your fork up to date with its origin. GitLab Blog. Retrieved January 7, 2023, from https://about.gitlab.com/blog/2016/12/01/how-to-keep-your-fork-up-to-date-with-its-origin/