저장소 미러링 문제 해결

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

미러링이 실패하면 프로젝트 유지 관리자는 프로젝트 세부정보 페이지에서 미러링 실패 1시간 전.과 유사한 링크를 볼 수 있습니다.
이 링크를 선택하여 미러링 설정으로 직접 이동하며, 여기서 GitLab은 미러링된 저장소에 대한 오류 배지를 표시합니다. 배지 위에 마우스를 올리면 오류 텍스트가 표시됩니다:

오류 메시지

GitHub에서 오류 코드 2로 RST_STREAM 수신

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에서 원격 서버로의 경로에 있는 모든 네트워킹 구성 요소에서 차단 여부를 확인해야 합니다.

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

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

외부 저장소를 위한 GitLab CI/CD를 사용하여 새 프로젝트를 만든 후 이 오류가 발생하면:

  • 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

Cloud 또는 셀프 관리 Bitbucket 저장소에 미러링을 위해 연결할 때는 저장소 소유자가 문자열에 필요합니다.

풀 미러에서 LFS 파일이 누락되었습니다

일부 경우, 풀 미러링이 LFS 파일을 전송하지 않습니다. 이 문제는 다음과 같은 경우에 발생합니다:

풀 미러링이 파이프라인을 트리거하지 않습니다

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

저장소가 업데이트되고 있습니다, 그러나 눈에 띄게 실패하거나 성공하지 않습니다

드물게, 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. 명령어를 실행한 후, 백그라운드 작업 페이지에서
    새로운 미러링 작업이 예약되고 있는 것을 확인해야 합니다, 특히 수동으로 트리거할 때.

잘못된 URL

SSH를 통해 미러링을 설정하는 동안 이 오류가 발생하면,
URL이 유효한 형식인지 확인하십시오.

미러링은 git@gitlab.com:gitlab-org/gitlab.git 형식의 SCP-like 클론 URL을 지원하지 않습니다.
호스트와 프로젝트 경로가 :로 구분됩니다.
ssh:// 프로토콜이 포함된 표준 URL이 필요합니다,
예: ssh://git@gitlab.com/gitlab-org/gitlab.git.

호스트 키 검증 실패

타겟 호스트의 공개 SSH 키가 변경되었을 때 이 오류가 반환됩니다.

공개 SSH 키는 드물게 변합니다. 호스트 키 검증에 실패했지만, 키가 여전히 유효하다고 의심되는 경우, 키의 정보를 새로 고칠 수 있습니다.

사전 조건:

  • 프로젝트에 대해 최소한 Maintainer 역할을 가져야 합니다.

문제를 해결하려면:

  1. 호스트 키 확인하기.
  2. 왼쪽 사이드바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
  3. Settings > Repository를 선택합니다.
  4. Mirroring repositories를 확장합니다.

  5. 키를 새로 고치려면 다음 중 하나를 선택합니다:

    • Detect host keys를 선택하여 GitLab이 서버에서 호스트 키를 가져오고 지문을 표시하도록 합니다.
    • Input host keys manually를 선택하고, SSH host key 필드에 호스트 키를 입력합니다.
  • Mirror repository를 선택합니다.

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

이 작업은 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?('@')
               # Case 1: url이 https://23423432@project/path.git와 같은 경우
               import_url.split('@').last
             elsif import_url.include?('//')
               # Case 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

요청된 URL이 오류를 반환했습니다: 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.

GitLab 인스턴스에서 Geo 보조로 푸시 미러가 실패합니다

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 객체가 포함되어 있지 않아야 하며, LFS 객체는 항상 HTTP 또는 HTTPS를 통해 전송되며 여전히 리다이렉트됩니다.
  • 리버스 프록시를 사용하여 소스 인스턴스의 모든 요청을 기본 Geo 노드로 전달합니다.
  • 소스의 로컬 hosts 파일 항목을 추가하여 타겟 호스트 이름이 Geo 기본 노드의 IP 주소로 해석되도록 강제합니다.
  • 대신 타겟에서 풀 미러를 구성합니다.

미러링 오류: 프로젝트가 미러링되지 않음

Pull 및 push 미러는 GitLab Silent Mode가 활성화되어 있을 때 업데이트하지 못합니다.

이럴 경우 UI에서 미러링을 허용하는 옵션이 비활성화됩니다.

관리자는 GitLab Silent Mode가 비활성화되어 있는지 확인할 수 있습니다.

Silent Mode로 인해 미러링이 실패할 경우, 다음의 디버그 단계가 필요합니다:

예를 들어, Silent Mode가 귀하의 가져오기를 방해하는 경우, 출력은 다음과 유사합니다:

"id": 1,
"update_status": "finished",
"url": "https://test.git"
"last_error": null,
"last_update_at": null,
"last_update_started_at": "2023-12-12T00:01:02.222Z",
"last_successful_update_at": null

초기 미러링 실패: 미러 리포를 가져올 수 없음: 팩 인덱스를 가져올 수 없음

다음과 유사한 오류가 발생할 수 있습니다:

13:fetch remote: "error: Unable to open local file /var/opt/gitlab/git-data/repositories/+gitaly/tmp/quarantine-[OMITTED].idx.temp.temp\nerror: Unable to get pack index https://git.example.org/ebtables/objects/pack/pack-[OMITTED].idx\nerror: Unable to find fcde2b2edba56bf408601fb721fe9b5c338d10ee under https://git.example.org/ebtables
필요한 객체 fcde2b2edba56bf408601fb721fe9b5c338d10ee를 가져올 수 없습니다
커밋 2c26b46b68ffc68ff99b453c1d30413413422d70을 처리하는 중입니다.
오류: 가져오기에 실패했습니다.\n": exit status 128.

이 문제는 Gitaly에서 “덜 똑똑한” HTTP 프로토콜을 통해 미러링 또는 리포지토리를 가져오는 것을 지원하지 않기 때문에 발생합니다.

서버가 “스마트”인지 “덜 스마트”인지 확인하려면 cURL을 사용하여 git-upload-pack 서비스의 참조 발견을 시작하고 Git “스마트” 클라이언트를 에뮬레이트하십시오:

$GIT_URL="https://git.example.org/project"
curl --silent --dump-header - "$GIT_URL/info/refs?service=git-upload-pack"\
  -o /dev/null | grep -Ei "$content-type:"
  • “스마트” 서버는 Content-Type 응답 헤더에 application/x-git-upload-pack-advertisement을 보고합니다.
  • “덜 스마트” 서버는 Content-Type 응답 헤더에 text/plain을 보고합니다.

자세한 내용은 참조 발견에 대한 Git 문서를 참조하십시오.

이를 해결하기 위해서는 다음 중 하나를 수행할 수 있습니다:

  • 소스 리포지토리를 “스마트” 서버로 마이그레이션 합니다.
  • SSH 프로토콜을 사용하여 리포지토리를 미러링합니다(인증 필요).