Skip to main content

Bitbucket Server에서 GitHub Enterprise Cloud로 리포지토리 마이그레이션

GitHub CLI을(를) 사용하여 Bitbucket Server에서 GitHub Enterprise Cloud(으)로 리포지토리를 마이그레이션할 수 있습니다.

GitHub Enterprise Importer을(를) 사용하는 리포지토리 마이그레이션 정보

GitHub CLI을(를) 사용하여 BitBucket Server 인스턴스에서 개별 리포지토리 또는 모든 리포지토리를 마이그레이션할 수 있습니다.

현재 GitHub API를 사용하여 Bitbucket Server에서 마이그레이션하는 것은 지원되지 않습니다.

필수 조건

  • 마이그레이션의 평가판을 수행하고 곧바로 프로덕션 마이그레이션을 완료하는 것이 좋습니다. 평가판 실행에 대한 자세한 내용은 "Bitbucket Server에서 GitHub Enterprise Cloud로 마이그레이션의 개요"을(를) 참조하세요.
  • 마이그레이션될 데이터와 가져오기 도구의 알려진 지원 제한 사항을 이해했는지 확인하세요. 자세한 내용은 "Bitbucket Server에서 GitHub Enterprise Cloud로 마이그레이션 정보"을(를) 참조하세요.
  • 필수는 아니지만 프로덕션 마이그레이션 중에는 작업을 중지하는 것이 좋습니다. Importer은(는) 델타 마이그레이션을 지원하지 않으므로 마이그레이션 중에 발생하는 변경 내용은 마이그레이션되지 않습니다. 프로덕션 마이그레이션 중에 작업을 중단하지 않도록 선택하는 경우, 이러한 변경 내용을 수동으로 마이그레이션해야 합니다.
  • GitHub.com에 대한 대상 조직의 경우 귀하가 조직 소유자이거나 마이그레이션자 역할이 있어야 합니다. 자세한 내용은 "Bitbucket 서버에서 마이그레이션에 대한 액세스 관리"을(를) 참조하세요.
  • 관리자 또는 슈퍼 관리자 권한이 있는 Bitbucket Server 계정의 사용자 이름과 암호가 필요합니다.

1단계: BBS2GH extension of the GitHub CLI 설치

첫 번째 마이그레이션인 경우 BBS2GH extension of the GitHub CLI을(를) 설치해야 합니다. GitHub CLI에 대한 자세한 내용은 "GitHub CLI 정보"을 참조하세요.

또는 github/gh-bbs2gh 리포지토리의 릴리스 페이지에서 독립 실행형 이진 파일을 다운로드할 수 있습니다. gh 접두사 없이 이 이진 파일을 직접 실행할 수 있습니다.

  1. GitHub CLI을(를) 설치하세요. GitHub CLI에 대한 설치 지침은 GitHub CLI 리포지토리를 참조하세요.

    참고: GitHub CLI 버전 2.4.0 이상이 필요합니다. gh --version 명령을 사용하여 설치한 버전을 검사할 수 있습니다.

  2. BBS2GH extension을(를) 설치합니다.

    Shell
    gh extension install github/gh-bbs2gh
    

BBS2GH extension에 대한 도움이 필요할 때마다 명령과 함께 플래그를 --help 사용할 수 있습니다. 예를 들어 사용 gh bbs2gh --help 가능한 모든 명령을 나열하고 gh bbs2gh migrate-repo --help 명령에 사용할 수 있는 migrate-repo 모든 옵션을 나열합니다.

2단계: BBS2GH extension of the GitHub CLI 업데이트

BBS2GH extension of the GitHub CLI은(는) 매주 업데이트됩니다. 최신 버전의 확장을 사용하고 있는지 확인합니다.

Shell
gh extension upgrade github/gh-bbs2gh

3단계: 환경 변수 설정

BBS2GH extension을(를) 사용하여 GitHub Enterprise Cloud(으)로 마이그레이션하기 전에 원본 및 대상 조직에 액세스할 수 있는 personal access token을(를) 만든 다음, personal access token을(를) 환경 변수로 설정해야 합니다.

또한 Bitbucket Server 사용자 이름 및 암호에 대한 환경 변수를 설정하고, Bitbucket Server 인스턴스가 Windows에서 실행되는 경우 SMB 암호를 설정해야 합니다.

  1. GitHub Enterprise Cloud에서 대상 조직에 대해 인증할 personal access token (classic)을(를) 만들고 기록하여 토큰이 모든 요구 사항을 충족하는지 확인합니다. 자세한 내용은 "Bitbucket 서버에서 마이그레이션에 대한 액세스 관리"을(를) 참조하세요.

  2. 환경 변수를 설정하고, 토큰을 위에서 기록한 personal access token(으)로, 사용자 이름을 관리자 또는 슈퍼 관리자 권한이 있는 Bitbucket Server 계정의 사용자 이름으로, 암호를 Bitbucket Server 계정의 암호로 바꿉니다.

    • Terminal을 사용하는 경우 export 명령을 사용합니다.

      Shell
      export GH_PAT="TOKEN"
      export BBS_USERNAME="USERNAME"
      export BBS_PASSWORD="PASSWORD"
      # If your Bitbucket Server instance runs on Windows
      export SMB_PASSWORD="PASSWORD"
      
    • PowerShell을 사용하는 경우 $env 명령을 사용합니다.

      Shell
      $env:GH_PAT="TOKEN"
      $env:BBS_USERNAME="USERNAME"
      $env:BBS_PASSWORD="PASSWORD"
      # If your Bitbucket Server instance runs on Windows
      $env:SMB_PASSWORD="PASSWORD"
      

4단계: Blob Storage 설정

많은 Bitbucket Server 인스턴스가 방화벽 뒤에 있기 때문에 GitHub CLI은(는) 인터넷에서 도달할 수 있는 데이터를 저장하는 중간 위치로 Blob Storage를 사용합니다.

먼저 마이그레이션하려는 데이터의 보관 파일을 생성하고 방화벽 뒤에서 Blob Storage로 데이터를 푸시합니다.

GitHub CLI은(는) 다음 Blob Storage 공급자를 지원합니다.

  • Amazon Web Services (AWS) S3
  • Azure Blob Storage

마이그레이션을 실행하기 전에 데이터를 저장하기 위해 선택한 클라우드 공급자를 사용하여 스토리지 컨테이너를 설정해야 합니다.

AWS S3 스토리지 버킷 설정

AWS에서 S3 버킷을 설정합니다. 자세한 내용은 AWS 설명서의 버킷 만들기를 참조하세요.

또한 다음 권한이 있는 AWS 액세스 키 및 비밀 키가 필요합니다.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:GetObject",
                "s3:ListBucketMultipartUploads",
                "s3:AbortMultipartUpload",
                "s3:ListBucket",
                "s3:DeleteObject",
                "s3:ListMultipartUploadParts"
            ],
            "Resource": [
                "arn:aws:s3:::github-migration-bucket",
                "arn:aws:s3:::github-migration-bucket/*"
            ]
        }
    ]
}

참고: GitHub Enterprise Importer은(는) 마이그레이션이 완료된 후 AWS에서 보관 파일을 삭제하지 않습니다. 스토리지 비용을 줄이려면 일정 기간 후의 보관 파일의 자동 삭제를 구성하는 것이 좋습니다. 자세한 내용은 AWS 설명서의 버킷에 대한 수명 주기 구성 설정을 참조하세요.

마이그레이션을 실행할 준비가 되면 지역, 액세스 키, 비밀 키 및 세션 토큰(필요한 경우)과 같은 GitHub CLI에 AWS 자격 증명을 제공해야 합니다. 인수로 전달하거나 AWS_REGION, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEYAWS_SESSION_TOKEN(으)로 불리는 환경 변수를 설정할 수 있습니다.

또한 --aws-bucket-name 인수를 사용하여 S3 버킷의 이름을 전달해야 합니다.

Azure Blob Storage 스토리지 계정 설정

Azure에서 스토리지 계정을 만들고 연결 문자열을 기록해 둡니다. 자세한 내용은 Microsoft Docs의 스토리지 계정 액세스 키 관리를 참조하세요.

참고: GitHub Enterprise Importer은(는) 마이그레이션이 완료된 후 Azure Blob Storage에서 보관 파일을 삭제하지 않습니다. 스토리지 비용을 줄이려면 일정 기간 후의 보관 파일의 자동 삭제를 구성하는 것이 좋습니다. 자세한 내용은 Microsoft Docs의 데이터 수명 주기를 자동으로 관리하여 비용 최적화를 참조하세요.

마이그레이션을 실행할 준비가 되면 GitHub CLI에 인수로 연결 문자열을 전달하거나 AZURE_STORAGE_CONNECTION_STRING 환경 변수를 사용하여 전달할 수 있습니다.

5단계: 리포지토리 마이그레이션

gh bbs2gh migrate-repo 명령을 사용하여 리포지토리를 마이그레이션할 수 있습니다.

리포지토리를 마이그레이션할 때 기본적으로 BBS2GH extension of the GitHub CLI은(는) 다음 단계를 수행합니다.

  1. Bitbucket Server 인스턴스에 연결하고 리포지토리당 마이그레이션 보관 파일을 생성합니다
  2. SFTP(Linux) 또는 SMB(Windows)를 사용하여 BBS2GH extension of the GitHub CLI을(를) Bitbucket Server 인스턴스에서 실행 중인 컴퓨터로 마이그레이션 보관 파일을 다운로드합니다
  3. 선택한 Blob 스토리지 공급자에 대한 마이그레이션 보관 파일을 업로드합니다
  4. Blob 스토리지 공급자와 함께 저장된 보관 파일의 URL을 사용하여 GitHub Enterprise Cloud에서 마이그레이션을 시작합니다
  5. 로컬 컴퓨터에서 마이그레이션 보관 파일을 삭제합니다. (마이그레이션이 완료되면 Blob Storage 공급자에서 보관 파일을 수동으로 삭제해야 합니다.)

아니면 GitHub CLI을(를) 사용하여 보관 파일을 생성하고, 해당 보관 파일을 수동으로 다운로드한 다음, GitHub CLI을(를) 사용하여 마이그레이션을 계속할 수 있습니다.

GitHub CLI에서 마이그레이션 보관 파일을 다운로드할 수 있도록 허용

단일 리포지토리를 마이그레이션하려면 gh bbs2gh migrate-repo 명령을 사용하세요.

액세스할 수 있는 컴퓨터에서 다음의 단계를 수행해야 합니다.

  • HTTPS를 이용한 Bitbucket 서버 인스턴스
  • Bitbucket Server 인스턴스가 Linux에서 실행되는 경우의 SFTP를 통한 Bitbucket Server 인스턴스입니다. 일반적으로 SSH를 통해 서버에 액세스할 수 있는 경우, SFTP를 사용할 수도 있습니다.
  • Bitbucket Server 인스턴스가 Windows에서 실행되는 경우의 SMB를 통한 Bitbucket Server 인스턴스입니다.
  • 지정한 Blob Storage 공급자
Shell
gh bbs2gh migrate-repo --bbs-server-url BBS-SERVER-URL \
  --bbs-project PROJECT --bbs-repo CURRENT-NAME \
  --github-org DESTINATION --github-repo NEW-NAME \
  # Use the following options if your Bitbucket Server instance runs on Linux
  --ssh-user SSH-USER --ssh-private-key PATH-TO-KEY
  # Use the following options if your Bitbucket Server instance runs on Windows
  --smb-user SMB-USER
  # Use the following option if you're using AWS S3 as your blob storage provider
  --aws-bucket-name AWS-BUCKET-NAME
  # Use the following option if you are running a Bitbucket Data Center cluster or your Bitbucket Server is behind a load balancer
  --archive-download-host ARCHIVE-DOWNLOAD-HOST

명령 내의 자리 표시자를 다음 값으로 바꿉니다.

자리 표시자
BBS-SERVER-URLBitbucket 서버 인스턴스 URL
PROJECT마이그레이션하려는 리포지토리의 Bitbucket Server 프로젝트 키입니다.
CURRENT-NAME마이그레이션할 리포지토리의 이름
대상대상 조직의 이름
NEW-NAME마이그레이션된 리포지토리에서 사용할 이름
SSH-USERBitbucket Server 인스턴스가 Linux에서 실행되는 경우 SFTP를 통해 Bitbucket Server에 연결할 때 사용되는 사용자 이름입니다.
PATH-TO-KEYBitbucket 서버 인스턴스가 Linux에서 실행되는 경우 SSH 프라이빗 키의 경로(예: ~/.ssh/id_rsa.) SSH 키 요구 사항은 "Bitbucket 서버에서 마이그레이션에 대한 액세스 관리"을 참조하세요.
SMB-USERBitbucket Server 인스턴스가 Windows에서 실행하는 경우, SMB를 통해 Bitbucket Server에 연결할 때 사용되는 사용자 이름입니다.
AWS-BUCKET-NAMEAWS S3 버킷의 버킷 이름
ARCHIVE-DOWNLOAD-HOSTSSH 혹은 SMB를 통해 Bitbucket 서버/데이터 센터 인스턴스에 연결하는 데 사용할 호스트입니다. Bitbucket 데이터 센터 클러스터를 실행 중이거나 Bitbucket 서버가 부하 분산 장치 뒤에 있는 경우에만 이를 지정해야 합니다.

참고: Renci.SshNet 멘션 오류가 발생하면 CLI에서 마이그레이션 보관 파일을 다운로드하기 위해 서버에 SFTP 연결을 만드는 데 문제가 있는 것입니다. 이러한 문제를 해결하는 방법에 대한 자세한 내용은 "GitHub Enterprise Importer를 사용하여 마이그레이션 문제 해결"을 참조하세요.

마이그레이션 보관 파일을 수동으로 다운로드

기본적으로 BBS2GH extension of the GitHub CLI은(는) SFTP 또는 SMB를 사용하여 Bitbucket Server 인스턴스에서 마이그레이션 보관 파일을 다운로드하는 등 전체 마이그레이션을 수행합니다.

그러나 일부 고객은 서버가 SFTP 액세스를 제공하지 않으므로 마이그레이션 보관 파일을 수동으로 다운로드하는 것을 선호합니다. 이 경우, GitHub CLI을(를) 사용하여 보관 파일을 생성하고, 해당 보관 파일을 수동으로 다운로드한 다음, GitHub CLI을(를) 사용하여 마이그레이션을 계속할 수 있습니다.

액세스할 수 있는 컴퓨터에서 다음 단계를 수행해야 합니다.

  • HTTPS를 이용한 Bitbucket 서버 인스턴스
  • 선택한 Blob Storage 공급자

먼저 다음 인수만 포함된 gh bbs2gh migrate-repo 명령을 사용합니다.

Shell
gh bbs2gh migrate-repo --bbs-server-url BBS-SERVER-URL \
  --bbs-project PROJECT \
  --bbs-repo CURRENT-NAME

명령 내의 자리 표시자를 다음 값으로 바꿉니다.

자리 표시자
BBS-SERVER-URLBitbucket 서버 인스턴스 URL
PROJECT마이그레이션하려는 리포지토리의 Bitbucket Server 프로젝트 키입니다.
CURRENT-NAME마이그레이션할 리포지토리의 이름

마이그레이션 보관 파일이 생성되고 해당 경로가 다음 명령 출력에 출력됩니다.

[12:14] [INFO] Export completed. Your migration archive should be ready on your
instance at $BITBUCKET_SHARED_HOME/data/migration/export/Bitbucket_export_9.tar

일반적으로 $BITBUCKET_SHARED_HOME은(는) Linux의 /var/atlassian/application-data/bitbucket/shared 및 Windows의 C:\Atlassian\ApplicationData\Bitbucket\Shared에 설정되지만 서버 구성에 따라 다를 수 있습니다. 공유 홈 디렉터리를 식별하는 데 도움을 받으려면 "GitHub Enterprise Importer를 사용하여 마이그레이션 문제 해결"을 참조하세요.

Bitbucket Server 인스턴스에서 마이그레이션 보관 파일을 다운로드하고 GitHub CLI을(를) 실행 중인 컴퓨터에 보관 파일을 저장합니다.

마이그레이션 보관 파일을 GitHub(으)로 가져오려면 다른 인수 집합이 포함된 gh bbs2gh migrate-repo 명령을 다시 사용합니다.

Shell
gh bbs2gh migrate-repo --archive-path ARCHIVE-PATH \
  --github-org DESTINATION --github-repo NEW-NAME \
  --bbs-server-url BBS-SERVER-URL \
  --bbs-project PROJECT \
  --bbs-repo CURRENT-NAME \
  # Use the following option if you're using AWS S3 as your blob storage provider
  --aws-bucket-name AWS-BUCKET-NAME

명령 내의 자리 표시자를 다음 값으로 바꿉니다.

자리 표시자
ARCHIVE-PATH인스턴스에서 다운로드한 Bitbucket 서버 마이그레이션 보관 파일 경로
대상대상 조직의 이름
NEW-NAME마이그레이션된 리포지토리에서 사용할 이름
BBS-SERVER-URLBitbucket 서버 인스턴스 URL
PROJECT마이그레이션하려는 리포지토리의 Bitbucket Server 프로젝트 키입니다.
CURRENT-NAME마이그레이션할 리포지토리의 이름
AWS-BUCKET-NAMEAWS S3 버킷의 버킷 이름

마이그레이션 취소

마이그레이션을 취소하려면 abort-migration 명령을 사용하여 MIGRATION-ID를 migrate-repo에서 반환된 ID로 바꿔야 합니다.

Shell
gh bb2gh abort-migration --migration-id MIGRATION-ID

6단계: 마이그레이션 유효성 검사 및 오류 로그 검사

마이그레이션이 완료되면, 마이그레이션 로그를 검토하는 것이 좋습니다. 자세한 내용은 "GitHub Enterprise Importer에 대한 마이그레이션 로그 액세스"을 참조하세요.

마이그레이션된 리포지토리에서 건전성 검사를 검토하는 것이 좋습니다.

7단계: 리포지토리 마이그레이션

여러 리포지토리를 한 번에 GitHub Enterprise Cloud으로 마이그레이션하려면 GitHub CLI을(를) 사용하여 마이그레이션 스크립트를 생성합니다. 결과 스크립트에는 리포지토리당 하나씩의 마이그레이션 명령 목록이 포함됩니다.

참고: 스크립트를 생성하면 PowerShell 스크립트가 출력됩니다. 터미널을 사용하는 경우 .ps1 파일 확장과 함께 스크립트를 출력하고 Mac 또는 Linux용 PowerShell을 설치하여 실행해야 합니다.

마이그레이션 스크립트 생성

HTTPS를 통해 Bitbucket Server 인스턴스에 액세스할 수 있는 컴퓨터에서 이 단계를 수행해야 합니다.

마이그레이션 스크립트를 생성하려면 gh bbs2gh generate-script 명령을 실행합니다.

Shell
gh bbs2gh generate-script --bbs-server-url BBS-SERVER-URL \
  --github-org DESTINATION \
  --output FILENAME \
  # Use the following options if your Bitbucket Server instance runs on Linux
  --ssh-user SSH-USER --ssh-private-key PATH-TO-KEY
  # Use the following options if your Bitbucket Server instance runs on Windows
  --smb-user SMB-USER
  # Use the following option if you are running a Bitbucket Data Center cluster or your Bitbucket Server is behind a load balancer
  --archive-download-host ARCHIVE-DOWNLOAD-HOST

스크립트가 마이그레이션된 각 리포지토리에 대한 마이그레이션 로그를 다운로드하려면 --download-migration-logs 플래그를 추가합니다. 마이그레이션 로그에 대한 자세한 내용은 "GitHub Enterprise Importer에 대한 마이그레이션 로그 액세스"를 참조하세요.

명령 내의 자리 표시자를 다음 값으로 바꿉니다.

자리 표시자
BBS-SERVER-URLBitbucket 서버 인스턴스 URL
대상대상 조직의 이름
FILENAME결과 마이그레이션 스크립트의 파일 이름

터미널을 사용하는 경우 생성된 스크립트에서 PowerShell을 실행해야 하므로 .ps1 파일 확장을 사용합니다. Mac 또는 Linux용 PowerShell을 설치할 수 있습니다.
SSH-USERBitbucket Server 인스턴스가 Linux에서 실행되는 경우 SFTP를 통해 Bitbucket Server에 연결할 때 사용되는 사용자 이름입니다.
PATH-TO-KEYBitbucket 서버 인스턴스가 Linux에서 실행되는 경우 SSH 프라이빗 키의 경로(예: ~/.ssh/id_rsa.) SSH 키 요구 사항은 "Bitbucket 서버에서 마이그레이션에 대한 액세스 관리"을 참조하세요.
SMB-USERBitbucket Server 인스턴스가 Windows에서 실행하는 경우, SMB를 통해 Bitbucket Server에 연결할 때 사용되는 사용자 이름입니다.
ARCHIVE-DOWNLOAD-HOSTSSH 혹은 SMB를 통해 Bitbucket 서버/데이터 센터 인스턴스에 연결하는 데 사용할 호스트입니다. Bitbucket 데이터 센터 클러스터를 실행 중이거나 Bitbucket 서버가 부하 분산 장치 뒤에 있는 경우에만 이를 지정해야 합니다.

마이그레이션 스크립트 검토

스크립트를 생성한 후 파일을 검토하고 필요에 따라 스크립트를 편집합니다.

  • 마이그레이션하지 않으려는 리포지토리가 있는 경우 해당 라인을 삭제하거나 주석으로 처리합니다.
  • 기본적으로 GitHub의 리포지토리 이름은 projectKey-repositoryName 규칙을 따릅니다. 예를 들어 키 OS이(가) 있는 open-source 프로젝트의 일부인 airports(이)라는 이름의 Bitbucket Server 리포지토리는 GitHub에서 OS-airports(이)라고 불립니다. GitHub에서 리포지토리에 다른 이름을 지정하려면 해당 --github-repo 플래그의 값을 업데이트합니다.

BBS2GH을(를) GitHub CLI의 확장이 아닌 독립 실행형 이진으로 다운로드한 경우 gh bbs2gh 대신 이진 파일을 실행하려면 생성된 스크립트를 업데이트해야 합니다.

마이그레이션 스크립트 실행

리포지토리를 마이그레이션하려면 생성된 스크립트를 실행합니다.

액세스할 수 있는 컴퓨터에서 다음의 단계를 수행해야 합니다.

  • HTTPS를 이용한 Bitbucket 서버 인스턴스
  • Bitbucket Server 인스턴스가 Linux에서 실행되는 경우의 SFTP를 통한 Bitbucket Server 인스턴스입니다. 일반적으로 SSH를 통해 서버에 액세스할 수 있는 경우, SFTP를 사용할 수도 있습니다.
  • Bitbucket Server 인스턴스가 Windows에서 실행되는 경우의 SMB를 통한 Bitbucket Server 인스턴스입니다.
  • 지정한 Blob Storage 공급자

스크립트를 실행하기 전에 Blob Storage 공급자에 인증할 추가적인 환경 변수를 설정해야 합니다.

  • AWS S3의 경우, 다음 환경 변수를 설정합니다.
    • AWS_ACCESS_KEY: 버킷에 대한 액세스 키
    • AWS_SECRET_KEY: 버킷의 비밀 키
    • AWS_REGION: 버킷이 있는 AWS 지역
    • AWS_SESSION_TOKEN: AWS 임시 자격 증명을 사용하는 경우 세션 토큰(AWS 설명서에서 AWS 리소스와 함께 임시 자격 증명 사용 참조)
  • Azure Blob Storage의 경우 AZURE_STORAGE_CONNECTION_STRING을(를) Azure 스토리지 계정에 대한 연결 문자열에 설정합니다.

스토리지 계정 액세스 키를 사용하는 연결 문자열만이 지원됩니다. SAS(공유 액세스 서명)를 사용하는 연결 문자열은 지원되지 않습니다. 스토리지 계정 액세스 키를 검색하는 방법에 대한 자세한 내용은 Azure 설명서의 스토리지 계정 액세스 키 관리를 참조하세요.

여러 리포지토리를 동시에 마이그레이션하려면 이 위에서 생성한 스크립트를 실행합니다. 아래 명령의 FILENAME을 스크립트를 생성할 때 제공받은 파일 이름으로 바꿉니다.

  • 터미널을 사용하는 경우, ./을(를) 사용하세요.

    Shell
    ./FILENAME
    
  • PowerShell을 사용하는 경우 .\을(를) 사용하세요.

    Shell
    .\FILENAME