리포지터리 미러링 문제 해결

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

미러링에 실패하면 프로젝트 유지보수자는 프로젝트 세부 정보 페이지에서 Pull 미러링이 1시간 전에 실패했습니다.과 비슷한 링크를 볼 수 있습니다. 이 링크를 선택하여 미러링 설정으로 바로 이동할 수 있으며, 여기서 GitLab은 미러링된 리포지터리에 대한 오류 배지를 표시합니다. 마우스 커서를 배지 위에 올려놓으면 오류의 텍스트가 표시됩니다:

호버하면 오류 메시지가 표시됩니다

GitHub으로 RST_STREAM 및 오류 코드 2를 수신하는 경우

GitHub 리포지터리로 미러링하는 동안이 메시지를 받은 경우:

13:Received RST_STREAM with error code 2

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

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

마감 시간 초과

GitLab을 업그레이드할 때 사용자 이름이 어떻게 나타나는지에 대한 변경으로 미러링 사용자 이름 및 암호를 업데이트하여 %40 문자가 @로 대체되도록해야 합니다.

연결이 차단됨: 서버는 공개 키 인증만 허용함

GitLab과 원격 리포지터리 간의 연결이 차단되었습니다. 심지어 TCP Check 이 성공하더라도 GitLab에서 원격 서버로의 경로에있는 네트워킹 컴포넌트를 확인해야 합니다.

이 오류는 방화벽이 나가는 패킷에 대해 심층 SSH 검사를 수행할 때 발생할 수 있습니다.

사용자 이름을 읽을 수 없음: 터미널 프롬프트가 비활성화됨

외부 리포지터리를 사용하여 새 프로젝트를 만든 후 이 오류를받은 경우:

  • Bitbucket Cloud의 경우:

    "2:fetch remote: "fatal: could not read Username for 'https://bitbucket.org':
    terminal prompts disabled\n": exit status 128."
    
  • Bitbucket Server (자체 호스팅):

    "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 (자체 호스팅)의 경우:

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

미러링에 사용되는 계정에 따라 클라우드 또는 자체 호스팅 Bitbucket 리포지터리에 대한 연결 시 리포지터리 소유자가 필요합니다.

Pull 미러가 LFS 파일을 누락시킵니다

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

  • SSH 리포지터리 URL을 사용하는 경우. 임시 방편은 HTTPS 리포지터리 URL을 대신 사용하는 것입니다. SSH URL에 대해 이 문제를 해결하기 위한 이슈가 존재합니다(https://gitlab.com/gitlab-org/gitlab/-/issues/11997).
  • 객체 리포지터리를 사용하여 외부 리포지터리를 미러링하는 경우. 이 문제를 해결하기 위한 이슈가 존재합니다(https://gitlab.com/gitlab-org/gitlab/-/issues/335495).

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

파이프라인이 실행되지 않을 수 있습니다:

  • 미러 업데이트를 위한 파이프라인 트리거 옵션이 활성화되어있지 않을 수 있습니다. 이 설정은 초기에 Pull 미러링 설정 시에만 활성화 할 수 있습니다. 프로젝트가 외부 리포지터리를 위한 CI/CD를 사용하여 미러링이 설정된 경우, 이 설정은 기본적으로 활성화되어 있습니다. 프로젝트 미러링이 매뉴얼으로 재구성될 경우, 파이프라인을 트리거하는 옵션이 기본적으로 꺼져있을 수 있으며, 이것이 파이프라인이 멈출 수 있는 이유일 수 있습니다.
  • rules 설정이 파이프라인에 임의 작업을 추가하는 것을 방지할 수 있습니다.
  • 파이프라인이 Pull 미러를 설정한 계정을 사용하여 트리거될 수 있습니다. 계정이 더 이상 유효하지 않으면 파이프라인이 실행되지 않을 수 있습니다.
  • 브랜치 보호 계정에게 미러 설정을 방해할 수 있습니다.

리포지터리가 업데이트 중입니다이지만 실패 혹은 성공이 명확하지 않음

드문 경우에는 Redis에서 미러링 슬롯이 고갈되어, 아웃-오브-메모리(OoM) 이벤트로 인해 Sidekiq 작업자가 중복으로 종료되면서 미러링 작업이 빠르게 시작되고 완료되지만 실패하거나 성공하지 않습니다. 또한 명확한 로그를 남기지 않습니다. 이 문제를 확인하려면:

  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. 명령을 실행한 후 백그라운드 작업 페이지에서 새로운 미러링 작업이 예정되어 있는지 확인할 수 있으며, 수동으로 트리거될 경우 특히 확인이 필요합니다.

잘못된 URL

SSH를 통해 미러링 설정 중에 이 오류를 받은 경우 URL이 올바른 형식인지 확인하십시오.

미러링은 git@gitlab.com:gitlab-org/gitlab.git와 같이 호스트와 프로젝트 경로를 :로 분리한 SCP와 유사한 클론 URL을 지원하지 않습니다. 대신 ssh:// 프로토콜을 포함한 표준 URL이 필요합니다. 예를 들면 ssh://git@gitlab.com/gitlab-org/gitlab.git입니다.

호스트 키 확인 실패

대상 호스트의 공개 SSH 키가 변경되면이 오류가 반환됩니다. 공개 SSH 키는 거의 또는 전혀 변경되지 않습니다. 호스트 키 확인이 실패하지만 여전히 키가 유효하다고 생각되면 키 정보를 새로 고칠 수 있습니다.

전제 조건:

  • 프로젝트를 유지자 역할 이상으로 가지고 있어야 합니다.

이 문제를 해결하려면:

  1. 호스트 키를 확인합니다.
  2. 왼쪽 사이드 바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  3. 설정 > 리포지터리를 선택합니다.
  4. 미러링 리포지터리를 확장합니다.
  5. 키를 새로 고치려면 다음 중 하나를 수행합니다:

    • GitLab이 서버에서 호스트 키를 가져와 fingerprint를 표시하도록 호스트 키 검색을 선택합니다.
    • 매뉴얼으로 호스트 키 입력을 선택하여 호스트 키를 SSH 호스트 키 필드에 입력합니다.
  • 리포지터리 미러링을 선택합니다.

단일 서비스 계정으로 미러 사용자 및 토큰 이전

이 작업에는 GitLab Rails console에 대한 액세스가 필요합니다.

사용 사례: 여러 사용자가 자체 GitHub 자격 증명을 사용하여 리포지터리 미러링을 설정하는 경우, 사람들이 회사를 떠나면 미러링이 중단됩니다. 이 스크립트를 사용하여 분산된 미러링 사용자 및 토큰을 단일 서비스 계정으로 이관합니다.

caution
데이터를 변경하는 명령은 올바르게 실행되지 않거나 올바른 조건에서 실행되지 않으면 손상을 일으킬 수 있습니다. 항상 먼저 테스트 환경에서 명령을 실행하고 복원할 수 있는 백업 인스턴스를 준비하세요.
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?('@')
               # Case 1: The url is something like https://23423432@project/path.git
               import_url.split('@').last
             elsif import_url.include?('//')
               # Case 2: The url is something like 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.

Geo 보조 노드로부터 GitLab 인스턴스로 미러 푸시 실패

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 프로토콜을 사용하도록 구성합니다. 그러나 리포지터리에는 항상 HTTP 또는 HTTPS를 통해 전송되는 LFS 객체가 포함되어 있어서는 안 됩니다.
  • 소스 인스턴스에서 모든 요청을 주 Geo 노드로 프록시하는 리버스 프록시를 사용합니다.
  • 소스에 대상 호스트 이름을 Geo 주 노드의 IP 주소로 해결하도록 로컬 hosts 파일 항목을 추가합니다.
  • 대신 대상에서 풀 미러를 구성합니다.