To configure repository mirroring, on the project page, go to “Settings” → “Repository” → “Mirroring repositories”.

If the repository is empty, import it first. All hooks are triggered during mirroring, and pulling a large repository may significantly impact system performance.

Configuring pull mirroring of a repository

Only one pull mirroring task can be configured per project. Multiple push mirroring tasks are allowed.

To configure pull mirroring of a repository, follow these steps:

  1. Go to the project page:

    • Open your project in the Deckhouse Code interface.
    • In the left-hand menu, select “Settings” → “Repository”.
    • Scroll down to the “Mirroring repositories” section.

  2. Specify the repository URL. Credentials in the URL are ignored. Use the fields in the “Authentication method” block below for authorization.

  3. Configure authentication:

    • If using HTTP(S) access, in the “Authentication method” field, select “Username and password” and enter:
      • “Username”: Your username.
      • “Password”: Your password or access token.
    • If using SSH mirroring, specify the username (typically git). After saving the configuration, Deckhouse Code will generate an SSH key to be used for access.

Branch filter

The “Branch filter” block in the mirroring settings defines which branches are pulled from the source repository:

  • “Mirror all branches”: All branches of the source repository are mirrored.
  • “Mirror only protected branches”: Only the branches protected in this project are mirrored. The option is unavailable until the project has at least one protected branch (protected branches of the parent group are taken into account as well). For more information, see Protected branches.
  • “Mirror matching branches”: Only the branches whose names match the specified regular expression (RE2 syntax) are mirrored. The expression is matched against the whole branch name. While you are typing the expression, the form shows how many branches of this repository match it.

How the branch filter affects tag synchronization

The branch filter applies to tags as well. If “Mirror only protected branches” or “Mirror matching branches” is selected, a tag of the source repository is synchronized only if its commit is present in one of the branches of this repository. All other tags are skipped.

Consider the following specifics:

  • With “Mirror all branches”, all tags of the source repository are synchronized.
  • A tag skipped because of the filter is not lost: it is re-checked during every synchronization, and as soon as its commit reaches one of the mirrored branches, the tag is created in the mirror.
  • The check is performed against all branches of the mirror repository, including branches created directly in Deckhouse Code, and not only against the branches that match the filter.
  • Tags that have already been synchronized remain in the repository even if the branch filter is changed later so that it no longer covers them.

Importing a repository by URL as a pull mirror

You can set up pull mirroring while importing a repository by URL, so that the project is created and immediately configured as a pull mirror of the source repository. This way, you do not need to configure mirroring separately after the import.

Repository mirroring must be enabled for the instance by an administrator. In the “Admin area”, go to “Settings” → “Repository” → “Repository mirroring” (the mirror_available setting). If mirroring is not enabled for the instance, the “Mirror repository” checkbox is shown but disabled (grayed out) and cannot be selected.

To import a repository by URL as a pull mirror, follow these steps:

  1. Create a new project:

    • Go to “New project” → “Import project” → “Repository by URL”.
    • Specify the URL of the source repository.
    • If the source repository requires authentication, provide the credentials used to access it.

  2. Select the “Mirror repository” checkbox.

  3. Create the project.

During the initial import, the repository is created and populated from the source. After that, the project is kept in sync with the source repository automatically, on the pull mirroring schedule (for more information, see the “Scheduling and error handling” section below).

To restrict mirroring to protected branches or to branches matching a pattern, configure the branch filter after the import on the project’s “Settings” → “Repository” → “Mirroring repositories” page (for more information, see the “Branch filter” section above).

You can also turn an existing project into a pull mirror by running an import by URL into it; this requires the Maintainer role. In either case, mirroring runs on behalf of the user who configured it.

Scheduling and error handling

  • Pull mirroring tasks are scheduled once per hour (Projects::PullMirrorScheduleWorker).
  • Each mirror is updated no more than once every 6 hours.
  • If a mirroring task fails, the next attempt will be during the next run of Projects::PullMirrorScheduleWorker. The maximum number of retry attempts is 5. Clicking “Update now” resets the failure counter.
  • If a Sidekiq task terminates unexpectedly (for example, due to a Sidekiq restart), its status is updated after 3 hours, and a new synchronization attempt is scheduled.

LFS (Large File Storage) specifics

When using pull mirroring, LFS objects are fetched only if LFS is enabled in the target Deckhouse Code project.

←
User guide / API
User guide / Approval rules
→