저장소 미러링 문제 해결

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

미러링이 실패하면 프로젝트 유지보수자는 프로젝트 세부 정보 페이지에 Pull 미러링이 1시간 전에 실패했습니다. 와 비슷한 링크를 볼 수 있습니다. 이 링크를 선택하여 미러링 설정으로 바로 이동할 수 있으며, GitLab이 미러링된 저장소에 대한 Error 배지를 표시합니다. 배지 위로 마우스 커서를 가져가면 오류 메시지가 표시됩니다:

호버링하면 표시되는 오류 메시지

Received RST_STREAM with error code 2 with GitHub

GitHub 저장소로 미러링하는 동안 이 메시지를 받는 경우: 

13:Received RST_STREAM with error code 2

다음 중 하나가 발생할 수 있습니다:

  1. 귀하의 GitHub 설정에서 커밋에 사용된 이메일 주소가 노출되는 푸시를 차단하도록 설정되어 있을 수 있습니다. 이 문제를 해결하려면 다음 중 하나를 수행하십시오:
  2. 귀하의 저장소가 GitHub의 100MB 파일 크기 제한을 초과할 수 있습니다. 이 문제를 해결하려면 GitHub에서 구성된 파일 크기 제한을 확인하고 클 대용량 파일을 관리하려면 Git Large File Storage를 사용하는 것을 고려하십시오.

Deadline Exceeded

GitLab을 업그레이드할 때 사용자 이름 표시 방식이 변경될 경우 미러링 사용자 이름과 암호를 업데이트하여 %40 문자가 @로 대체되도록 해야합니다.

Connection blocked because server only allows public key authentication

GitLab과 원격 저장소 간의 연결이 차단되었습니다. TCP Check 이 성공하더라도 GitLab에서 원격 서버로의 경로에서 네트워킹 구성 요소를 확인해야 합니다.

방화벽이 발신 패킷에 대해 Deep SSH Inspection을 수행하는 경우 이 오류가 발생할 수 있습니다.

Could not read username: terminal prompts disabled

GitLab CI/CD for external repositories를 사용하여 새 프로젝트를 만든 후 이 오류를 받은 경우:

  • Bitbucket Cloud에서: 

    "2:fetch remote: "fatal: could not read Username for 'https://bitbucket.org':
terminal prompts disabled\n": exit status 128."

  • Bitbucket Server(self-managed)에서: 

    "2:fetch remote: "fatal: could not read Username for 'https://lab.example.com':
terminal prompts disabled\n": exit status 128.

미러링된 저장소 URL에서 저장소 소유자가 지정되었는지 확인하십시오:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하여 프로젝트를 찾습니다.
  2. 설정 > 저장소를 선택합니다.
  3. 저장소 미러링을 확장합니다.

  4. 저장소 소유자가 지정되지 않은 경우 저장소 URL을 다음 형식으로 삭제하고 다시 추가합니다. 여기서 OWNER, ACCOUNTNAME, PATH_TO_REPO, REPONAME은 각각 해당하는 값으로 대체합니다:

    • Bitbucket Cloud에서: 

      https://OWNER@bitbucket.org/ACCOUNTNAME/REPONAME.git

    • Bitbucket Server(self-managed)에서: 

      https://OWNER@lab.example.com/PATH_TO_REPO/REPONAME.git

미러링을 위해 Cloud 또는 self-managed Bitbucket 저장소에 연결할 때 저장소 소유자가 필요합니다.

Pull mirror is missing LFS files

일부 경우에는 pull 미러링이 LFS 파일을 전송하지 않을 수 있습니다. 이 문제는 다음 상황에서 발생합니다:

  • SSH 저장소 URL을 사용하는 경우. 대신 HTTPS 저장소 URL을 사용하도록 해결합니다. SSH URL에 대한 이 문제를 해결하기 위한 이슈가 존재합니다.
  • GitLab 14.0 이하를 사용하고 소스 저장소가 공개 Bitbucket URL인 경우. GitLab 14.0.6에서 수정됨.
  • 객체 저장소를 사용하여 외부 저장소를 미러링하는 경우. 이 문제에 대한 이슈가 존재합니다.

Pull 미러링이 파이프라인을 트리거하지 않음

파이프라인이 실행되지 않는 이유는 여러 가지일 수 있습니다:

The repository is being updated, but neither fails nor succeeds visibly

드물게 Redis에서 미러링 슬롯이 고갈되는 경우가 있습니다. 이는 Sidekiq 워커가 메모리 부족(OoM) 이벤트로 제거되기 때문일 수 있습니다. 이 문제가 발생하면 미러링 작업이 빠르게 시작되고 완료되지만 실패하거나 성공하지 않습니다. 또한 명확한 로그를 남기지 않습니다. 이 문제를 확인하려면 다음을 수행하십시오.

  1. Rails 콘솔로 들어가 Redis의 미러링 용량을 확인하십시오. 

    current = Gitlab::Redis::SharedState.with { |redis| redis.scard('MIRROR_PULL_CAPACITY') }.to_i
maximum = Gitlab::CurrentSettings.mirror_max_capacity
available = maximum - current

  2. 미러링 용량이 0 또는 매우 낮은 경우 다음 명령어로 모든 지연된 작업을 처리할 수 있습니다. 

    Gitlab::Redis::SharedState.with { |redis| redis.smembers('MIRROR_PULL_CAPACITY') }.each do |pid|
  Gitlab::Redis::SharedState.with { |redis| redis.srem('MIRROR_PULL_CAPACITY', pid) }
end

  3. 명령을 실행한 후 백그라운드 작업 페이지에서 새로운 미러링 작업이 트리거되고 있는지 확인하십시오.

Invalid URL

미러링 설정 중 SSH를 사용할 때 이 오류를 받으신다면 URL이 올바른 형식인지 확인하십시오. 미러링은 SSH 클론 URL의 간소화된 버전인 git@gitlab.com:gitlab-org/gitlab.git를 지원하지 않으며, 프로토콜(ssh://git@gitlab.com/gitlab-org/gitlab.git)을 포함한 완전한 버전이 필요합니다. 호스트와 프로젝트 경로가 : 대신 /로 구분되었는지 확인하십시오.

Host key verification failed

이 오류는 대상 호스트의 공개 SSH 키가 변경될 때 반환됩니다. 공개 SSH 키는 거의, 대부분 변경되지 않습니다. 호스트 키 확인에 실패하지만 여전히 키가 유효하다고 판단되는 경우 키 정보를 새로고치할 수 있습니다.

전제 조건: - 프로젝트의 최소한 Maintainer 역할이 있어야 합니다.

이 문제를 해결하려면 다음을 수행하십시오:

  1. 호스트 키를 확인하십시오.
  2. 왼쪽 사이드바에서 검색 또는 이동을 선택하여 프로젝트를 찾으십시오.
  3. 설정 > 저장소를 선택하십시오.
  4. 저장소 미러링을 확장하십시오.

  5. 키를 다시 새로고치려면:

    • GitLab이 서버에서 호스트 키를 가져와 fingerprint를 표시하도록 호스트 키 감지를 선택하십시오.
    • 수동으로 호스트 키를 입력하려면 호스트 키 수동 입력을 선택하고 SSH 호스트 키 필드에 호스트 키를 입력하십시오.
  • 저장소 미러링을 선택하십시오.

Transfer mirror users and tokens to a single service account in Rails console

이 작업은 GitLab Rails 콘솔에 액세스해야 합니다.

사례: 여러 사용자가 자신의 GitHub 자격 증명을 사용하여 저장소 미러링을 설정하고, 사용자가 회사를 떠날 때 미러링이 중단되는 경우에 사용합니다. 아래 스크립트를 사용하여 분산된 미러링 사용자와 토큰을 단일 서비스 계정으로 이전합니다.

경고: 데이터를 변경하는 명령은 올바르게 실행되지 않거나 적절한 조건에서 실행되지 않으면 손상을 일으킬 수 있습니다. 항상 명령을 먼저 테스트 환경에서 실행하고 복원할 백업 인스턴스를 준비해 두어야 합니다. 

svc_user = User.find_by(username: 'ourServiceUser')
token = 'githubAccessToken'

Project.where(mirror: true).each do |project|
  import_url = project.import_url

  # 원하는 URL은 https://token@project/path.git 형식입니다
  repo_url = if import_url.include?('@')
               # 경우 1: URL은 https://23423432@project/path.git과 같은 형식입니다
               import_url.split('@').last
             elsif import_url.include?('//')
               # 경우 2: URL은 https://project/path.git과 같은 형식입니다
               import_url.split('//').last
             end

  next unless repo_url

  final_url = "https://#{token}@#{repo_url}"

  project.mirror_user = svc_user
  project.import_url = final_url
  project.username_only_import_url = final_url
  project.save
end

The requested URL returned error: 301

http:// 또는 https:// 프로토콜을 사용하여 미러링하는 경우, 저장소의 정확한 URL이 지정되었는지 확인하십시오: https://gitlab.example.com/group/project.git

HTTP 리디렉션이 따르지 않으며 .git을 생략하면 301 오류가 발생할 수 있습니다. 

13:fetch remote: "fatal: unable to access 'https://gitlab.com/group/project': The requested URL returned error: 301\n": exit status 128.

Push mirror from GitLab instance to Geo secondary fails: The requested URL returned error: 302

HTTP 또는 HTTPS 프로토콜을 사용하여 GitLab 저장소를 Geo 보조 노드로 푸시하는 경우, 푸시 요청을 Geo 기본 노드로 프록시하고 실패합니다. 이때 다음 오류가 표시됩니다. 

13:get remote references: create git ls-remote: exit status 128, stderr: "fatal: unable to access 'https://gitlab.example.com/group/destination.git/': The requested URL returned error: 302".

이 오류는 Geo 통합 URL이 구성되고 대상 호스트 이름이 보조 노드의 IP 주소로 해석될 때 발생합니다.

이 오류를 방지하는 방법:

  • 푸시 미러링을 SSH 프로토콜을 사용하도록 구성합니다. 그러나 저장소에 LFS(Large File Storage) 객체가 포함되어 있으면 항상 HTTP 또는 HTTPS로 전송되고 여전히 리디렉트됩니다.
  • 소스 인스턴스에서 모든 요청을 기본 Geo 노드로 전달하는 역방향 프록시를 사용합니다.
  • 소스에 대상 호스트 이름을 Geo 기본 노드의 IP 주소로 해석하도록 로컬 hosts 파일 항목을 추가합니다.
  • 대상에 풀 미러링을 구성합니다.