diff options
Diffstat (limited to 'doc/user/project/repository/repository_mirroring.md')
| -rw-r--r-- | doc/user/project/repository/repository_mirroring.md | 46 |
1 files changed, 25 insertions, 21 deletions
diff --git a/doc/user/project/repository/repository_mirroring.md b/doc/user/project/repository/repository_mirroring.md index 3bbe9e6cb66..e9f214f08ce 100644 --- a/doc/user/project/repository/repository_mirroring.md +++ b/doc/user/project/repository/repository_mirroring.md @@ -8,7 +8,7 @@ disqus_identifier: 'https://docs.gitlab.com/ee/workflow/repository_mirroring.htm # Repository mirroring **(FREE)** Repository mirroring allows for the mirroring of repositories to and from external sources. You -can use it to mirror branches, tags, and commits between repositories. It's useful when you want to use +can use it to mirror branches, tags, and commits between repositories. It helps you use a repository outside of GitLab. A repository mirror at GitLab updates automatically. You can also manually trigger an update @@ -22,21 +22,22 @@ There are two kinds of repository mirroring supported by GitLab: When the mirror repository is updated, all new branches, tags, and commits are visible in the project's activity feed. -Users with [Maintainer access](../../permissions.md) to the project can also force an +Users with the [Maintainer role](../../permissions.md) for the project can also force an immediate update, unless: - The mirror is already being updated. - The [limit for pull mirroring interval seconds](../../../administration/instance_limits.md#pull-mirroring-interval) has not elapsed since its last update. -For security reasons, the URL to the original repository is only displayed to users with -Maintainer or Owner permissions to the mirrored project. +For security reasons, the URL to the original repository is only displayed to users with the +[Maintainer role](../../permissions.md) or the [Owner role](../../permissions.md) for the mirrored +project. ## Use cases The following are some possible use cases for repository mirroring: - You migrated to GitLab but still need to keep your project in another source. In that case, you - can simply set it up to mirror to GitLab (pull) and all the essential history of commits, tags, + can set it up to mirror to GitLab (pull) and all the essential history of commits, tags, and branches are available in your GitLab instance. **(PREMIUM)** - You have old projects in another source that you don't use actively anymore, but don't want to remove for archiving purposes. In that case, you can create a push mirror so that your active @@ -65,9 +66,9 @@ For an existing project, you can set up push mirroring as follows:  When push mirroring is enabled, only push commits directly to the mirrored repository to prevent the -mirror diverging. +mirror diverging. -Unlike [pull mirroring](#how-it-works), the mirrored repository is not periodically auto-synced. +Unlike [pull mirroring](#how-it-works), the mirrored repository is not periodically auto-synced. The mirrored repository receives all changes only when: - Commits are pushed to GitLab. @@ -93,19 +94,19 @@ You can also create and modify project push mirrors through the By default, if any ref on the remote mirror has diverged from the local repository, the *entire push* fails, and no updates occur. -For example, if a repository has `master`, `develop`, and `stable` branches that +For example, if a repository has `main`, `develop`, and `stable` branches that have been mirrored to a remote, and then a new commit is added to `develop` on -the mirror, the next push attempt fails, leaving `master` and `stable` +the mirror, the next push attempt fails, leaving `main` and `stable` out-of-date despite not having diverged. No change on any branch can be mirrored until the divergence is resolved. With the **Keep divergent refs** option enabled, the `develop` branch is -skipped, allowing `master` and `stable` to be updated. The mirror status +skipped, allowing `main` and `stable` to be updated. The mirror status reflects that `develop` has diverged and was skipped, and be marked as a failed update. NOTE: -After the mirror is created, this option can currently only be modified via the [API](../../../api/remote_mirrors.md). +After the mirror is created, this option can only be modified via the [API](../../../api/remote_mirrors.md). ### Setting up a push mirror from GitLab to GitHub @@ -122,11 +123,15 @@ The repository pushes shortly thereafter. To force a push, select the **Update n ### Setting up a push mirror from GitLab to AWS CodeCommit -AWS CodeCommit push mirroring is currently the best way to connect GitLab repositories to AWS CodePipeline, as GitLab isn't yet supported as one of their Source Code Management (SCM) providers. +AWS CodeCommit push mirroring is the best way to connect GitLab repositories to +AWS CodePipeline, as GitLab isn't 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. +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, leverage GitLab CI/CD pipelines and simply use the AWS CLI in the final job in `.gitlab-ci.yml` to deploy to CodeDeploy. +If AWS CodeDeploy is the final step of a CodePipeline, you can, instead, leverage +GitLab CI/CD pipelines and use the AWS CLI in the final job in `.gitlab-ci.yml` +to deploy to CodeDeploy. NOTE: GitLab-to-AWS-CodeCommit push mirroring cannot use SSH authentication until [GitLab issue 34014](https://gitlab.com/gitlab-org/gitlab/-/issues/34014) is resolved. @@ -214,10 +219,9 @@ If it isn't working correctly, a red `error` tag appears and shows the error mes You can set up a repository to automatically have its branches, tags, and commits updated from an upstream repository. -This is useful when a repository you're interested in is located on a different server, and you want -to be able to browse its content and its activity using the familiar GitLab interface. - -To configure mirror pulling for an existing project: +If a repository you're interested in is located on a different server, and you want +to browse its content and its activity using the GitLab interface, you can configure +mirror pulling: 1. If you [configured two-factor authentication (2FA)](https://docs.github.com/en/github/authenticating-to-github/securing-your-account-with-two-factor-authentication-2fa) for GitHub, create a [personal access token for GitHub](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) @@ -244,7 +248,7 @@ Because GitLab is now set to pull changes from the upstream repository, you shou directly to the repository on GitLab. Instead, any commits should be pushed to the remote repository. Changes pushed to the remote repository are pulled into the GitLab repository, either: -- Automatically within a certain period of time. +- Automatically in a certain period of time. - When a [forced update](#forcing-an-update) is initiated. WARNING: @@ -254,7 +258,7 @@ Deleted branches and tags in the upstream repository are not reflected in the Gi ### How it works -Once the pull mirroring feature has been enabled for a repository, the repository is added to a queue. +After the pull mirroring feature has been enabled for a repository, the repository is added to a queue. Once per minute, a Sidekiq cron job schedules repository mirrors to update, based on: @@ -556,7 +560,7 @@ Bidirectional mirroring should not be used as a permanent configuration. Refer t [Git Fusion](https://www.perforce.com/manuals/git-fusion/#Git-Fusion/section_avy_hyc_gl.html) provides a Git interface to [Perforce Helix](https://www.perforce.com/products) which can be used by GitLab to bidirectionally -mirror projects with GitLab. This may be useful in some situations when migrating from Perforce Helix +mirror projects with GitLab. This can help you in some situations when migrating from Perforce Helix to GitLab where overlapping Perforce Helix workspaces cannot be migrated simultaneously to GitLab. If using mirroring with Perforce Helix, you should only mirror protected branches. Perforce Helix |