@@ -266,7 +266,7 @@ Set the limit to `0` to disable it.
...
@@ -266,7 +266,7 @@ Set the limit to `0` to disable it.
The [minimum wait time between pull refreshes](../user/project/repository/mirror/index.md)
The [minimum wait time between pull refreshes](../user/project/repository/mirror/index.md)
defaults to 300 seconds (5 minutes). For example, by default a pull refresh will only run once in a given 300 second period regardless of how many times you try to trigger it.
defaults to 300 seconds (5 minutes). For example, by default a pull refresh will only run once in a given 300 second period regardless of how many times you try to trigger it.
This setting applies in the context of pull refreshes invoked via the [projects API](../api/projects.md#start-the-pull-mirroring-process-for-a-project), or when forcing an update by selecting the **Update now** (**{retry}**) button within **Settings > Repository > Mirroring repositories**. This setting has no effect on the automatic 30 minute interval schedule used by Sidekiq for [pull mirroring](../user/project/repository/mirror/pull.md#how-it-works).
This setting applies in the context of pull refreshes invoked via the [projects API](../api/projects.md#start-the-pull-mirroring-process-for-a-project), or when forcing an update by selecting the **Update now** (**{retry}**) button within **Settings > Repository > Mirroring repositories**. This setting has no effect on the automatic 30 minute interval schedule used by Sidekiq for [pull mirroring](../user/project/repository/mirror/pull.md).
To change this limit for a self-managed installation, run the following in the
To change this limit for a self-managed installation, run the following in the
create a [personal access token for GitHub](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token).
- When an administrator [force-updates the mirror](index.md#force-an-update).
with the `repo` scope. If 2FA is enabled, this personal access
- When an [API call triggers an update](#trigger-an-update-by-using-the-api).
token serves as your GitHub password.
1. In your project, go to **Settings > Repository**, and then expand the
**Mirroring repositories** section.
1. In the **Git repository URL** field, enter a repository URL. Include the username
in the URL if required: `https://MYUSERNAME@github.com/group/PROJECTNAME.git`
1. In the **Mirror direction** dropdown, select **Pull**.
1. In the **Authentication method** dropdown, select your authentication method.
1. Select from the following checkboxes, if needed:
-**Overwrite diverged branches**
-**Trigger pipelines for mirror updates**
-**Only mirror protected branches**
1. Select **Mirror repository** to save the configuration.
Because GitLab is now set to pull changes from the upstream repository, you should not push commits
By default, if any branch or tag on the downstream pull mirror diverges from the
directly to the repository on GitLab. Instead, any commits should be pushed to the remote repository.
local repository, GitLab stops updating the branch. This prevents data loss.
Changes pushed to the remote repository are pulled into the GitLab repository, either:
Deleted branches and tags in the upstream repository are not reflected in the
downstream repository.
- Automatically in a certain period of time.
## How pull mirroring works
- When a [forced update](index.md#force-an-update) is initiated.
WARNING:
After you configure a GitLab repository as a pull mirror:
If you do manually update a branch in the GitLab repository, the branch becomes diverged from
upstream, and GitLab no longer automatically updates this branch to prevent any changes from being lost.
Deleted branches and tags in the upstream repository are not reflected in the GitLab repository.
## How it works
1. GitLab adds the repository to a queue.
1. Once per minute, a Sidekiq cron job schedules repository mirrors to update, based on:
- Available capacity, determined by Sidekiq settings. For GitLab.com, read
- How many mirrors are already in the queue and due for updates. Being due depends
on when the repository mirror was last updated, and how many times updates have been retried.
1. Sidekiq becomes available to process updates, mirrors are updated. If the update process:
-**Succeeds**: An update is enqueued again with at least a 30 minute wait.
-**Fails**: The update is attempted again later. After 14 failures, a mirror is marked as a
[hard failure](#hard-failure) and is no longer enqueued for updates. A branch diverging
from its upstream counterpart can cause failures. To prevent branches from
diverging, configure [Overwrite diverged branches](#overwrite-diverged-branches) when
you create your mirror.
After the pull mirroring feature has been enabled for a repository, the repository is added to a queue.
## Configure pull mirroring
Once per minute, a Sidekiq cron job schedules repository mirrors to update, based on:
Prerequisite:
- The capacity available. This is determined by Sidekiq settings. For GitLab.com, see [GitLab.com Sidekiq settings](../../../gitlab_com/index.md#sidekiq).
- If your remote repository is on GitHub and you have
- The number of repository mirrors already in the queue that are due to be updated. Being due depends on when the repository mirror was last updated and how many times it's been retried.
create a [personal access token for GitHub](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token)
Repository mirrors are updated as Sidekiq becomes available to process them. If the process of updating the repository mirror:
with the `repo` scope. If 2FA is enabled, this personal access
token serves as your GitHub password.
-**Succeeds**: An update is enqueued again with at least a 30 minute wait.
1. On the top bar, select **Menu > Projects** and find your project.
-**Fails**: (For example, a branch diverged from upstream.), The update attempted again later. Mirrors can fail
1. On the left sidebar, select **Settings > Repository**.
up to 14 times before they are no longer enqueued for updates.
1. Expand **Mirroring repositories**.
1. Enter the **Git repository URL**. Include the username
in the URL, if required: `https://MYUSERNAME@github.com/GROUPNAME/PROJECTNAME.git`
1. In **Mirror direction**, select **Pull**.
1. In **Authentication method**, select your authentication method.
[Start the pull mirroring process for a project](../../../../api/projects.md#start-the-pull-mirroring-process-for-a-project).
## Hard failure
## Hard failure
> Moved to GitLab Premium in 13.9.
> Moved to GitLab Premium in 13.9.
...
@@ -95,12 +114,8 @@ and mirroring attempts stop. This failure is visible in either the:
...
@@ -95,12 +114,8 @@ and mirroring attempts stop. This failure is visible in either the:
You can resume the project mirroring again by [forcing an update](index.md#force-an-update).
You can resume the project mirroring again by [forcing an update](index.md#force-an-update).
## Trigger an update using the API
## Related topics
> Moved to GitLab Premium in 13.9.
Pull mirroring uses polling to detect new branches and commits added upstream, often minutes
afterwards. If you notify GitLab by [API](../../../../api/projects.md#start-the-pull-mirroring-process-for-a-project),
updates are pulled immediately.
For more information, see [Start the pull mirroring process for a Project](../../../../api/projects.md#start-the-pull-mirroring-process-for-a-project).
