GitHub Enterprise Importer를 사용하여 마이그레이션 문제 해결

마이그레이션이 실패하거나 예기치 않은 결과가 발생하는 경우 일반적인 문제 해결 단계를 시도할 수 있습니다.

이 문서의 내용

GitHub Enterprise Importer에 대한 문제 해결 단계 정보

마이그레이션이 실패하거나 예기치 않은 결과가 발생하는 경우 아래 문제를 해결하기 위한 첫 번째 단계를 시도합니다. 이 단계는 일반적으로 다양한 문제를 해결합니다. 이러한 첫 번째 단계가 문제를 해결하지 못하는 경우 마이그레이션 로그에 오류 메시지를 검사합니다. 그런 다음 이 문서에서 오류 메시지를 찾아 해결 단계를 시도합니다.

오류 메시지의 문제 해결 단계를 시도한 후 문제를 해결할 수 없는 경우 GitHub 지원에 문의할 수 있습니다.

첫 번째 문제 해결 단계

자세히 조사하기 전에 일반적으로 다양한 문제를 해결하는 이러한 문제 해결 단계를 시도해 보세요.

  1. 마이그레이션하는 데 사용 중인 최신 버전의 GitHub CLI 확장을 사용하고 있는지 확인합니다. 사용하고 있지 않다면 최신 버전으로 업그레이드합니다.

  2. 모든 액세스 요구 사항이 충족되었는지 확인합니다. 자세한 내용은 마이그레이션 경로에 대한 해당 문서를 참조하세요.

  3. 마이그레이션을 다시 실행해 보세요. 일부 마이그레이션 문제는 일시적이며 두 번째 시도가 작동할 수 있습니다.

  4. 비슷한 데이터가 있는 다른 리포지토리에서 마이그레이션을 실행해 보세요. 이렇게 하면 문제가 리포지토리에 고유한지, 또는 더 광범위한 데이터 셰이프 문제를 나타내는지 확인하는 데 도움이 됩니다.

이러한 단계를 수행해도 문제가 해결되지 않으면 마이그레이션 로그에서 오류 메시지를 검토합니다. 검사가 필요한 로그는 마이그레이션이 실패했는지 또는 성공했는지에 따라 달라집니다.

실패한 마이그레이션 문제 해결

마이그레이션이 실패하면 각 마이그레이션에 대해 GitHub CLI에 따라 생성된 자세한 로그 항목을 검토합니다. 로그 파일은 마이그레이션을 실행한 것과 동일한 디렉터리에 저장됩니다.

로그에는 실행한 각 명령의 레코드와 GitHub CLI이(가) 응답에서 만든 모든 API 요청이 포함됩니다. 오류 및 오류 메시지는 일반적으로 로그의 끝 부분에 나타납니다.

마이그레이션을 실행할 수 없음

No access to createMigrationMutation 또는 Missing permissions와(과) 같은 오류가 표시되면 개인 계정애 마이그레이션을 실행하는 데 필요한 액세스 권한이 없습니다. 조직 소유자 또는 마이그레이션자 역할이 부여되었는지 확인합니다. 마이그레이션자 역할 부여에 대한 자세한 내용은 GitHub Enterprise Importer 정보을(를) 참조하세요.

Note

GitHub 제품 간에 마이그레이션하는 경우 조직 소유자이거나 원본 및 대상 조직 모두에 대한 마이그레이터 역할이 부여되었는지 확인하세요.

리소스는 조직 SAML 규약에 따라 보호됩니다

이 오류는 { GitHub CLI에 제공한 personal access token에 SAML Single Sign-On에 사용할 권한을 부여해야 했음을 나타냅니다. 자세한 내용은 SAML Single Sign-On에 사용할 개인용 액세스 토큰 권한 부여을(를) 참조하세요.

401 Unauthorized 응답

401 상태 코드가 포함된 오류는 일반적으로 GitHub CLI에 제공한 personal access token에 필요한 범위가 없음을 나타냅니다. 제공한 personal access token의 범위를 확인합니다. 필수 범위에 대한 자세한 내용은 마이그레이션 경로에 대한 해당 문서를 참조하세요.

404 Not Found 응답

404 상태 코드가 포함된 오류는 일반적으로 명령 중 하나에 오타가 있음을 나타냅니다. 입력한 정확한 명령에 대한 마이그레이션 로그를 검토하고 원본 리포지토리, 조직 또는 프로젝트에 있는 오타에 대해 검사합니다.

Archive generation failed 응답

GitHub Enterprise Server에서 마이그레이션할 때 Archive generation failed... 응답을 받으면 리포지토리가 너무 클 수 있습니다. 리포지토리 크기 제한에 대한 자세한 내용은 GitHub 제품 간 마이그레이션 정보을(를) 참조하세요.

먼저 migrate-repo 명령과 함께 --skip-releases 플래그를 사용하여 마이그레이션에서 릴리스를 제외해 보세요.

작동하지 않는 경우 GitHub Enterprise Server 3.8.0 이상으로 업그레이드하는 것이 좋습니다. 업그레이드할 수 없는 경우 다른 옵션은 ghe-migrator을(를) 사용하여 리포지토리 보관 파일을 수동으로 생성하는 것입니다.

  1. 리포지토리에 대한 마이그레이션 보관 파일을 생성합니다. 한 번에 하나의 리포지토리만 내보내야 합니다. 지침은 GitHub Enterprise Server 설명서의 "엔터프라이즈에서 마이그레이션 데이터 내보내기"를 참조하세요.
  2. 선택한 Blob 스토리지 공급자에 마이그레이션 보관 파일을 업로드합니다.
  3. AWS S3 미리 서명된 URL 또는 Azure Blob Storage SAS URL과 같이 GitHub에 액세스할 수 있는 마이그레이션 보관 파일의 단기 URL을 생성합니다.
  4. 이전 단계에서 보관 파일의 URL로 모두 설정된 --git-archive-url 및 --metadata-archive-url 플래그와 함께 migrate-repo 명령을 호출합니다.

cipher name is not supported 오류

Bitbucket Server에서 마이그레이션하고 마이그레이션을 실행할 때 cipher name aes256-ctr for openssh key file is not supported와(과) 같은 오류가 발생하는 경우 SSH 프라이빗 키는 지원되지 않는 암호화를 사용합니다. 지원되는 암호에 대한 자세한 내용은 Bitbucket 서버에서 마이그레이션에 대한 액세스 관리을(를) 참조하세요.

호환 가능한 새 SSH를 생성하려면 다음 명령을 실행하세요.

Shell
ssh-keygen -t ed25519 -Z aes256-cbc -C "your_email@example.com"

새 SSH 키페어를 생성한 후 키를 사용하기 전에 Bitbucket Server 인스턴스의 authorized_keys에 공개 키를 추가해야 합니다.

Subsystem 'sftp' could not be executed 오류

Bitbucket Server에서 마이그레이션하는 중 Subsystem 'sftp' could not be executed와(과) 같은 오류가 발생하는 경우 서버에서 SFTP를 사용하도록 설정되지 않았거나 사용자 계정에 SFTP 액세스 권한이 없습니다.

서버 관리자에게 문의하여 사용자 계정에 대한 SFTP 액세스를 사용하도록 요청해야 합니다.

Source export archive... does not exist 오류

Bitbucket Server에서 마이그레이션하는 중 Source export archive (/var/atlassian/application-data/bitbucket/shared/migration/export/Bitbucket_export_1.tar) does not exist와(과) 같은 오류가 발생하는 경우 GitHub CLI은(는) Bitbucket Server 인스턴스의 잘못된 위치에서 마이그레이션 보관 파일을 찾고 있습니다.

이 문제를 해결하려면 gh bbs2gh migrate-repo에 대한 --bbs-shared-home 인수를 Bitbucket Server 또는 데이터 센터의 공유 홈 디렉터리로 설정합니다. 기본 공유 홈 디렉터리가 /var/atlassian/application-data/bitbucket/shared이지만 구성이 다를 수 있습니다.

Bitbucket Server에서 공유 홈 디렉터리를 식별할 수 있습니다.

  1. Bitbucket Server 또는 데이터 센터 인스턴스의 관리 영역으로 이동합니다.
  2. 사이드바의 "시스템"에서 스토리지를 클릭합니다.
  3. "공유 디렉터리"에서 서버의 공유 홈 디렉터리 위치를 확인합니다.

여러 노트가 있는 클러스터 모드에서 Bitbucket 데이터 센터를 실행하는 경우 공유 디렉터리가 클러스터 노드 간에 공유되며 각 노드의 동일한 위치에 탑재되어야 합니다.

Repository rule violations found 오류

GH013: Repository rule violations found for refs/heads/main와(과) 같은 Repository rule violations found 오류가 발생하면 원본 리포지토리의 데이터가 대상 조직에 구성된 규칙 집합과 충돌합니다. 자세한 내용은 규칙 세트 정보을(를) 참조하세요.

마이그레이션 중에 규칙 집합을 일시적으로 사용하지 않도록 설정하거나 바이패스 모드 또는 바이패스 목록을 사용하여 구성된 규칙에서 마이그레이션을 제외할 수 있습니다. 자세한 내용은 조직의 리포지토리에 대한 규칙 집합 관리을(를) 참조하세요.

Your push would publish a private email address개 오류

GH007: Your push would publish a private email address이(가) 포함된 Git source migration failed 오류가 발생하면 마이그레이션하려는 Git 원본에 GitHub에 푸시되지 않도록 차단한 이메일 주소에서 작성한 커밋이 포함됩니다. 자세한 내용은 .

이 오류를 해결하려면 Git 기록을 다시 작성하여 이메일 주소를 제거하거나 "내 이메일을 노출하는 명령줄 푸시 차단" 설정을 사용하지 않도록 설정하면 됩니다.

마이그레이션 로그 경고 이해

마이그레이션이 성공하더라도 마이그레이션 로그를 검토하여 경고를 검사합니다.

마이그레이션 로그의 경고는 마이그레이션할 수 없는 리포지토리 내의 특정 항목을 가리킵니다. 자세한 내용은 GitHub Enterprise Importer에 대한 마이그레이션 로그 액세스을(를) 참조하세요.

Note

“마이그레이션 로그” 문제 아래쪽에 “마이그레이션 완료됨”이 포함된 경우 리포지토리가 마이그레이션되었다는 의미입니다. 경고는 끌어오기 요청에 대한 주석과 마찬가지로, 리포지토리 내의 특정 항목이 올바르게 마이그레이션되지 않았을 수 있음을 나타냅니다.

경고: 리포지토리 메타데이터가 너무 커서 마이그레이션할 수 없음

"마이그레이션 로그" 문제 또는 GitHub CLI에 "마이그레이션하기에 너무 큰 리포지토리 메타데이터"가 표시되면 리포지토리가 최대 보관 크기인 10GB를 초과한 것입니다. 이는 대용량 릴리스 자산으로 인해 발생하는 경우가 많습니다. migrate-repo 명령에 대한 --skip-releases 플래그를 사용하여 마이그레이션에서 릴리스를 제외해 보세요.

경고: "주석이 diff에 없음"

Azure DevOps에서 마이그레이션하는 경우 끌어오기 요청에서 변경되지 않은 라인의 끌어오기 요청 주석은 GitHub(으)로 마이그레이션할 수 없습니다. 이러한 이유로 마이그레이션할 수 없는 모든 주석에 대해 이 경고가 표시됩니다.

Note

끌어오기 요청에서 변경되지 않은 라인에 대한 주석만 이 제한 사항의 영향을 받습니다. 끌어오기 요청에서 변경된 라인에 대한 주석이 마이그레이션됩니다.

영향을 받는 주석은 마이그레이션된 리포지토리에 없지만 이러한 경고에는 추가 작업이 필요하지 않다는 점에 유의하세요.

경고: "끌어오기 요청 검토... "REVIEW_THREAD_MISSING_END_COMMIT_OID 오류로 인해 가져올 수 없음"

이 경고는 검토가 연결된 커밋이 더 이상 존재하지 않으므로 끌어오기 요청 검토를 마이그레이션할 수 없는 경우에 발생합니다.

일반적으로 커밋이 강제 푸시와 함께 제거되었거나 분기가 삭제된 경우에 발생합니다.

이 경우 주석은 손실되지 않지만 특정 커밋에 첨부된 검토가 아니라 기록을 보존하기 위해 인라인 끌어오기 요청 주석으로 마이그레이션됩니다.

조직 마이그레이션 후 팀 참고자료가 차단됨

@octo-org/octo-team와(과) 같은 팀에 대한 참조는 조직 마이그레이션의 일부로 업데이트되지 않습니다. 이로 인해 CODEOWNERS 파일이 예상대로 작동하지 않는 등, 대상 조직에서 문제가 발생할 수 있습니다.

마이그레이션 후에 이러한 참고자료를 업데이트하거나 대상 조직의 원래 이름을 사용할 수 있도록 원본 조직의 이름을 변경하여 팀 이름을 유지할 수 있습니다.

예를 들어 원본 조직이 @octo-org이고 CODEOWNERS 파일에 팀 @octo-org/octo-team에 대한 참고자료가 포함된 경우, 마이그레이션하기 전에 @octo-org-temp에 대한 원본 조직의 이름을 변경하여 @octo-org을(를) 새 조직의 이름으로 사용할 수 있습니다. 그런 다음 마이그레이션된 팀을 @octo-org/octo-team(이)라고 하며 마이그레이션된 리포지토리의 CODEOWNERS 파일이 예상대로 작동합니다.

잠긴 리포지토리

마이그레이션한 후에는 원본 또는 대상 리포지토리가 잠겨 리포지토리의 코드 및 모든 리소스(예: 문제 및 끌어오기 요청)에 대한 액세스를 사용하지 않도록 설정하여 찾을 수 있습니다. 잠긴 리포지토리에 대한 자세한 내용은 잠긴 리포지토리 정보을(를) 참조하세요.

리포지토리의 잠금을 해제하는 프로세스는 리포지토리가 저장된 GitHub 제품에 따라 달라집니다.

  • 잠긴 리포지토리가 GitHub Enterprise Server에 있는 경우 사이트 관리자는 사이트 관리자 대시보드를 사용하여 리포지토리의 잠금을 해제할 수 있습니다. 자세한 내용은 GitHub Enterprise Server 설명서의 리포지토리 잠금을(를) 참조하세요.
  • 잠긴 리포지토리가 GitHub.com에 있는 경우 GitHub 지원 포털 사용에 문의하여 리포지토리의 잠금을 해제할 수 있습니다.

Note

마이그레이션에 실패한 경우 모든 데이터가 마이그레이션되지 않습니다. 리포지토리의 잠금을 해제하고 사용하도록 선택하면 데이터가 손실됩니다. 잠긴 리포지토리를 삭제하고 마이그레이션을 다시 시도하는 것이 더 나은 옵션일 수 있습니다.

GitHub 지원에 문의

위의 문제 해결 단계를 시도한 후에도 여전히 문제를 해결할 수 없는 경우 GitHub 지원 포털을(를) 통해 GitHub 지원에 문의할 수 있습니다.