Create a repository mirror

Prerequisites:

You must have at least the Maintainer role for the project.

If your mirror connects with ssh:// , the host key must be detectable on the server, or you must have a local copy of the key.

On the left sidebar, select Search or go to and find your project.

Select Settings > Repository .

Expand Mirroring repositories .

Select Add new .

Enter a Git repository URL . For security reasons, the URL to the original repository is only displayed to users with the Maintainer role or the Owner role for the mirrored project.

Select a Mirror direction .

If you entered a ssh:// 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 into SSH host key .

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

Select an Authentication method . For more information, see Authentication methods for mirrors .

If you authenticate with SSH host keys, verify the host key to ensure it is correct.

To prevent force-pushing over diverged refs, select Keep divergent refs .

Optional. To limit the number of branches mirrored, select Mirror only protected branches or enter a regex in Mirror specific branches .

Select Mirror repository .

If you select SSH public key as your authentication method, GitLab generates a public key for your GitLab repository. You must provide this key to the non-GitLab server. For more information, see Get your SSH public key .

Mirror only protected branches

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

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

Mirror specific branches Tier: Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated History

Mirroring branches matching a regex as an option in API introduced in GitLab 15.8 with a flag named mirror_only_branches_match_regex . Disabled by default.

Option in the project setting introduced in GitLab 15.9. Enabled by default in GitLab 16.0. Generally available in GitLab 16.2. Feature flag mirror_only_branches_match_regex removed.

To mirror only branches with names matching an re2 regular expression , enter a regular expression into the Mirror specific branches field. Branches with names that do 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 the project’s activity feed. A repository mirror at GitLab updates automatically. You can also manually trigger an update:

At most once every five minutes on GitLab.com.

According to the pull mirroring interval limit set by the administrator on self-managed instances. 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.

The interval, in seconds for pull mirroring limits has not elapsed after its last update.

Prerequisites:

You must have at least the Maintainer role for the project.

On the left sidebar, select Search or go to and find your project.

Select Settings > Repository .

Expand Mirroring repositories .

Scroll to Mirrored repositories and identify the mirror to update.

Select Update now ( ):

Authentication methods for mirrors

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

Username and password.

For a project access token or group access token , use the username (not token name) 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 must verify the fingerprint of this host key manually.

If you’re mirroring over SSH (using an ssh:// 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 supports deploy keys .

Get your SSH public key

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

On the left sidebar, select Search or go to and find your project.

Select Settings > Repository .

Expand Mirroring repositories .

Scroll to Mirrored repositories .

Identify the correct repository, and select Copy SSH public key ( ).

Add the public SSH key to the other repository’s configuration:

If the other repository is hosted on GitLab, add the public SSH key as a deploy key .

If the other repository is hosted elsewhere, add the key to your user’s authorized_keys file. Paste the entire public SSH key into the file on its own line and save it.

If you must change the key at any time, you can remove and re-add the mirror to generate a new key. Update the other repository with the new key 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 fingerprints for you to check:

AWS CodeCommit

Bitbucket

Codeberg

GitHub

GitLab.com

Launchpad

Savannah

SourceForge

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

Run self-managed GitLab.

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.
Related topics
Troubleshooting for repository mirroring.

Configure a Pull Mirroring Interval

Disable mirrors for a project

Secrets file and mirroring to fix an error or add an improvement in a merge request.
Create an issue to suggest an improvement to this page.

Product

Create an issue if there's something you don't like about this feature.
Propose functionality by submitting a feature request.
Join First Look to help shape new features.

Feature availability and product trials

View pricing to see all GitLab tiers and features, or to upgrade.
Try GitLab for free with access to all features for 30 days.
search the docs .
If you want help with something specific and could use community support, post on the GitLab forum .
For problems setting up or using this feature (depending on your GitLab subscription).
Request support