GitLab 인터페이스를 사용하면 GitLab에 호스팅되지 않은 리포지터리라도 그 콘텐츠와 활동을 탐색할 수 있습니다. 업스트림 리포지터리의 브랜치, 태그, 커밋을 내 리포지터리로 복사하려면 풀 미러를 만듭니다.

푸시 미러와 달리 풀 미러는 예약된 일정에 따라 업스트림(원격) 리포지터리에서 변경 사항을 가져옵니다. 미러가 업스트림 리포지터리와 어긋나지 않도록 다운스트림 미러에 직접 커밋을 푸시하지 않습니다. 대신 업스트림 리포지터리에 커밋을 푸시합니다. 원격 리포지터리의 변경 사항은 다음 경우에 GitLab 리포지터리로 가져옵니다.

• 이전 풀로부터 30분 후 자동으로 가져옵니다. 이 동작은 비활성화할 수 없습니다.
• 관리자가 미러를 강제로 업데이트할 때 가져옵니다.
• API 호출이 업데이트를 트리거할 때 가져옵니다.

UI 및 API 업데이트에는 기본 풀 미러링 간격 5분이 적용됩니다. 이 간격은 GitLab Self-Managed 인스턴스에서 구성할 수 있습니다.

기본적으로 다운스트림 풀 미러의 브랜치나 태그가 로컬 리포지터리와 어긋나면 GitLab은 해당 브랜치 업데이트를 중지합니다. 데이터 손실을 방지하기 위한 동작입니다. 업스트림 리포지터리에서 삭제된 브랜치와 태그는 다운스트림 리포지터리에 반영되지 않습니다.

풀 미러링 작동 방식#

GitLab 리포지터리를 풀 미러로 구성하면 다음 순서로 동작합니다.

1. GitLab 이 리포지터리를 대기열에 추가합니다.
2. 1분에 한 번 Sidekiq cron job 이 다음을 기준으로 업데이트할 리포지터리 미러를 예약합니다.
   • Sidekiq 설정으로 결정되는 가용 용량. GitLab.com의 경우 GitLab.com Sidekiq 설정을 참고합니다.
   • 이미 대기열에 있고 업데이트 시점이 된 미러의 수. 시점이 되었는지 여부는 리포지터리 미러가 마지막으로 업데이트된 시각과 업데이트 재시도 횟수에 따라 정해집니다.
3. Sidekiq 이 업데이트를 처리할 수 있게 되면 미러가 업데이트됩니다. 업데이트 프로세스가
   • 성공한 경우: 최소 30분 대기 후 업데이트가 다시 대기열에 등록됩니다.
   • 실패한 경우: 업데이트를 나중에 다시 시도합니다. 14회 실패하면 미러는 하드 실패로 표시되며 더 이상 업데이트 대기열에 등록되지 않습니다. 업스트림 브랜치와 어긋난 브랜치가 실패의 원인이 될 수 있습니다. 브랜치가 어긋나지 않도록 하려면 미러를 만들 때 어긋난 브랜치 덮어쓰기를 구성합니다.

풀 미러링 구성#

사전 요구 사항:

• 원격 리포지터리가 GitHub에 있고 2단계 인증(2FA)을 구성했다면 repo 범위로 GitHub 개인 액세스 토큰을 만듭니다. 2FA가 활성화되어 있으면 이 개인 액세스 토큰이 GitHub 비밀번호 역할을 합니다.
• GitLab 사일런트 모드가 활성화되어 있지 않아야 합니다.
• 업스트림 리포지터리와 GitLab 리포지터리가 동일한 객체 형식을 사용해야 합니다. SHA-1 리포지터리와 SHA-256 리포지터리 사이에서는 미러링할 수 없습니다.

1. 상단 표시줄에서 Search or go to를 선택하고 프로젝트를 찾습니다.

2. 왼쪽 사이드바에서 Settings > Repository를 선택합니다.

3. Mirroring repositories를 확장합니다.

4. Git repository URL을 입력합니다.

   [!note] gitlab 리포지터리를 미러링하려면 gitlab.com:gitlab-org/gitlab.git 또는 https://gitlab.com/gitlab-org/gitlab.git을 사용합니다.

5. Mirror direction에서 Pull을 선택합니다.

6. Authentication method에서 인증 방법을 선택합니다. 자세한 내용은 미러의 인증 방법을 참고합니다.

7. 필요한 옵션을 선택합니다.

   • Overwrite diverged branches
   • Trigger pipelines for mirror updates
   • Only mirror protected branches

8. 구성을 저장하려면 Mirror repository를 선택합니다.

어긋난 브랜치 덮어쓰기#

원격 버전과 어긋난 경우에도 로컬 브랜치를 항상 원격 버전으로 업데이트하려면 미러를 만들 때 Overwrite diverged branches를 선택합니다.

미러 업데이트 시 파이프라인 트리거#

원격 리포지터리가 브랜치나 태그를 업데이트할 때 파이프라인이 자동으로 트리거되도록 미러를 구성할 수 있습니다. 이 기능을 활성화하기 전에 다음을 확인합니다.

• CI 러너가 원격 리포지터리 활동으로 인한 추가 부하를 감당할 수 있는지 확인합니다.
• 파이프라인이 풀 미러링을 설정한 사용자의 자격 증명을 사용하므로 보안 위험을 고려합니다. 예를 들어 악의적인 Maintainer는 다음과 같은 행위를 할 수 있습니다.
  • 파이프라인 실행 시 저장된 CI/CD 변수 값을 가져오려 시도하는 업데이트를 원격 리포지터리에 반영합니다.
  • Allow Git push requests to the repository 설정이 활성화되어 있으면 미러된 프로젝트에 커밋을 푸시합니다.

SSO 적용 환경에서의 풀 미러링#

그룹에 SSO 적용이 활성화되어 있으면 미러를 만든 사용자가 활성 SSO 세션을 유지해야 하며, 그렇지 않으면 미러가 실패합니다.

SSO 세션에 의존하지 않고 미러링을 구성하려면 서비스 계정용 프로젝트 액세스 토큰, 그룹 액세스 토큰 또는 개인 액세스 토큰과 함께 풀 미러링 API를 사용할 수 있습니다.

API를 사용하여 업데이트 트리거#

풀 미러링은 폴링으로 업스트림에 추가된 새 브랜치와 커밋을 감지하며, 감지까지 몇 분이 걸리는 경우가 많습니다. API 호출로 GitLab에 알릴 수 있지만, 풀 미러링 최소 간격 제한은 그대로 적용됩니다.

자세한 내용은 프로젝트의 풀 미러링 프로세스 시작을 참고합니다.

미러링 시 하드 실패 수정#

재시도가 14회 연속으로 실패하면 미러링 프로세스가 하드 실패로 표시되고 미러링 시도가 중단됩니다. 이 실패는 다음 위치에서 확인할 수 있습니다.

• 프로젝트의 메인 대시보드
• 풀 미러 설정 페이지

프로젝트 미러링을 재개하려면 강제로 업데이트합니다.

장기간의 네트워크 또는 서버 장애 이후처럼 이 문제가 여러 프로젝트에 영향을 미치는 경우, Rails 콘솔에서 다음 명령으로 영향을 받은 모든 프로젝트를 확인하고 업데이트할 수 있습니다.

Project.find_each do |p|
  if p.import_state && p.import_state.retry_count >= 14
    puts "Resetting mirroring operation for #{p.full_path}"
    p.import_state.reset_retry_count
    p.import_state.set_next_execution_to_now(prioritized: true)
    p.import_state.save!
  end
end

관련 주제#

• 리포지터리 미러링 문제 해결
• 풀 미러링 간격
• 프로젝트 풀 미러링 API