Push mirroring

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

A push mirror is a downstream repository that mirrors the commits made to the upstream repository. Push mirrors passively receive copies of the commits made to the upstream repository. 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.

While pull mirroring periodically retrieves updates from the upstream repository, push mirrors only receive changes when:

Commits are pushed to the upstream GitLab repository.
An administrator force-updates the mirror.

When you push a change to the upstream repository, the push mirror receives it in five minutes, or one minute if the setting Only mirror protected branches is on.

When a branch is merged into the default branch and deleted in the source project, it is deleted from the remote mirror on the next push. Branches with unmerged changes are kept. If a branch diverges, the Mirroring repositories section displays an error.

GitLab Silent Mode disables pushing to, and pulling from, remote mirrors.

Push mirror limits

Each project can have a maximum of 10 enabled push mirrors. For more information, see maximum number of project push mirrors.

Configure push mirroring

To set up push mirroring for an existing project:

In the top bar, select Search or go to and find your project.
Select Settings > Repository.
Expand Mirroring repositories.
Enter a repository URL.
In the Mirror direction dropdown list, select Push.
Select an Authentication method. For more information, see authentication methods for mirrors.
Select Only mirror protected branches, if necessary.
Select Keep divergent refs, if desired.
To save the configuration, select Mirror repository.

Configure push mirrors through the API

You can also create and modify project push mirrors through the remote mirrors API.

Keep divergent refs

By default, if any ref (branch or tag) on the remote (downstream) mirror diverges from the local repository, the upstream repository overwrites any changes on the remote:

A repository mirrors main and develop branches to a remote.
A new commit is added to develop on the remote mirror.
The next push updates the remote mirror to match the upstream repository.
The new commit added to develop on the remote mirror is lost.

If Keep divergent refs is selected, the changes are handled differently:

Updates to the develop branch on the remote mirror are skipped.
The develop branch on the remote mirror preserves the commit that does not exist on the upstream repository. Any refs that exist in the remote mirror, but not the upstream, are left untouched.
The update is marked failed.

After you create a mirror, you can only modify the value of Keep divergent refs through the remote mirrors API.

Set up a push mirror from GitLab to GitHub

When you push commits from GitLab to GitHub, GitHub determines commit attribution based on email addresses. If the commit email address matches a verified email on a GitHub user account, GitHub attributes the commit to that user. Otherwise, the commit appears as unattributed with only the name and email from the commit metadata.

Prerequisites:

A GitHub fine-grained personal access token with read and write permissions for repository contents. If your repository contains a .github/workflows directory, you must also grant read and write access for Workflows. For more fine-grained access, configure your token to apply only to the specific repository.

To set up the mirror:

For Git repository URL, enter the URL with this format:
plaintext
```
https://github.com/GROUP/PROJECT.git
```
- GROUP: The group on GitHub.
- PROJECT: The project on GitHub.
For Username, enter the username of the owner of the personal access token.
For Password, enter your GitHub personal access token.
Select Mirror repository.

The mirrored repository is listed. For example:

plaintext

https://*****:*****@github.com/<your_github_group>/<your_github_project>.git

The repository pushes shortly thereafter. To force a push, select Update now ({{< icon name="retry" >}}).

Set up a push mirror from GitLab to AWS CodeCommit

AWS CodeCommit push mirroring is the best way to connect GitLab repositories to AWS CodePipeline. GitLab is not yet supported as one of their Source Code Management (SCM) providers. Each new AWS CodePipeline needs significant AWS infrastructure setup. It also requires an individual pipeline per branch.

If AWS CodeDeploy is the final step of a CodePipeline, you can, instead combine these tools to create a deployment:

GitLab CI/CD pipelines.
The AWS CLI in the final job in .gitlab-ci.yml to deploy to CodeDeploy.

To set up a mirror from GitLab to AWS CodeCommit:

In the AWS IAM console, create an IAM user.

Add the following least privileges permissions for repository mirroring as an inline policy.

The Amazon Resource Names (ARNs) must explicitly include the region and account. This IAM policy grants privilege for mirroring access to two sample repositories. These permissions have been tested to be the minimum (least privileged) required for mirroring:

json

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "MinimumGitLabPushMirroringPermissions",
            "Effect": "Allow",
            "Action": [
                "codecommit:GitPull",
                "codecommit:GitPush"
            ],
            "Resource": [
              "arn:aws:codecommit:us-east-1:111111111111:MyDestinationRepo",
              "arn:aws:codecommit:us-east-1:111111111111:MyDemo*"
            ]
        }
    ]
}

After the user is created, select the AWS IAM user name.
Select the Security credentials tab.
Under HTTPS Git credentials for AWS CodeCommit, select Generate credentials.

[!note] This Git user ID and password is specific to communicating with CodeCommit. Do not confuse it with the IAM user ID or AWS keys of this user.
Copy or download the special Git HTTPS user ID and password.
In the AWS CodeCommit console, create a new repository to mirror from your GitLab repository.
Open your new repository, in the upper-right corner, select Code > Clone HTTPS (not Clone HTTPS (GRC)).
In GitLab, open the repository to be push-mirrored.
Select Settings > Repository, and then expand Mirroring repositories.
Fill in the Git repository URL field using this format, replacing <aws-region> with your AWS region, and <your_codecommit_repo> with the name of your repository in CodeCommit:
plaintext
```
https://git-codecommit.<aws-region>.amazonaws.com/v1/repos/<your_codecommit_repo>
```
For Authentication method, select Username and Password.
For Username, enter the AWS special HTTPS Git user ID.
For Password, enter the special IAM Git clone user ID password created earlier in AWS.
Leave the option Only mirror protected branches for CodeCommit. It pushes more frequently (from every five minutes to every minute).

CodePipeline requires individual pipeline setups for named branches you want to have a AWS CI setup for. Because feature branches with dynamic names are unsupported, configuring Only mirror protected branches doesn't cause flexibility problems with CodePipeline integration. You must also protect all the named branches you want to build CodePipelines for.

Select Mirror repository. You should see the mirrored repository appear: