Pull from a remote repository | GitLab Docs Skip to main content Go to GitLab Docs homepage What's new? What's new? Get free trial Toggle menu * Use GitLab * GitLab Duo * GitLab Orbit * Extend * Install * Administer * Subscribe * Contribute * Solutions Getting started Tutorials Manage your organization Organize work with projects Plan and track work Manage authentication and authorization Use Git Manage your code Getting started Repositories Protect your repository Branches Compare revisions Commits Forks File management File tree browser Repository size Tags Code Owners Mirroring Pull mirroring Push mirroring Bidirectional mirroring Troubleshooting Changelogs Snippets Push rules Signed commits Managing monorepos MLOps Merge requests Remote development Use CI/CD to build your application Secure your application Deploy and release your application Manage your infrastructure Monitor your application Analyze GitLab usage Release notes Feature support Find your GitLab version * GitLab Docs / * Use GitLab / * Manage your code / * Repositories / * Mirroring / * Pull mirroring Help us learn about your current experience with the documentation. Take the survey . Pull from a remote repository * Tier : Premium, Ultimate * Offering : GitLab.com, GitLab Self-Managed, GitLab Dedicated History * Moved to GitLab Premium in 13.9. You can use the GitLab interface to browse the content and activity of a repository, even if it isn t hosted on GitLab. Create a pull mirror to copy the branches, tags, and commits from an upstream repository to yours. Unlike push mirrors , pull mirrors retrieve changes from an upstream (remote) repository on a scheduled basis. To prevent the mirror from diverging from the upstream repository, don t push commits directly to the downstream mirror. Push commits to the upstream repository instead. Changes in the remote repository are pulled into the GitLab repository: * Automatically, 30 minutes after a previous pull. This cannot be disabled. * When an administrator force-updates the mirror . * When an API call triggers an update . UI and API updates are subject to default pull mirroring intervals of 5 minutes. This interval can be configured on GitLab Self-Managed instances. By default, if any branch or tag on the downstream pull mirror diverges from the local repository, GitLab stops updating the branch. This prevents data loss. Deleted branches and tags in the upstream repository are not reflected in the downstream repository. Items deleted from the downstream pull mirror repository, but still in the upstream repository, are restored upon the next pull. For example: a branch deleted only in the mirrored repository reappears after the next pull. How pull mirroring works After you configure a GitLab repository as a pull mirror: * GitLab adds the repository to a queue. * Once per minute, a Sidekiq cron job schedules repository mirrors to update, based on: * Available capacity, determined by Sidekiq settings. For GitLab.com, read GitLab.com Sidekiq settings . * How many mirrors are already in the queue and due for updates. Being due depends on when the repository mirror was last updated, and how many times updates have been retried. * Sidekiq becomes available to process updates, mirrors are updated. If the update process: * Succeeds: An update is enqueued again with at least a 30 minute wait. * Fails: The update is attempted again later. After 14 failures, a mirror is marked as a hard failure and is no longer enqueued for updates. A branch diverging from its upstream counterpart can cause failures. To prevent branches from diverging, configure overwrite diverged branches when you create your mirror. Configure pull mirroring Prerequisites: * If your remote repository is on GitHub and you have two-factor authentication (2FA) configured , create a personal access token for GitHub with the repo scope. If 2FA is enabled, this personal access token serves as your GitHub password. * GitLab Silent Mode is not enabled. * The upstream repository and your GitLab repository use the same object format. You cannot mirror between SHA-1 and SHA-256 repositories. * In the top bar, select Search or go to and find your project. * In the left sidebar, select Settings > Repository . * Expand Mirroring repositories . * Enter the Git repository URL . To mirror the gitlab repository, use gitlab.com:gitlab-org/gitlab.git or https://gitlab.com/gitlab-org/gitlab.git . * In Mirror direction , select Pull . * In Authentication method , select your authentication method. For more information, see authentication methods for mirrors . * Select any of the options you need: * Overwrite diverged branches * Trigger pipelines for mirror updates * Only mirror protected branches * To save the configuration, select Mirror repository . Overwrite diverged branches History * Moved to GitLab Premium in 13.9. To always update your local branches with remote versions, even if they have diverged from the remote, select Overwrite diverged branches when you create a mirror. For mirrored branches, enabling this option results in the loss of local changes. Trigger pipelines for mirror updates History * Moved to GitLab Premium in 13.9. You can configure your mirror to automatically trigger pipelines when the remote repository updates branches or tags. Before you enable this feature: * Ensure your CI runners can handle the additional load from the remote repository activity. * Consider the security risks, because the pipelines use the credentials of the user that set up the pull mirroring. For example, a malicious maintainer could: * Make an update to the remote repository that attempts to fetch stored CI/CD variable values when the pipeline runs. * Push commits to your mirrored project if the Allow Git push requests to the repository setting is enabled. Only enable this feature for your own projects or those with trusted maintainers. Pull mirroring with SSO enforcement When SSO enforcement is enabled for your group, the user who created the mirror must maintain an active SSO session or the mirror fails. To configure mirroring without SSO session dependency, you can use the Pull mirroring API with a project access token , group access token , or personal access token for service accounts. Trigger an update by using the API History * moved to GitLab Premium in 13.9. Pull mirroring uses polling to detect new branches and commits added upstream, often minutes afterwards. You can notify GitLab using an API call , but the minimum interval for pull mirroring limits is still enforced. For more information, see start the pull mirroring process for a project . Fix hard failures when mirroring History * Moved to GitLab Premium in 13.9. After 14 consecutive unsuccessful retries, the mirroring process is marked as a hard failure and mirroring attempts stop. This failure is visible in either the: * Project s main dashboard. * Pull mirror settings page. To resume project mirroring, force an update . If multiple projects are affected by this problem, such as after a long network or server outage, you can use the Rails console to identify and update all affected projects with this command: Project . find_each do | p | if p . import_state && p . import_state . retry_count >= 14 puts "Resetting mirroring operation for #{ p . full_path } " p . import_state . reset_retry_count p . import_state . set_next_execution_to_now ( prioritized : true ) p . import_state . save! end end Related topics * Troubleshooting for repository mirroring. * Pull mirroring intervals * Project pull mirroring API * How pull mirroring works * Configure pull mirroring * Overwrite diverged branches * Trigger pipelines for mirror updates * Pull mirroring with SSO enforcement * Trigger an update by using the API * Fix hard failures when mirroring * Related topics * Facebook * LinkedIn * Twitter * YouTube Company * About GitLab * View pricing * Try GitLab for free Feedback * View page source * Edit in Web IDE * Contribute to GitLab * Suggest updates Help & Community * Get certified * Get support * Post on the GitLab forum Resources * Terms * Privacy statement * Use of generative AI * Acceptable use of user licenses *