Help us learn about your current experience with the documentation. Take the survey.

推送镜像

版本层级：Free, Premium, Ultimate
提供方式：GitLab.com, GitLab Self-Managed, GitLab Dedicated

推送镜像（push mirror）是一个下游仓库，它会镜像上游仓库中的提交。推送镜像被动接收上游仓库提交的副本。为防止镜像与上游仓库产生分歧，不要直接向下游镜像推送提交。相反，应该向上游仓库推送提交。

而拉取镜像会定期从上游仓库检索更新，推送镜像仅在以下情况接收变更：

提交被推送到上游 GitLab 仓库。
管理员强制更新镜像。

当您向上游仓库推送变更时，推送镜像会在五分钟内接收，如果开启 Only mirror protected branches 设置，则在一分钟内接收。

当分支被合并到默认分支并在源项目中删除时，它会在下一次推送时从远程镜像中删除。具有未合并更改的分支会被保留。如果分支产生分歧，Mirroring repositories 部分会显示错误。

GitLab 静默模式禁止向远程镜像推送和从远程镜像拉取。

配置推送镜像

为现有项目设置推送镜像：

在左侧边栏，选择 Search or go to 并找到您的项目。
选择 Settings > Repository。
展开 Mirroring repositories。
输入仓库 URL。
在 Mirror direction 下拉列表中，选择 Push。
选择 Authentication method。更多信息，请参见 Authentication methods for mirrors。
如有必要，选择 Only mirror protected branches。
如需要，选择 Keep divergent refs。
要保存配置，选择 Mirror repository。

通过 API 配置推送镜像

您还可以通过 remote mirrors API 创建和修改项目推送镜像。

保留 divergent refs

默认情况下，如果远程（下游）镜像上的任何 ref（分支或标签）与本地仓库产生分歧，上游仓库会覆盖远程上的任何更改：

仓库将 main 和 develop 分支镜像到远程。
在远程镜像的 develop 分支上添加了一个新提交。
下一次推送会更新远程镜像以匹配上游仓库。
添加到远程镜像 develop 分支的新提交会丢失。

如果选择了 Keep divergent refs，更改的处理方式会有所不同：

跳过对远程镜像上 develop 分支的更新。
远程镜像上的 develop 分支保留了在上游仓库中不存在的提交。任何存在于远程镜像但不存在于上游的 refs 都保持不变。
更新被标记为失败。

创建镜像后，您只能通过 remote mirrors API 修改 Keep divergent refs 的值。

设置从 GitLab 到 GitHub 的推送镜像

要配置从 GitLab 到 GitHub 的镜像：

创建一个 GitHub 细粒度个人访问令牌，授予对 repository contents 的至少读写权限。如果您的仓库包含 .github/workflows 目录，还必须授予 Workflows 的读写权限。为了更细粒度的访问，您可以配置令牌仅适用于特定仓库。
输入 Git repository URL，使用以下格式，根据需要更改变量：
```
https://github.com/GROUP/PROJECT.git
```
- GROUP: GitHub 上的组。
- PROJECT: GitHub 上的项目。
对于 Username，输入个人访问令牌所有者的用户名。
对于 Password，输入您的 GitHub 个人访问令牌。
选择 Mirror repository。

镜像仓库会列出。例如：

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

仓库随后会推送。要强制推送，选择 Update now ( )。

设置从 GitLab 到 AWS CodeCommit 的推送镜像

AWS CodeCommit 推送镜像是将 GitLab 仓库连接到 AWS CodePipeline 的最佳方式。GitLab 尚不被支持作为他们的源代码管理（SCM）提供商之一。每个新的 AWS CodePipeline 都需要大量的 AWS 基础设施设置。它还需要为每个分支单独设置管道。

如果 AWS CodeDeploy 是 CodePipeline 的最后一步，您可以结合这些工具来创建部署：

GitLab CI/CD 管道。
在 .gitlab-ci.yml 的最后一个作业中使用 AWS CLI 部署到 CodeDeploy。

在 GitLab issue 34014 解决之前，GitLab 到 AWS CodeCommit 的推送镜像无法使用 SSH 认证。

要设置从 GitLab 到 AWS CodeCommit 的镜像：

在 AWS IAM 控制台中创建一个 IAM 用户。

添加以下用于仓库镜像的最小权限作为 inline policy。

Amazon 资源名称（ARN）必须明确包含区域和账户。此 IAM 策略授予对两个示例仓库的镜像访问权限。这些权限已被测试为镜像所需的最小（最少权限）权限：

{
    "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*"
            ]
        }
    ]
}

用户创建后，选择 AWS IAM 用户名。
选择 Security credentials 选项卡。
在 HTTPS Git credentials for AWS CodeCommit 下，选择 Generate credentials。

此 Git 用户 ID 和密码专门用于与 CodeCommit 通信。不要将其与此用户的 IAM 用户 ID 或 AWS 密钥混淆。
复制或下载特殊的 Git HTTPS 用户 ID 和密码。
在 AWS CodeCommit 控制台中，创建一个新仓库来镜像您的 GitLab 仓库。
打开您的新仓库，在右上角，选择 Code > Clone HTTPS（不是 Clone HTTPS (GRC)）。
在 GitLab 中，打开要推送镜像的仓库。
选择 Settings > Repository，然后展开 Mirroring repositories。
使用以下格式填写 Git repository URL 字段，将 <aws-region> 替换为您的 AWS 区域，将 <your_codecommit_repo> 替换为您的 CodeCommit 仓库名称：
```
https://git-codecommit.<aws-region>.amazonaws.com/v1/repos/<your_codecommit_repo>
```
对于 Authentication method，选择 Username and Password。
对于 Username，输入 AWS special HTTPS Git user ID。
对于 Password，输入之前在 AWS 中创建的特殊 IAM Git 克隆用户 ID 密码。
为 CodeCommit 保留 Only mirror protected branches 选项。它会更频繁地推送（从每五分钟到每分钟）。

CodePipeline 需要为您想要设置 AWS CI 的命名分支单独设置管道。由于不支持动态名称的功能分支，配置 Only mirror protected branches 不会导致与 CodePipeline 集成的灵活性问您还必须保护所有想要构建 CodePipeline 的命名分支。

选择 Mirror repository。您应该会看到镜像仓库出现：

https://*****:*****@git-codecommit.<aws-region>.amazonaws.com/v1/repos/<your_codecommit_repo>

要通过强制推送测试镜像，选择 Update now（半圆箭头）。如果 Last successful update 显示日期，说明您已正确配置镜像。如果工作不正常，会出现红色 error 标签，并将错误消息显示为悬停文本。

设置到启用 2FA 的另一个 GitLab 实例的推送镜像

在目标 GitLab 实例上，创建一个具有 write_repository 范围的 personal access token。
在源 GitLab 实例上：
1. 使用以下格式输入 Git repository URL： https://<destination host>/<your_gitlab_group_or_name>/<your_gitlab_project>.git。
2. 输入 Username oauth2。
3. 输入 Password。使用在目标 GitLab 实例上创建的 GitLab personal access token。
4. 选择 Mirror repository。