Repository mirroring

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

You can mirror a repository to and from external sources. You can select which repositoryserves as the source. Branches, tags, and commits are synced automatically.

Several mirroring methods exist:

  • Push: Mirror a repository from GitLab to another location.
  • Pull: Mirror a repository from another location. Available in the Premium and Ultimate tier.
  • Bidirectional mirroring is also available, but can cause conflicts.

Mirror a repository when:

  • The canonical version of your project has migrated to GitLab. To keep providing acopy of your project at its previous home, configure your GitLab repository as apush mirror. Changes you make to your GitLab repository are copied tothe old location.
  • Your GitLab instance is private, but you want to open-source some projects.
  • You migrated to GitLab, but the canonical version of your project is somewhere else.Configure your GitLab repository as apull mirror of the other project.Your GitLab repository pulls copies of the commits, tags, and branches of project.They become available to use on GitLab.

The following is not supported:

  • SCP-style URLs. The work to implement SCP-style URLs is ongoing.For more information and to track its progress, seeissue 18993.
  • Mirroring repositories overdumb HTTP protocol.

Create a repository mirror

Prerequisites:

  • You must have at least the Maintainer role for the project.
  • If your mirror connects withssh://, the host key must be detectable on the server,or you must have a local copy of the key.

  1. On the left sidebar, selectSearch or go to and find your project. If you’veturned on the new navigation, this field is on the top bar.

  2. SelectSettings >Repository.

  3. ExpandMirroring repositories.

  4. SelectAdd new.

  5. Enter aGit repository URL. The repository must be accessible overhttp://,https://,ssh://, orgit://.

  6. Select aMirror direction. For more information, seePull mirroring andPush mirroring.

  7. If you entered anssh:// URL, select either:

    • Detect host keys: GitLab fetches the host keys from the server and displays the fingerprints.
    • Input host keys manually, and enter the host key intoSSH host key.

    When mirroring the repository, GitLab confirms that at least one of the stored host keysmatches before connecting. This check protects your mirror from malicious code injections,or your password from being stolen.

  8. Select anAuthentication method. For more information, seeAuthentication methods for mirrors.

  9. If you authenticate with SSH host keys,verify the host keyto ensure it is correct.

  10. To prevent force-pushing over diverged refs, selectKeep divergent refs. For more information, seeKeep divergent refs.

  11. Optional. To limit the number of branches mirrored, selectMirror only protected branches or enter a regex inMirror specific branches.

  12. SelectMirror repository.

Example: Create mirror with SSH authentication

If you selectSSH public key as your authentication method, GitLab generates apublic key for your GitLab repository. You must provide this key to the non-GitLab server.For more information, seeGet your SSH public key.

To mirror a repository with SSH authentication:

  1. On the left sidebar, selectSearch or go to and find your project. If you’veturned on the new navigation, this field is on the top bar.

  2. SelectSettings >Repository.

  3. ExpandMirroring repositories.

  4. SelectAdd new.

  5. Enter aGit repository URL. Provide a URL in the formatssh://gitlab.com/gitlab-org/gitlab.git.

    SSH URLs must use the formatssh://host/path/to/repo.git instead ofSCP-style URLs (git@host:path/to/repo.git). Replace the colon (:)with a slash (/) and add thessh:// prefix.

  6. Select aMirror direction. For more information, seePull mirroring andPush mirroring.

  7. Select eitherDetect host keys orInput host keys manually.

  8. In theAuthentication method field, selectSSH public key

  9. In theUsername field, addgit.

  10. Optional. Configure theMirror user andMirror branches settings.

  11. SelectMirror repository.

  12. Copy the SSH public key and provide it to your non-GitLab server.

Mirror only protected branches

You can choose to mirror only theprotected branches in the mirroring project,either from or to your remote repository. Forpull mirroring,non-protected branches in the mirroring project are not mirrored and can diverge.

To use this option, selectOnly mirror protected branches when you create a repository mirror.

Mirror specific branches

  • Tier: Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

To mirror only branches with names matching anre2 regular expression,enter a regular expression into theMirror specific branches field. Branches with names thatdo not match the regular expression are not mirrored.

Update a mirror

When the mirror repository is updated, all new branches, tags, and commits are visible in theproject’s activity feed. A repository mirror at GitLab updates automatically.You can also manually trigger an update:

GitLab Silent Mode disables both push and pull updates.

Force an update

While mirrors are scheduled to update automatically, you can force an immediate update unless:

  • The mirror is already being updated.
  • Theinterval, in secondsfor pull mirroring limits has not elapsed after its last update.

Prerequisites:

  • You must have at least the Maintainer role for the project.
  1. On the left sidebar, selectSearch or go to and find your project. If you’veturned on the new navigation, this field is on the top bar.
  2. SelectSettings >Repository.
  3. ExpandMirroring repositories.
  4. Scroll toMirrored repositories and identify the mirror to update.
  5. SelectUpdate now (retry).

Authentication methods for mirrors

When you create a mirror, you must configure the authentication method for it.GitLab supports these authentication methods:

For aproject access token orgroup access token,use a non-blank value as a username and the token as the password.

SSH authentication

SSH authentication is mutual:

  • You must prove to the server that you’re allowed to access the repository.
  • The server must also prove to you that it’s who it claims to be.

For SSH authentication, you provide your credentials as a password or public key.The server that the other repository resides on provides its credentials as a host key.You mustverify the fingerprint of this host key manually.

If you’re mirroring over SSH (using anssh:// URL), you can authenticate using:

  • Password-based authentication, just as over HTTPS.
  • Public key authentication. This method is often more secure than password authentication,especially when the other repository supportsdeploy keys.

Get your SSH public key

When you mirror a repository and select theSSH public key as yourauthentication method, GitLab generates a public key for you. The non-GitLab serverneeds this key to establish trust with your GitLab repository. To copy your SSH public key:

  1. On the left sidebar, selectSearch or go to and find your project. If you’veturned on the new navigation, this field is on the top bar.
  2. SelectSettings >Repository.
  3. ExpandMirroring repositories.
  4. Scroll toMirrored repositories.
  5. Identify the correct repository, and selectCopy SSH public key (copy-to-clipboard).
  6. Add the public SSH key to the other repository’s configuration:
    • If the other repository is hosted on GitLab, add the public SSH keyas adeploy key.
    • If the other repository is hosted elsewhere, add the key toyour user’sauthorized_keys file. Paste the entire public SSH key into thefile on its own line and save it.

If you must change the key at any time, you can remove and re-add the mirrorto generate a new key. Update the other repository with the newkey to keep the mirror running.

The generated keys are stored in the GitLab database, not in the file system. Therefore,SSH public key authentication for mirrors cannot be used in a pre-receive hook.

Verify a host key

When using a host key, always verify the fingerprints match what you expect.GitLab.com and other code hosting sites publish their fingerprintsfor you to check:

Other providers vary. You can securely gather key fingerprints with the followingcommand if you:

  • Run GitLab Self-Managed.
  • Have access to the server for the other repository.
$ cat /etc/ssh/ssh_host*pub| ssh-keygen -E md5 -l -f -256 MD5:f4:28:9f:23:99:15:21:1b:bf:ed:1f:8e:a0:76:b2:9d root@example.com(ECDSA)256 MD5:e6:eb:45:8a:3c:59:35:5f:e9:5b:80:12:be:7e:22:73 root@example.com(ED25519)2048 MD5:3f:72:be:3d:62:03:5c:62:83:e8:6e:14:34:3a:85:1d root@example.com(RSA)

Older versions of SSH may require you to remove-E md5 from the command.