Skip to content

G
gitlab-ce
Commit 2265fc54 authored by Marcia Ramos's avatar Marcia Ramos
Browse files
Options

Merge branch 'docs/refactor-repository-mirroring-ee' into 'master' 

Port from CE - update repo mirroring documentation

See merge request gitlab-org/gitlab-ee!7790
parents 88ea34ed fb0d40a7
Show whitespace changes
Inline Side-by-side
Showing with 219 additions and 256 deletions
doc/workflow/repository_mirroring.md
View file @ 2265fc54
# Repository mirroring
Repository mirroring is a way to mirror repositories from external sources.
It can be used to mirror all branches, tags, and commits that you have
in your repository.
Repository mirroring allows for mirroring of repositories to and from external sources. It can be
used to mirror branches, tags, and commits between repositories.
Your mirror at GitLab will be updated automatically. You can
also manually trigger an update at most once every 5 minutes.
A repository mirror at GitLab will be updated automatically. You can also manually trigger an update
at most once every 5 minutes.
## Overview
Repository mirroring is very useful when, for some reason, you must use a
project from another source.
Repository mirroring is useful when you want to use a repository outside of GitLab.
There are two kinds of repository mirroring features supported by GitLab:
**push** and **pull**, the latter being only available in GitLab Enterprise Edition.
The **push** method mirrors the repository in GitLab to another location.
There are two kinds of repository mirroring supported by GitLab:
Once the mirror repository is updated, all new branches,
tags, and commits will be visible in the project's activity feed.
Users with at least [developer access][perms] to the project can also force an
immediate update with the click of a button. This button will not be available if
the mirror is already being updated or 5 minutes still haven't passed since its last update.
- Push: for mirroring a GitLab repository to another location.
- Pull: for mirroring a repository from another location to GitLab. **[STARTER]**
A few things/limitations to consider:
When the mirror repository is updated, all new branches, tags, and commits will be visible in the
project's activity feed.
- The repository must be accessible over `http://`, `https://`, `ssh://` or `git://`.
- If your HTTP repository is not publicly accessible, add authentication
information to the URL, like: `https://username@gitlab.company.com/group/project.git`.
In some cases, you might need to use a personal access token instead of a
password, e.g., you want to mirror to GitHub and have 2FA enabled.
- The import will time out after 15 minutes. For repositories that take longer
use a clone/push combination.
- The Git LFS objects will not be synced. You'll need to push/pull them
manually.
Users with at least [developer access](../user/permissions.md) to the project can also force an
immediate update, unless:
- The mirror is already being updated.
- 5 minutes haven't elapsed since its last update.
## Use cases
- 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 and branches will be available in your
GitLab instance.
- 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 GitLab repository can push its changes to the
old location.
The following are some possible use cases for repository mirroring:
## Pulling from a remote repository **[STARTER]**
- 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,
and branches will be available in your GitLab instance. **[STARTER]**
- 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
GitLab repository can push its changes to the old location.
>[Introduced][ee-51] in GitLab Enterprise Edition 8.2.
## Pushing to a remote repository **[CORE]**
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.
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/249) in GitLab Enterprise
> Edition 8.7. [Moved to GitLab Core](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/18715) in 10.8.
When creating a new project, you can enable repository mirroring when you choose
to import the repository from "Any repo by URL". Enter the full URL of the Git
repository to pull from and click on the **Mirror repository** checkbox.
For an existing project, you can set up push mirroring as follows:
![New project](repository_mirroring/repository_mirroring_new_project.png)
1. Navigate to your project's **Settings > Repository** and expand the **Mirroring repositories** section.
1. Enter a repository URL.
1. Select **Push** from the **Mirror direction** dropdown.
1. Select an authentication method from the **Authentication method** dropdown, if necessary.
1. Check the **Only mirror protected branches** box, if necessary.
1. Click the **Mirror repository** button to save the configuration.
For an existing project, you can set up mirror pulling by visiting your project's
**Settings ➔ Repository** and searching for the "Pull from a remote repository"
section. Check the "Mirror repository" box and hit **Save changes** at the bottom.
You have a few options to choose from one being the user who will be the author
of all events in the activity feed that are the result of an update. This user
needs to have at least [maintainer access][perms] to the project. Another option is
whether you want to trigger builds for mirror updates.
![Repository mirroring push settings screen](img/repository_mirroring_push_settings.png)
![Pull settings](repository_mirroring/repository_mirroring_pull_settings.png)
When push mirroring is enabled, only push commits directly to the mirrored repository to prevent the
mirror diverging. All changes will end up in the mirrored repository whenever:
Since the repository on GitLab functions as a mirror of the upstream repository,
you are advised not to push commits directly to the repository on GitLab.
Instead, any commits should be pushed to the upstream repository, and will end
up in the GitLab repository automatically within a certain period of time
or when a [forced update](#forcing-an-update) is initiated.
- Commits are pushed to GitLab.
- A [forced update](#forcing-an-update) is initiated.
If you do manually update a branch in the GitLab repository, the branch will
become diverged from upstream, and GitLab will no longer automatically update
this branch to prevent any changes from being lost.
Changes pushed to files in the repository are automatically pushed to the remote mirror at least:
![Diverged branch](repository_mirroring/repository_mirroring_diverged_branch.png)
- Within five minutes of being received.
- Within one minute if **Only mirror protected branches** is enabled.
### Trigger update using API **[STARTER]**
In the case of a diverged branch, you will see an error indicated at the **Mirroring repositories**
section.
>[Introduced][ee-3453] in GitLab Enterprise Edition 10.3.
### Push only protected branches **[CORE]**
Pull mirroring uses polling to detect new branches and commits added upstream,
often many minutes afterwards. If you notify GitLab by [API][pull-api], updates
will be pulled immediately.
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3350) in
> [GitLab Starter](https://about.gitlab.com/pricing/) 10.3. [Moved to GitLab Core](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/18715) in 10.8.
Read the [Pull Mirror Trigger API docs][pull-api].
You can choose to only push your protected branches from GitLab to your remote repository.
### Pull only protected branches **[STARTER]**
To use this option, check the **Only mirror protected branches** box when creating a repository
mirror.
>[Introduced][ee-3326] in GitLab Enterprise Edition 10.3.
## Setting up a push mirror from GitLab to GitHub **[CORE]**
You can choose to only pull the protected branches from your remote repository to GitLab.
To set up a mirror from GitLab to GitHub, you need to follow these steps:
To use this option go to your project's repository settings page under pull mirror.
1. Create a [GitHub personal access token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/) with the `public_repo` box checked.
1. Fill in the **Git repository URL** field, with the personal access token instead of a password.
For example: `https://<GitHubUsername>:<GitHubPersonalAccessToken>@github.com/group/project.git`.
1. Click the **Mirror repository** button.
1. Wait, or click the update button.
### Overwrite diverged branches **[STARTER]**
## Pulling from a remote repository **[STARTER]**
>[Introduced][ee-4559] in GitLab Enterprise Edition 10.6.
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/51) in GitLab Enterprise Edition 8.2.
You can choose to always update your local branch with the remote version even
if your local version has diverged from the remote.
You can set up a repository to automatically have its branches, tags, and commits updated from an
upstream repository.
To use this option go to your project's repository settings page under pull mirror.
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.
### Hard failure **[STARTER]**
To configure mirror pulling for an existing project:
1. Navigate to your project's **Settings > Repository** and expand the **Mirroring repositories**
section.
1. Enter a repository URL.
1. Select **Pull** from the **Mirror direction** dropdown.
1. Select an authentication method from the **Authentication method** dropdown, if necessary.
1. If necessary, check the following boxes:
- **Overwrite diverged branches**.
- **Trigger pipelines for mirror updates**.
- **Only mirror protected branches**.
1. Click the **Mirror repository** button to save the configuration.
>[Introduced][ee-3117] in GitLab Enterprise Edition 10.2.
![Repository mirroring pull settings screen - upper part](img/repository_mirroring_pull_settings_upper.png)
Once a mirror gets retried 14 times in a row, it will get marked as hard failed,
this will become visible in either the project main dashboard or in the
pull mirror settings page.
---
![Hard failed mirror main notice](repository_mirroring/repository_mirroring_hard_failed_main.png)
![Repository mirroring pull settings screen - lower part](img/repository_mirroring_pull_settings_lower.png)
![Hard failed mirror settings notice](repository_mirroring/repository_mirroring_hard_failed_settings.png)
Because GitLab is now set to pull changes from the upstream repository, you should not push commits
directly to the repository on GitLab. Instead, any commits should be pushed to the upstream repository.
Changes pushed to the upstream repository will be pulled into the GitLab repository, either:
When a project is hard failed, it will no longer get picked up for mirroring.
A user can resume the project mirroring again by either [forcing an update](#forcing-an-update)
or by changing the import URL in repository settings.
- Automatically within a certain period of time.
- When a [forced update](#forcing-an-update) is initiated.
CAUTION: **Caution:**
If you do manually update a branch in the GitLab repository, the branch will become diverged from
upstream and GitLab will no longer automatically update this branch to prevent any changes from being lost.
### How it works
Once you activate the pull mirroring feature, the mirror will be inserted into a queue. A scheduler
will start every minute and schedule a fixed number of mirrors for update, based on the configured maximum capacity.
If the mirror updates successfully, it will be enqueued once again with a small backoff period.
If the mirror fails (for example, a branch diverged from upstream), the project's backoff period is
increased each time it fails, up to a maximum amount of time.
### SSH authentication **[STARTER]**
> [Introduced][ee-2551] in GitLab Starter 9.5
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/2551) in [GitLab Starter](https://about.gitlab.com/pricing/) 9.5.
SSH authentication is mutual:
- You have to prove to the server that you're allowed to access the repository.
- The server also has to prove to *you* that it's who it claims to be.
You provide your credentials as a password or public key. The server that the source repository
resides on provides its credentials as a "host key", the fingerprint of which needs to be verified manually.
If you're mirroring over SSH (i.e., an `ssh://` URL), you can authenticate using
password-based authentication, just as over HTTPS, but you can also use public
key authentication. This is often more secure than password authentication,
especially when the source repository supports [Deploy Keys][deploy-key].
If you're mirroring over SSH (that is, using an `ssh://` URL), you can authenticate using:
To get started, navigate to **Settings ➔ Repository ➔ Pull from a remote repository**,
enable mirroring (if not already enabled) and enter an `ssh://` URL.
- Password-based authentication, just as over HTTPS.
- Public key authentication. This is often more secure than password authentication, especially when
the source repository supports [Deploy Keys](../ssh/README.md#deploy-keys).
> **NOTE**: SCP-style URLs, e.g., `git@example.com:group/project.git`, are not
supported at this time.
To get started:
Entering the URL adds two features to the page - `Fingerprints` and
`SSH public key authentication`:
1. Navigate to your project's **Settings > Repository** and expand the **Mirroring repositories** section.
1. Enter an `ssh://` URL for mirroring.
![Pull settings for SSH](repository_mirroring/repository_mirroring_pull_settings_for_ssh.png)
NOTE: **Note:**
SCP-style URLs (that is, `git@example.com:group/project.git`) are not supported at this time.
SSH authentication is mutual. You have to prove to the server that you're
allowed to access the repository, but the server also has to prove to *you* that
it's who it claims to be. You provide your credentials as a password or public
key. The server that the source repository resides on provides its credentials
as a "host key", the fingerprint of which needs to be verified manually.
Entering the URL adds two buttons to the page:
Press the `Detect host keys` button. GitLab will fetch the host keys from the
server, and display the fingerprints to you:
- **Detect host keys**.
- **Input host keys manually**.
![Detect SSH host keys](repository_mirroring/repository_mirroring_detect_host_keys.png)
If you click the:
- **Detect host keys** button, GitLab will fetch the host keys from the server and display the fingerprints.
- **Input host keys manually** button, a field is displayed where you can paste in host keys.
You now need to verify that the fingerprints are those you expect. GitLab.com
and other code hosting sites publish their fingerprints in the open for you
to check:
* [AWS CodeCommit](http://docs.aws.amazon.com/codecommit/latest/userguide/regions.html#regions-fingerprints)
* [Bitbucket](https://confluence.atlassian.com/bitbucket/use-the-ssh-protocol-with-bitbucket-cloud-221449711.html#UsetheSSHprotocolwithBitbucketCloud-KnownhostorBitbucket%27spublickeyfingerprints)
* [GitHub](https://help.github.com/articles/github-s-ssh-key-fingerprints/)
* [GitLab.com](https://about.gitlab.com/gitlab-com/settings/#ssh-host-keys-fingerprints)
* [Launchpad](https://help.launchpad.net/SSHFingerprints)
* [Savannah](http://savannah.gnu.org/maintenance/SshAccess/)
* [SourceForge](https://sourceforge.net/p/forge/documentation/SSH%20Key%20Fingerprints/)
- [AWS CodeCommit](http://docs.aws.amazon.com/codecommit/latest/userguide/regions.html#regions-fingerprints)
- [Bitbucket](https://confluence.atlassian.com/bitbucket/use-the-ssh-protocol-with-bitbucket-cloud-221449711.html#UsetheSSHprotocolwithBitbucketCloud-KnownhostorBitbucket%27spublickeyfingerprints)
- [GitHub](https://help.github.com/articles/github-s-ssh-key-fingerprints/)
- [GitLab.com](https://about.gitlab.com/gitlab-com/settings/#ssh-host-keys-fingerprints)
- [Launchpad](https://help.launchpad.net/SSHFingerprints)
- [Savannah](http://savannah.gnu.org/maintenance/SshAccess/)
- [SourceForge](https://sourceforge.net/p/forge/documentation/SSH%20Key%20Fingerprints/)
Other providers will vary. If you're running on-premises GitLab, or otherwise
Other providers will vary. If you're running self-managed GitLab, or otherwise
have access to the source server, you can securely gather the key fingerprints:
```
```sh
$ 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)
```
(You may need to exclude `-E md5` for some older versions of SSH).
If you're an SSH expert and already have a `known_hosts` file you'd like to use
unaltered, then you can skip these steps. Just press the "Show advanced" button
and paste in the file contents:
![Advanced SSH host key management](repository_mirroring/repository_mirroring_pull_advanced_host_keys.png)
Once you've **carefully verified** that all the fingerprints match your trusted
source, you can press `Save changes`. This will record the host keys, along with
the person who verified them (you!) and the date:
NOTE: **Note:**
You may need to exclude `-E md5` for some older versions of SSH.
![SSH host keys submitted](repository_mirroring/repository_mirroring_ssh_host_keys_verified.png)
When pulling changes from the source repository, GitLab will now check that at least one of the stored
host keys matches before connecting. This can prevent malicious code from being injected into your
mirror, or your password being stolen.
When pulling changes from the source repository, GitLab will now check that at
least one of the stored host keys matches before connecting. This can prevent
malicious code from being injected into your mirror, or your password being
stolen!
### SSH public key authentication
To use SSH public key authentication, you'll also need to choose that option
from the authentication methods dropdown. GitLab will generate a 4096-bit RSA
key and display the public component of that key to you:
To use SSH public key authentication, you'll also need to choose that option from the **Authentication method**
dropdown. GitLab will generate a 4096-bit RSA key and display the public component of that key to you.
![SSH public key authentication](repository_mirroring/repository_mirroring_ssh_public_key_authentication.png)
You then need to add the public SSH key to the source repository configuration. If:
You then need to add the public SSH key to the source repository configuration.
If the source is hosted on GitLab, you should add it as a [Deploy Key][deploy-key].
Other sources may require you to add the key to your user's `authorized_keys`
file - just paste the entire `ssh-rsa AAA.... user@host` block into the file on
its own line and save it.
- The source is hosted on GitLab, you should add the public SSH key as a [Deploy Key](../ssh/README.md#deploy-keys).
- The source is hosted elsewhere, you may need to 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.
Once the public key is set up on the source repository, press `Save changes` and your
mirror will begin working.
Once the public key is set up on the source repository, click the **Mirror repository** button and
your mirror will begin working.
If you need to change the key at any time, you can press the `Regenerate key`
button to do so. You'll have to update the source repository with the new key
to keep the mirror running.
If you need to change the key at any time, you can click the **Regenerate key** button to do so. You'll have to update the source repository with the new key to keep the mirror running.
### How it works
### Overwrite diverged branches **[STARTER]**
Once you activate the pull mirroring feature, the mirror will be inserted into
a queue. A scheduler will start every minute and schedule a fixed amount of
mirrors for update, based on the configured maximum capacity.
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/4559) in
> [GitLab Starter](https://about.gitlab.com/pricing/) 10.6.
If the mirror successfully updates it will be enqueued once again with a small
backoff period.
You can choose to always update your local branches with remote versions, even if they have
diverged from the remote.
If the mirror fails (eg: branch diverged from upstream), the project's backoff
period will be penalized each time it fails up to a maximum amount of time.
CAUTION: **Caution:**
For mirrored branches, enabling this option results in the loss of local changes.
## Pushing to a remote repository
To use this option, check the **Overwrite diverged branches** box when creating a repository mirror.
>[Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/249) in
GitLab Enterprise Edition 8.7. [Moved to GitLab Community Edition][ce-18715] in 10.8.
### Only mirror protected branches **[STARTER]**
For an existing project, you can set up push mirror from your project's
**Settings ➔ Repository** and searching for the "Push to a remote repository"
section. Check the "Remote mirror repository" box and fill in the Git URL of
the repository to push to. Click **Save changes** for the changes to take
effect.
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3326) in
> [GitLab Starter](https://about.gitlab.com/pricing/) 10.3.
![Push settings](repository_mirroring/repository_mirroring_push_settings.png)
You can choose to pull mirror only the protected branches from your remote repository to GitLab.
Non-protected branches are not mirrored and can diverge.
When push mirroring is enabled, you are advised not to push commits directly
to the mirrored repository to prevent the mirror diverging.
All changes will end up in the mirrored repository whenever commits
are pushed to GitLab, or when a [forced update](#forcing-an-update) is
initiated.
To use this option, check the **Only mirror protected branches** box when creating a repository mirror.
Pushes into GitLab are automatically pushed to the remote mirror at least once
every 5 minutes after they are received or once every minute if **push only
protected branches** is enabled.
### Hard failure **[STARTER]**
In case of a diverged branch, you will see an error indicated at the **Mirror
repository** settings.
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3117) in
> [GitLab Starter](https://about.gitlab.com/pricing/) 10.2.
![Diverged branch](
repository_mirroring/repository_mirroring_diverged_branch_push.png)
Once the mirroring process is unsuccessfully retried 14 times in a row, it will get marked as hard
failed. This will become visible in either the:
### Push only protected branches
- Project's main dashboard.
- Pull mirror settings page.
>[Introduced][ee-3350] in GitLab Enterprise Edition 10.3. [Moved to GitLab Community Edition][ce-18715] in 10.8.
When a project is hard failed, it will no longer get picked up for mirroring. A user can resume the
project mirroring again by [Forcing an update](#forcing-an-update).
You can choose to only push your protected branches from GitLab to your remote repository.
To use this option go to your project's repository settings page under push mirror.
### Trigger update using API **[STARTER]**
## Setting up a push mirror from GitLab to GitHub
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3453) in
[GitLab Starter](https://about.gitlab.com/pricing/) 10.3.
To set up a mirror from GitLab to GitHub, you need to follow these steps:
Pull mirroring uses polling to detect new branches and commits added upstream, often minutes
afterwards. If you notify GitLab by [API](https://docs.gitlab.com/ee/api/projects.html#start-the-pull-mirroring-process-for-a-project),
updates will be pulled immediately.
1. Create a [GitHub personal access token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/) with the "public_repo" box checked:
For more information, see [Start the pull mirroring process for a Project](https://docs.gitlab.com/ee/api/projects.html#start-the-pull-mirroring-process-for-a-project).
![edit personal access token GitHub](repository_mirroring/repository_mirroring_github_edit_personal_access_token.png)
## Forcing an update **[CORE]**
1. Fill in the "Git repository URL" with the personal access token replacing the password `https://GitHubUsername:GitHubPersonalAccessToken@github.com/group/project.git`:
While mirrors are scheduled to update automatically, you can always force an update by using the
update button which is available on the **Mirroring repositories** section of the **Repository Settings** page.
![push to remote repo](repository_mirroring/repository_mirroring_gitlab_push_to_a_remote_repository.png)
![Repository mirroring force update user interface](img/repository_mirroring_force_update.png)
1. Save
1. And either wait or trigger the "Update Now" button:
## Bidirectional mirroring **[STARTER]**
![update now](repository_mirroring/repository_mirroring_gitlab_push_to_a_remote_repository_update_now.png)
CAUTION: **Caution:**
Bidirectional mirroring may cause conflicts.
## Forcing an update
If you configure a GitLab repository to both pull from, and push to, the same remote source, there
is no guarantee that either repository will update correctly. If you set up a repository for
bidirectional mirroring, you should prepare for the likely conflicts by deciding who will resolve
them and how they will be resolved.
While mirrors are scheduled to update automatically, you can always force an update
by using the **Update now** button which is exposed in various places:
Rewriting any mirrored commit on either remote will cause conflicts and mirroring to fail. This can
be prevented by:
- in the commits page
- in the branches page
- in the tags page
- in the **Mirror repository** settings page
- [Pulling only protected branches](#pull-only-protected-branches).
- [Pushing only protected branches](#push-only-protected-branches).
## Bidirectional mirroring
You should [protect the branches](../user/project/protected_branches.md) you wish to mirror on both
remotes to prevent conflicts caused by rewriting history.
CAUTION: **Warning:**
There is no bidirectional support without conflicts. If you
configure a repository to pull and push to a second remote, there is no
guarantee that it will update correctly on both remotes. If you configure
a repository for bidirectional mirroring, you should consider when conflicts
occur who and how they will be resolved.
Rewriting any mirrored commit on either remote will cause conflicts and
mirroring to fail. This can be prevented by [only pulling protected branches](
#pull-only-protected-branches) and [only pushing protected branches](
#push-only-protected-branches). You should protect the branches you wish to
mirror on both remotes to prevent conflicts caused by rewriting history.
Bidirectional mirroring also creates a race condition where commits to the same
branch in close proximity will cause conflicts. The race condition can be
mitigated by reducing the mirroring delay by using a Push event webhook to
trigger an immediate pull to GitLab. Push mirroring from GitLab is rate limited
to once per minute when only push mirroring protected branches.
Bidirectional mirroring also creates a race condition where commits made close together to the same
branch causes conflicts. The race condition can be mitigated by reducing the mirroring delay by using
a [Push event webhook](../user/project/integrations/webhooks.md#push-events) to trigger an immediate
pull to GitLab. Push mirroring from GitLab is rate limited to once per minute when only push mirroring
protected branches.
### Preventing conflicts using a `pre-receive` hook
......@@ -322,12 +305,12 @@ to once per minute when only push mirroring protected branches.
A server-side `pre-receive` hook can be used to prevent the race condition
described above by only accepting the push after first pushing the commit to
the upstream Git repository. In this configuration one Git repository acts as
the authoritative upstream, and the other as downstream. The `pre-recieve` hook
the authoritative upstream, and the other as downstream. The `pre-receive` hook
will be installed on the downstream repository.
Read about [configuring custom Git hooks][hooks] on the GitLab server.
Read about [configuring custom Git hooks](../administration/custom_hooks.md) on the GitLab server.
A sample `pre-recieve` hook is provided below.
A sample `pre-receive` hook is provided below.
```bash
#!/usr/bin/env bash
......@@ -385,47 +368,27 @@ else
fi
```
### Mirroring with Perforce via GitFusion
### Mirroring with Perforce Helix via Git Fusion **[STARTER]**
CAUTION: **Warning:**
Bidirectional mirroring should not be used as a permanent
configuration. There is no bidirectional mirroring without conflicts.
Refer to [Migrating from Perforce Helix][perforce] for alternative migration
approaches.
GitFusion provides a Git interface to Perforce which can be used by GitLab to
bidirectionally mirror projects with GitLab. This may be useful in some
situations when migrating from Perforce to GitLab where overlapping Perforce
workspaces cannot be migrated simultaneously to GitLab.
If using mirroring with Perforce you should only mirror protected branches.
Perforce will reject any pushes that rewrite history. It is recommended that
only the fewest number of branches are mirrored due to the performance
limitations of GitFusion.
When configuring mirroring with Perforce via GitFusion, the following GitFusion
Bidirectional mirroring should not be used as a permanent configuration. Refer to
[Migrating from Perforce Helix](../user/project/import/perforce.md) for alternative migration approaches.
[Git Fusion](https://www.perforce.com/video-tutorials/git-fusion-overview) 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
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
will reject any pushes that rewrite history. Only the fewest number of branches should be mirrored
due to the performance limitations of Git Fusion.
When configuring mirroring with Perforce Helix via Git Fusion, the following Git Fusion
settings are recommended:
- `change-pusher` should be disabled, otherwise every commit will be rewritten
as being committed by the mirroring account, rather than being mapped to
existing Perforce users or the `unknown_git` user.
- `unknown_git` user will be used as the commit author if the GitLab user does
not exist in Perforce.
Read about [GitFusion settings on Perforce.com][gitfusion-settings].
[ee-51]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/51
[ee-2551]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/2551
[ee-3117]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3117
[ee-3326]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3326
[ee-3350]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3350
[ee-3453]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3453
[ee-4559]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/4559
[ce-18715]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/18715
[perms]: ../user/permissions.md
[hooks]: ../administration/custom_hooks.md
[deploy-key]: ../ssh/README.md#deploy-keys
[webhook]: ../user/project/integrations/webhooks.md#push-events
[pull-api]: ../api/projects.md#start-the-pull-mirroring-process-for-a-project
[perforce]: ../user/project/import/perforce.md
[gitfusion-settings]: https://www.perforce.com/perforce/doc.current/manuals/git-fusion/Content/Git-Fusion/section_zdp_zz1_3l.html
- `change-pusher` should be disabled. Otherwise, every commit will be rewritten as being committed
by the mirroring account, rather than being mapped to existing Perforce Helix users or the `unknown_git` user.
- `unknown_git` user will be used as the commit author if the GitLab user does not exist in
Perforce Helix.
Read about [Git Fusion settings on Perforce.com](https://www.perforce.com/perforce/doc.current/manuals/git-fusion/Content/Git-Fusion/section_zdp_zz1_3l.html).
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7