GitHub로 마이그레이션 계획

마이그레이션 정보

GitHub 제품(예: GitHub Enterprise Server에서 GitHub Enterprise Cloud으로 또는 Bitbucket Server 또는 GitLab과 같은 다른 코드 호스팅 플랫폼에서 GitHub)으로 이동하는 경우 사용자 코드, 코드 기록 및 이전 대화 및 공동 작업을 모두 이동하려고 할 것입니다.

이 가이드에서는 성공적인 마이그레이션 계획 및 실행을 안내합니다. 마이그레이션을 준비하는 방법, 데이터를 이동하는 데 사용할 수 있는 도구 및 이동을 성공으로 만드는 방법을 알아보세요.

마이그레이션 용어

이 가이드를 사용하여 마이그레이션을 계획하기 전에 이러한 중요한 용어를 알아보세요.

용어	정의
코드 호스팅 플랫폼	소스 코드 리포지토리를 호스트하고 공동 작업하는 데 사용하는 온라인 도구(예: GitHub Enterprise Cloud, GitHub Enterprise Server, Bitbucket Server 및 GitLab.com).
버전 제어 시스템(VCS)	이러한 변경을 수행하는 컴퓨터에서 소스 코드의 변경 내용을 추적하고 관리하는 데 사용하는 도구입니다. 예를 들어 GitHub 또는 GitLab을 코드 호스팅 플랫폼으로 사용하는 경우 Git 버전 제어 시스템을 사용합니다. Azure DevOps를 코드 호스팅 플랫폼으로 사용하는 경우 Git 또는 Team Foundation 버전 제어(TFVC)를 기본 버전 제어 시스템으로 사용할 수 있습니다. VCS를 전혀 사용하지 않을 수도 있습니다.
마이그레이션 원본	마이그레이션하는 위치입니다. 이는 일반적으로 코드 호스팅 플랫폼이지만 자체 컴퓨터 또는 공유 네트워크 드라이브일 수 있습니다.
마이그레이션 대상	이동할 GitHub 제품입니다.
마이그레이션 경로	마이그레이션 원본과 마이그레이션 대상의 조합(예: "Bitbucket Server에서 GitHub Enterprise Cloud"). 특정 마이그레이션 경로의 경우 GitHub은(는) 마이그레이션에 도움이 되는 GitHub Enterprise Importer와(과) 같은 전문 도구를 제공합니다.

마이그레이션 범위 정의

마이그레이션을 계획하기 전에 마이그레이션하려는 항목과 시기를 이해해야 합니다.

원본 및 대상 정의

먼저 데이터를 이동해야 하는 위치를 결정합니다. 이는 일반적으로 항상 코드 호스팅 플랫폼은 아닙니다.

코드 호스팅 플랫폼은 GitHub 제품(예: GitHub.com 또는 GitHub Enterprise Server)이거나 Bitbucket Server, GitLab 또는 Azure DevOps와 같은 다른 코드 호스팅 플랫폼일 수 있습니다. 비즈니스의 크기와 복잡성에 따라 여러 코드 호스팅 플랫폼을 사용할 수 있습니다.

예를 들어 코드 호스팅 플랫폼을 전혀 사용하지 않는 경우 공유 네트워크 드라이브에 코드를 저장할 수 있습니다.

코드가 어디에 있든 이것이 "마이그레이션 원본"입니다.

또한 마이그레이션할 GitHub 제품 또는 "마이그레이션 대상"도 알아야 합니다. 이것은 GitHub.com, GHE.com 또는 GitHub Enterprise Server일 수 있습니다.

마이그레이션하려는 리포지토리의 기본 인벤토리 빌드

마이그레이션 원본 및 대상을 식별한 후 마이그레이션해야 하는 데이터를 설정합니다.

마이그레이션해야 하는 마이그레이션 원본의 모든 리포지토리 목록을 사용하여 마이그레이션 인벤토리를 빌드해야 합니다. 스프레드시트를 사용하는 것이 좋습니다. 시작점으로 각 리포지토리에 대해 다음 데이터를 기록해야 합니다.

속성
소유자: GitHub에서는 조직이지만 다른 도구에서는 다른 종류의 소유자가 있을 수 있습니다
URL
마지막으로 업데이트한 타임스탬프
끌어오기 요청 수(또는 마이그레이션 원본에 상응하는 것)
문제 수(또는 마이그레이션 원본에 상응하는 것)

GitHub Enterprise Cloud 또는 GitHub Enterprise Server에서 마이그레이션하는 경우 GitHub CLI에 대한 gh-repo-stats 확장을 통해 이 데이터를 가져올 수 있습니다. 몇 가지 명령을 사용하면 gh-repo-stats은(는) 마이그레이션 원본의 API와 연결하고 모든 권장 필드가 있는 CSV를 만듭니다. 자세한 내용은 mona-actions/gh-repo-stats 리포지토리를 참조하세요.

참고: gh-repo-stats은(는) GitHub 지원에서 지원하지 않는 제3자 오픈 소스 도구입니다. 이 도구 에 대한 도움이 필요한 경우 해당 리포지토리에서 문제를 엽니다.

Azure DevOps에서 마이그레이션하는 경우 ADO2GH extension of the GitHub CLI의 inventory-report 명령을 사용하는 것이 좋습니다. 이 inventory-report 명령은 Azure DevOps API와 연결한 다음 위에 제안된 필드 중 일부를 사용하여 간단한 CSV를 빌드합니다. ADO2GH extension of the GitHub CLI을(를) 설치하는 방법에 대한 자세한 내용은 "Azure DevOps에서 GitHub Enterprise Cloud로 리포지토리 마이그레이션"을 참조하세요.

Bitbucket Server 또는 Bitbucket 데이터 센터에서 마이그레이션하는 경우 BBS2GH extension of the GitHub CLI의 inventory-report 명령을 사용하는 것이 좋습니다. 이 inventory-report 명령은 Bitbucket 인스턴스의 API를 사용하여 간단한 CSV를 빌드합니다. BBS2GH extension of the GitHub CLI을(를) 설치하는 방법에 대한 자세한 내용은 "Bitbucket Server에서 GitHub Enterprise Cloud로 리포지토리 마이그레이션"을 참조하세요.

다른 마이그레이션 원본의 경우 마이그레이션 인벤토리를 직접 만듭니다. 원본의 보고 도구(사용 가능한 경우) 또는 API를 사용하여 스프레드시트를 빌드하거나 인벤토리를 수동으로 만들 수 있습니다.

마이그레이션 인벤토리에 대해 어떤 접근 방식을 선택하든 수행된 프로세스 또는 실행한 명령을 기록해 둡니다. 마이그레이션을 계속 계획할 때 인벤토리를 다시 실행할 가능성이 매우 높습니다.

모든 리포지토리 목록이 있으면 마이그레이션할 리포지토리를 결정할 수 있습니다. 한 가지 옵션은 모든 것을 완전히 마이그레이션하는 것입니다. 그러나 마이그레이션은 리포지토리를 평가하고 더 이상 필요하지 않은 리포지토리를 제거할 수 있는 좋은 기회입니다. 많은 비즈니스에는 수백 또는 수천 개의 사용하지 않은 불필요한 리포지토리가 있으며, 이러한 리포지토리를 보관하면 마이그레이션이 훨씬 간단해질 수 있다는 것을 알아냈습니다.

리포지토리의 크기 측정

기본 마이그레이션 인벤토리를 완료한 후 리포지토리의 크기에 대한 정보를 수집합니다. 리포지토리가 크거나 100MB가 넘는 개별 파일이 포함된 경우 마이그레이션이 더 길고 위험해질 수 있으며 사용 가능한 마이그레이션 도구를 제한할 수 있습니다.

Git을 버전 제어 시스템으로 사용하는 경우 현재 리포지토리에 있는 대용량 파일뿐만 아니라 리포지토리의 기록에 있는 대용량 파일도 중요합니다. 예를 들어 과거에 리포지토리에 100MB보다 큰 파일이 있는 경우 파일의 모든 추적을 제거하기 위해 기록을 다시 작성하지 않는 한 해당 파일은 Git 기록에 계속 존재합니다. 기록 다시 쓰기에 대한 자세한 내용은 "GitHub의 대용량 파일 정보"을 참조하세요.

인벤토리를 빌드하는 데 gh-repo-stats을(를) 사용한 경우 리포지토리가 얼마나 큰지에 대한 몇 가지 기본 정보를 이미 보유하고 있습니다. 전체 마이그레이션 인벤토리를 빌드하려면 리포지토리 내의 데이터에 대한 세부 정보를 가져와야 합니다.

다음으로 아래 지침에 따라 각 리포지토리와 관련된 마이그레이션 인벤토리에 다음 데이터를 추가합니다.

가장 대용량인 파일의 크기("미확인 개체"라고도 함)
모든 파일의 총 크기("미확인 개체")

Git 이외의 버전 제어 시스템을 사용하고 있거나 파일이 버전 제어 시스템을 사용하여 전혀 추적되지 않는 경우 먼저 리포지토리를 Git으로 이동합니다. 자세한 내용은 "GitHub에 로컬로 호스트된 코드 추가"을(를) 참조하세요.

그런 다음 오픈 소스 도구인 git-sizer을(를) 사용하여 리포지토리에 대한 이 데이터를 가져옵니다.

필수 조건

git-sizer를 설치합니다. 자세한 내용은 github/git-sizer 리포지토리를 참조하세요.
git-sizer이(가) 설치되어 있는지 확인하려면 git-sizer –version을(를) 실행하세요. git-sizer release 1.5.0와(과) 같은 출력이 표시되면 설치가 성공한 것입니다.
jq를 설치합니다. 자세한 내용은 jq 설명서의 jq 다운로드를 참조하세요.
jq이(가) 설치되어 있는지 확인하려면 jq –-version을(를) 실행하세요. jq-1.6와(과) 같은 출력이 표시되면 설치가 성공한 것입니다.

`git-sizer`을(를) 사용한 리포지토리 크기 측정

마이그레이션 원본에서 리포지토리를 복제하려면 git clone --mirror을(를) 실행하세요.
리포지토리를 복제한 디렉터리로 이동합니다.
리포지토리에 있는 가장 대용량인 파일의 크기를 바이트 단위로 얻으려면 git-sizer --no-progress -j | jq ".max_blob_size"을(를) 실행하세요.
리포지토리에 있는 모든 파일의 총 크기를 바이트 단위로 얻으려면 git-sizer --no-progress -j | jq ".unique_blob_size"을(를) 실행하세요.
이전 단계의 값을 인벤토리에 추가합니다.

마이그레이션 유형 정보

마이그레이션을 실행할 때 수행할 수 있는 세 가지 접근 방식은 서로 다른 수준의 마이그레이션 충실도를 제공합니다.

마이그레이션 유형	정의	요구 사항
원본 스냅샷	현재와 같이 코드의 현재 상태를 마이그레이션하지만 수정 기록이 포함되지 않습니다.	코드가 현재 버전 제어 시스템(VCS)에서 추적되지 않더라도 모든 원본 및 대상에 대해 가능합니다.
원본 및 기록	코드의 현재 상태와 수정 기록을 마이그레이션합니다.	Git 또는 마이그레이션하기 전에 Git으로 변환할 수 있는 버전 제어 시스템의 변경 내용을 추적한 경우 가능합니다.
원본, 기록 및 메타데이터	코드의 현재 상태와 수정 기록과 문제 및 끌어오기 요청, 설정과 같은 공동 작업 기록을 마이그레이션합니다.	모든 마이그레이션 경로에 사용할 수 없는 전문 도구가 필요합니다.

완료할 마이그레이션 유형을 결정할 때 조직의 요구 사항과 사용 가능한 도구를 고려합니다.

다른 리포지토리에 대해 다른 전략을 사용하고 싶을 수 있습니다. 예를 들어 기록이 중요하지 않은 오래된 보관된 리포지토리가 있을 수 있지만, 충실도가 높은 마이그레이션은 가장 활성화된 코드에 중요합니다.

다양한 마이그레이션 지원 모델에 대한 정보

GitHub의 전문적인 지원 없이 설명서만 사용하여 고유의 마이그레이션을 계획하고 실행하는 "셀프 서비스 마이그레이션"을 완료하도록 선택할 수 있습니다.

아니면 GitHub의 전문가 서비스 팀 또는 "전문가 주도 마이그레이션"이라고 하는 GitHub 파트너와 함께 작업하는 것이 좋습니다. 전문가 주도 마이그레이션을 사용하면 이전에 수십 또는 수백 건의 마이그레이션을 실행한 전문가의 지식과 경험을 활용할 수 있으며, 셀프 서비스용으로 사용할 수 없는 추가 마이그레이션 도구에 액세스할 수 있습니다.

많은 양의 데이터를 마이그레이션하는 경우 전문가 주도 마이그레이션의 이점을 누릴 수 있습니다. 예를 들어, 수천 개의 리포지토리를 마이그레이션하거나 크기가 약 5GB보다 큰 복잡한 리포지토리가 있는 경우 Expert Services에 연결하는 것이 좋습니다.

	셀프 서비스	전문가 주도
설명서에 대한 액세스

지원에서 다루는 주제	실행 문제 해결	계획 실행 문제 해결
비용	무료	자세한 내용은 전문가 서비스에 문의하세요

전문가 주도 마이그레이션에 대한 자세한 내용은 계정 담당자 또는 전문가 서비스에 문의하세요.

사용할 도구 결정

마이그레이션은 대상 및 원본을 고려하려 계획합니다. 고려 사항에 따라 마이그레이션 경로를 결정합니다. 자세한 내용은 "GitHub에 대한 마이그레이션 경로"을 참조하세요.

마이그레이션 대상에 대한 조직 구조 디자인

GitHub에서 각 리포지토리는 조직에 속합니다. 조직은 비즈니스와 오픈 소스 프로젝트가 정교한 보안 및 관리 기능을 사용하여 여러 프로젝트에서 동시에 협업할 수 있는 공유 계정입니다. 자세한 내용은 "조직 정보"을 참조하세요.

GitHub을(를) 처음 채택하든, 이미 % data variables.product.prodname_dotcom %}을(를) 사용했든지 간에 마이그레이션한 후 조직 및 리포지토리에 가장 효과적인 구조를 고려하려면 일시 중지합니다. 선택한 디자인은 공동 작업 및 검색을 최대화하고 관리 부담을 최소화하거나 불필요한 사일로 및 관리 오버헤드를 만들 수 있습니다.

조직 수를 최소화하고 5가지 원형 중 하나에 따라 조직을 구성하는 것이 좋습니다. 자세한 지침은 "엔터프라이즈의 조직 구조화 모범 사례"을 참조하세요.

모든 리포지토리에 대해 시허 실행 마이그레이션 수행

계획을 계속하기 전에 모든 리포지토리를 포함하여 시험 실행 마이그레이션을 수행합니다. 포괄적인 시험 실행을 사용하면 다음과 같이 할 수 있습니다.

선택한 도구가 리포지토리에 작동하는지 확인
도구가 요구 사항을 충족하는지 확인
마이그레이션되는 데이터 및 마이그레이션되지 않은 데이터를 정확히 알기
프로덕션 마이그레이션을 예약하는 데 도움이 되도록 마이그레이션에 걸리는 시간 알기

시험 실행 마이그레이션에 대한 고유 사항이 없습니다. 일반 마이그레이션을 실행한 다음, 마이그레이션 대상에서 리포지토리를 삭제하기만 하면됩니다.

마이그레이션 전 및 마이그레이션 후 단계 계획

리포지토리 마이그레이션은 더 큰 마이그레이션 프로세스에서 한 단계에 불과합니다. 수행해야 하는 다른 단계와 수동으로 마이그레이션해야 하는 데이터 또는 설정이 있을 수 있습니다.

마이그레이션에 필요한 전체 단계 목록은 고유한 상황에 따라 달라지지만, 다음과 같이 모든 마이그레이션에 적용되는 몇 가지 사전 마이그레이션 단계가 있습니다.

사용자에게 예정된 마이그레이션 및 해당 타임라인에 대해 미리 알림
마이그레이션이 발생하기 직전에 미리 알림 보내기
팀의 GitHub에서 사용자 계정 설정
새 시스템을 가리키도록 로컬 리포지토리를 업데이트하는 지침을 사용자에게 보냅니다

다음과 같이 모든 마이그레이션에 적용되는 마이그레이션 후 단계도 있습니다.

마이그레이션이 완료되었다는 것을 사용자에게 알림
마이그레이션 대상의 사용자에게 활동 연결
마이그레이션 원본 사용 중단

마이그레이션을 계획할 때 고려해야 할 몇 가지 다른 단계는 다음과 같습니다.

연속 통합(CI) 및 지속적인 업데이트(CD) 마이그레이션

GitHub 제품 간에 이동하는 경우 이미 CI/CD에 대한 GitHub Actions을(를) 사용하고 있으며 GitHub Actions을(를) 계속 사용하는 경우 수행할 일이 별로 없습니다. 리포지토리의 워크플로 파일이 자동으로 귀하에게 마이그레이션됩니다. 자체 호스팅 실행기를 사용하는 경우 워크플로를 실행할 준비가 되도록 새 GitHub 조직에서 설정해야 합니다.

GitHub Actions을(를) 사용하지 않으면 상황이 더 복잡해집니다. 동일한 CI/CD 공급자를 계속 사용하려는 경우 공급자가 GitHub와(과) 호환되는지 확인하고, 해당 공급자를 새 조직 및 리포지토리에 연결해야 합니다.

GitHub Actions(으)로 전환하려는 경우 리포지토리를 마이그레이션하면서 이 작업을 수행하지 않는 것이 좋습니다. 대신 이후 날짜까지 기다렸다가 별도의 단계로 CI/CD 마이그레이션을 수행합니다. 이렇게 하면 마이그레이션 프로세스를 보다 쉽게 관리할 수 있습니다. 마이그레이션할 준비가 되면 "GitHub Actions로 마이그레이션"을 참조하세요.

통합 마이그그레션

사내에서 개발되거나 다른 공급업체에서 제공하는 코드 호스팅 공급자를 통해 통합을 사용할 수 있습니다.

에 새로 사용하는 경우 통합이 GitHub와(과) 호환되는지 여부를 검사한 다음, 통합을 다시 구성합니다. 사내에서 개발된 통합을 사용하는 경우 GitHub API로 작업하도록 통합을 다시 작성합니다. 자세한 내용은 "GitHub REST API 설명서"을(를) 참조하세요.

마이그레이션 대상의 사용자에게 활동 연결

공동 작업 기록 또는 메타데이터와 코드를 마이그레이션하는 경우 마이그레이션 대상에서 사용자의 활동을 새 ID에 연결해야 합니다.

예를 들어 @octocat(으)로 인해 GitHub Enterprise Server 인스턴스에 문제가 생겼고 GitHub Enterprise Cloud(으)로 이동한다고 가정해 보겠습니다. GitHub Enterprise Cloud에서 @octocat은(는) 완전히 다른 사용자 이름을 가질 수 있습니다. 특성 프로세스를 사용하면 사용자 활동을 이러한 새 ID와 연결할 수 있습니다.

특성이 작동하는 방식은 도구 간에 다릅니다.

ghe-migrator, gl-exporter 또는 bbs-exporter을(를) 사용하고 있는 경우 데이터를 미리 특성화하고 데이터를 가져올 때 매핑 파일을 포함할 방법을 결정합니다.
GitHub Enterprise Importer을(를) 사용하는 경우 데이터는 "마네킹"이라는 자리 표시자 ID에 연결되며 데이터가 마이그레이션된 후 이 기록을 실제 사용자에게 할당할 수 있습니다. 자세한 내용은 "GitHub Enterprise Importer에 대한 마네킹 회수"을(를) 참조하세요.

팀 및 권한 관리

대부분의 고객은 팀을 사용하여 리포지토리에 대한 액세스를 관리합니다. 팀을 사용하면 Mona에게 리포지토리에 대한 액세스 권한을 직접 부여하는 대신 엔지니어링 팀에 Mona를 추가하고 엔지니어링 팀의 모든 사람에게 리포지토리에 대한 액세스 권한을 부여할 수 있습니다. 자세한 내용은 "팀 정보"을(를) 참조하세요.

리포지토리를 마이그레이션하기 전에 팀을 만들고 팀 구성원을 추가할 수 있습니다. 팀을 IdP 그룹에 연결하여 ID 공급자(IdP)를 통해 구성원을 관리할 수 있습니다. 자세한 내용은 "팀과 ID 공급자 그룹 동기화"을(를) 참조하세요.

그러나 리포지토리를 마이그레이션할 때까지 리포지토리에 팀을 연결할 수 없습니다.

이 문서의 내용