GitHub Enterprise Importer
を使ったリポジトリの移行について
GitHub CLI を使用して、BitBucket Server インスタンスから個々のリポジトリまたはすべてのリポジトリを移行できます。
現時点では、GitHub API を使用した Bitbucket Server からの移行はサポートされていません。
前提条件
- 移行の試験的実行を行い、そのすぐ後で運用環境の移行を完了することを強くお勧めします。 試験的実行について詳しくは、「Bitbucket サーバーから GitHub Enterprise クラウドへの移行の概要」をご覧ください。
- 移行されるデータと、Importer の既知のサポート制限事項を理解していることを確認します。 詳しくは、「Bitbucket サーバーから GitHub Enterprise クラウドへの移行について」をご覧ください。
- 必須ではありませんが、運用環境の移行の間は作業を停止することをお勧めします。 Importer は差分移行をサポートしていないため、移行中に発生した変更は移行されません。 運用環境の移行の間に作業を停止しない場合は、これらの変更を手動で移行する必要があります。
- GitHub.com の移行先の Organization では、Organization 所有者であるか、移行者ロールを持っている必要があります。 詳しくは、「Bitbucket サーバーからの移行のアクセスの管理」を参照してください。
- 管理者またはスーパー管理者のアクセス許可がある Bitbucket Server アカウントのユーザー名とパスワードが必要です。
手順 1: BBS2GH extension of the GitHub CLI をインストールする
これが初めての移行の場合は、BBS2GH extension of the GitHub CLI をインストールする必要があります。 GitHub CLI について詳しくは、「GitHub CLI について」をご覧ください。
または、github/gh-bbs2gh
リポジトリの「リリース ページ」からスタンドアロン バイナリをダウンロードすることもできます。 このバイナリは、gh
プレフィックスなしで直接実行できます。
-
GitHub CLI をインストールします。 GitHub CLI のインストール手順については、GitHub CLI リポジトリを参照してください。
Note
GitHub CLI のバージョン 2.4.0 以降が必要です。
gh --version
コマンドを使って、インストールされているバージョンを確認できます。 -
BBS2GH extension をインストールします。
Shell gh extension install github/gh-bbs2gh
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 は毎週更新されます。 最新バージョンを確実に使うため、拡張機能を更新してください。
gh extension upgrade github/gh-bbs2gh
gh extension upgrade github/gh-bbs2gh
手順 3: 環境変数を設定する
BBS2GH extension を使って GitHub Enterprise Cloud に移行するには、その前に、移行先の Organization にアクセスできる personal access token を作成してから、personal access token を環境変数として設定する必要があります。
また、Bitbucket Server のユーザー名とパスワードの環境変数を設定し、Bitbucket Server インスタンスが Windows で実行されている場合は SMB パスワードを設定する必要があります。
-
GitHub Enterprise Cloud 上の移行先 Organization に対して認証を行う personal access token (classic) を作成して記録し、トークンがすべての要件を満たしていることを確認します。 詳しくは、「Bitbucket サーバーからの移行のアクセスの管理」を参照してください。
-
環境変数を設定し、TOKEN は先ほど記録した personal access token、USERNAME は管理者またはスーパー管理者のアクセス許可を持つ Bitbucket Server アカウントのユーザー名、PASSWORD は Bitbucket Server アカウントのパスワードに置き換えます。
-
ターミナルを使っている場合は、
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"
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"
$env:GH_PAT="TOKEN" $env:BBS_USERNAME="USERNAME" $env:BBS_PASSWORD="PASSWORD" # If your Bitbucket Server instance runs on Windows $env:SMB_PASSWORD="PASSWORD"
-
-
データ所在地付き GitHub Enterprise Cloud に移行する場合は、便宜上、エンタープライズのベース API URL の環境変数を設定します。 次に例を示します。
Shell export TARGET_API_URL="https://api.octocorp.ghe.com"
export TARGET_API_URL="https://api.octocorp.ghe.com"
この変数は、GitHub CLI で実行するコマンドの
--target-api-url
オプションと共に使用します。
手順 4: BLOB ストレージを設定する
多くの Bitbucket Server インスタンスはファイアウォールの背後にあるため、GitHub CLI では、インターネットから到達可能なデータを格納するための中間的な場所として BLOB ストレージが使用されます。
最初に、移行するデータのアーカイブを生成し、ファイアウォールの背後から BLOB ストレージにデータをプッシュします。
GitHub CLI は、次の BLOB ストレージ プロバイダーをサポートしています。
- アマゾン ウェブ サービス (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/*"
]
}
]
}
Note
GitHub Enterprise Importer は、移行の完了後に AWS からアーカイブを削除しません。 ストレージ コストを減らすため、一定期間後にアーカイブが自動削除されるよう構成することをお勧めします。 詳しくは、AWS のドキュメントの「バケットのライフサイクル設定の指定」をご覧ください。
移行を実行する準備ができたら、リージョン、アクセス キー、シークレット キー、セッション トークンなどの AWS 資格情報を GitHub CLI に提供します (必要な場合)。 引数として渡すことも、AWS_REGION
、AWS_ACCESS_KEY_ID
、AWS_SECRET_ACCESS_KEY
、AWS_SESSION_TOKEN
という環境変数を設定することもできます。
また、--aws-bucket-name
引数を使って S3 バケットの名前で渡す必要があります。
Azure Blob Storage ストレージ アカウントの設定
Azure でストレージ アカウントを作成し、接続文字列を記録しておきます。 詳しくは、Microsoft Docs の「ストレージ アカウント アクセス キーを管理する」をご覧ください。
Note
GitHub Enterprise Importer は、移行の完了後に Azure Blob Storage からアーカイブを削除しません。 ストレージ コストを減らすため、一定期間後にアーカイブが自動削除されるよう構成することをお勧めします。 詳しくは、Microsoft Docs の「データ ライフサイクルを自動管理してコストを最適化する」をご覧ください。
移行を実行する準備ができたら、接続文字列を引数として GitHub CLI に渡すか、AZURE_STORAGE_CONNECTION_STRING
という名前の環境変数を使って渡すことができます。
ネットワーク アクセスの許可
ストレージ アカウントでファイアウォール規則を構成している場合は、移行先の IP 範囲へのアクセスを許可していることを確認します。 「Bitbucket サーバーからの移行のアクセスの管理」を参照してください。
手順 5: リポジトリを移行する
gh bbs2gh migrate-repo
コマンドを使ってリポジトリを移行できます。
既定では、リポジトリを移行するときに、BBS2GH extension of the GitHub CLI によって次の手順が行われます。
- Bitbucket Server インスタンスに接続し、リポジトリごとに移行アーカイブを生成します
- SFTP (Linux) または SMB (Windows) を使用して、移行アーカイブを Bitbucket Server インスタンスから BBS2GH extension of the GitHub CLI を実行しているコンピューターにダウンロードします
- 移行アーカイブを任意の BLOB ストレージ プロバイダーにアップロードします
- BLOB ストレージ プロバイダーに格納されているアーカイブの URL を使用して、GitHub Enterprise Cloud で移行を開始します
- ローカル コンピューターから移行アーカイブを削除します。 (移行が完了したら、BLOB ストレージ プロバイダーからアーカイブを手動で削除する必要があります。)
または、GitHub CLI を使ってアーカイブを生成し、そのアーカイブを手動でダウンロードしてから、GitHub CLI を使って移行を続けることもできます。
移行アーカイブをダウンロードすることを GitHub CLI に許可する
1 つのリポジトリを移行するには、gh bbs2gh migrate-repo
コマンドを使います。
以下のようにアクセスできるコンピューターからこの手順に従う必要があります。
- HTTPS 経由で Bitbucket Server インスタンス
- Bitbucket Server インスタンスが Linux 上で実行されている場合は、SFTP 経由で Bitbucket Server インスタンス。 一般に、SSH 経由でサーバーにアクセスできる場合は、SFTP を使用することもできます。
- Bitbucket Server インスタンスが Windows で実行されている場合は、SMB 経由で Bitbucket Server インスタンス
- 選んだ BLOB ストレージ プロバイダー
gh bbs2gh migrate-repo --bbs-server-url BBS-SERVER-URL \ --bbs-project PROJECT --bbs-repo CURRENT-NAME \ --github-org DESTINATION --github-repo NEW-NAME \ # If you are migrating to GHE.com: --target-api-url TARGET-API-URL # If your Bitbucket Server instance runs on Linux: --ssh-user SSH-USER --ssh-private-key PATH-TO-KEY # If your Bitbucket Server instance runs on Windows: --smb-user SMB-USER # If you're using AWS S3 as your blob storage provider: --aws-bucket-name AWS-BUCKET-NAME # If you are running a Bitbucket Data Center cluster or your Bitbucket Server is behind a load balancer: --archive-download-host ARCHIVE-DOWNLOAD-HOST
gh bbs2gh migrate-repo --bbs-server-url BBS-SERVER-URL \
--bbs-project PROJECT --bbs-repo CURRENT-NAME \
--github-org DESTINATION --github-repo NEW-NAME \
# If you are migrating to GHE.com:
--target-api-url TARGET-API-URL
# If your Bitbucket Server instance runs on Linux:
--ssh-user SSH-USER --ssh-private-key PATH-TO-KEY
# If your Bitbucket Server instance runs on Windows:
--smb-user SMB-USER
# If you're using AWS S3 as your blob storage provider:
--aws-bucket-name AWS-BUCKET-NAME
# 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-URL | Bitbucket Server インスタンスの URL |
PROJECT | 移行するリポジトリの Bitbucket Server プロジェクト用のキー |
CURRENT-NAME | 移行するリポジトリの名前 |
DESTINATION | 移行先の Organization の名前 |
NEW-NAME | 移行されたリポジトリに設定する名前 |
TARGET-API-URL | エンタープライズの GHE.com のサブドメインのベース API URL。 (例: https://api.octocorp.ghe.com )。 |
SSH-USER | Bitbucket Server インスタンスが Linux 上で実行されている場合、SFTP 経由で Bitbucket Server に接続するときに使うユーザー名 |
PATH-TO-KEY | Bitbucket Server インスタンスが Linux 上で実行する場合は、SSH 秘密キーへのパス (例: ~/.ssh/id_rsa )。 SSH キーの要件については、「Bitbucket サーバーからの移行のアクセスの管理」をご覧ください。 |
SMB-USER | Bitbucket Server インスタンスが Windows 上で実行されている場合、SMB 経由で Bitbucket Server に接続するときに使うユーザー名 |
AWS-BUCKET-NAME | AWS S3 バケットのバケット名 |
ARCHIVE-DOWNLOAD-HOST | SSH または SMB 経由で Bitbucket サーバー/データ センターのインスタンスに接続するために使うホスト。 これを指定する必要があるのは、Bitbucket Data Center クラスターを使っている場合、または Bitbucket サーバーがロード バランサーの背後にある場合のみです。 |
Note
Renci.SshNet
を示すエラーが発生する場合は、CLI で移行アーカイブをダウンロードするためのサーバーへの SFTP 接続を確立する際に問題が発生しています。 これらの Issue をトラブルシューティングする方法については、「GitHub Enterprise Importer を使用した移行のトラブルシューティング」を参照してください。
移行アーカイブを手動でダウンロードする
BBS2GH extension of the GitHub CLI の既定では、SFTP または SMB を使って Bitbucket Server インスタンスからの移行アーカイブのダウンロードを含め、移行全体が実行されます。
ただし、サーバーが SFTP アクセスを提供していない場合など、移行アーカイブを手動でダウンロードすることを好むお客様もいます。 その場合は、GitHub CLI を使ってアーカイブを生成し、そのアーカイブを手動でダウンロードしてから、GitHub CLI を使って移行を続けることもできます。
以下のようにアクセスできるコンピューターからこの手順に従う必要があります。
- HTTPS 経由で Bitbucket Server インスタンス
- 選んだ BLOB ストレージ プロバイダー
まず、次の引数のみを指定して gh bbs2gh migrate-repo
コマンドを実行します。
gh bbs2gh migrate-repo --bbs-server-url BBS-SERVER-URL \ --bbs-project PROJECT \ --bbs-repo CURRENT-NAME
gh bbs2gh migrate-repo --bbs-server-url BBS-SERVER-URL \
--bbs-project PROJECT \
--bbs-repo CURRENT-NAME
上のコマンドのプレースホルダーを次の値に置き換えます。
プレースホルダー | 値 |
---|---|
BBS-SERVER-URL | Bitbucket Server インスタンスの 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
コマンドをもう一度実行します。
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 \ # If you're using AWS S3 as your blob storage provider: --aws-bucket-name AWS-BUCKET-NAME # If you are migrating to GHE.com: --target-api-url TARGET-API-URL
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 \
# If you're using AWS S3 as your blob storage provider:
--aws-bucket-name AWS-BUCKET-NAME
# If you are migrating to GHE.com:
--target-api-url TARGET-API-URL
上のコマンドのプレースホルダーを次の値に置き換えます。
プレースホルダー | 値 |
---|---|
ARCHIVE-PATH | お使いのインスタンスからダウンロードした Bitbucket Server 移行アーカイブのパス |
DESTINATION | 移行先の Organization の名前 |
NEW-NAME | 移行されたリポジトリに設定する名前 |
BBS-SERVER-URL | Bitbucket Server インスタンスの URL |
PROJECT | 移行するリポジトリの Bitbucket Server プロジェクト用のキー |
CURRENT-NAME | 移行するリポジトリの名前 |
AWS-BUCKET-NAME | AWS S3 バケットのバケット名 |
TARGET-API-URL | エンタープライズの GHE.com のサブドメインのベース API URL。 (例: https://api.octocorp.ghe.com )。 |
移行を取り消す
移行を取り消す場合は、MIGRATION-ID を abort-migration
返された( migrate-repo
から)ID に置き換えて、コマンドを使用します。
gh bb2gh abort-migration --migration-id MIGRATION-ID
gh bb2gh abort-migration --migration-id MIGRATION-ID
手順 6: 移行を検証し、エラー ログを確認する
移行が完了したら、移行ログを確認することをお勧めします。 詳しくは、「GitHub Enterprise Importer の移行ログへのアクセス」を参照してください。
移行したリポジトリで健全性チェックを確認することをお勧めします。
手順 7: 複数のリポジトリを移行する
複数のリポジトリを GitHub Enterprise Cloud に一度に移行したい場合は、GitHub CLI を使って移行スクリプトを生成します。 結果のスクリプトには、リポジトリごとに 1 つの移行コマンドのリストが含まれます。
Note
スクリプトを生成すると、PowerShell スクリプトが出力されます。 ターミナルを使っている場合は、.ps1
ファイル拡張子を持つスクリプトを出力し、Mac または Linux 用の PowerShell をインストールして実行する必要があります。
移行スクリプトの生成
HTTPS 経由で Bitbucket Server インスタンスにアクセスできるコンピューターからこの手順に従う必要があります。
移行スクリプトを生成するには、gh bbs2gh generate-script
コマンドを実行します。
gh bbs2gh generate-script --bbs-server-url BBS-SERVER-URL \ --github-org DESTINATION \ --output FILENAME \ # If you are migrating to GHE.com: --target-api-url TARGET-API-URL # If your Bitbucket Server instance runs on Linux: --ssh-user SSH-USER --ssh-private-key PATH-TO-KEY # If your Bitbucket Server instance runs on Windows: --smb-user SMB-USER # If you are running a Bitbucket Data Center cluster or your Bitbucket Server is behind a load balancer: --archive-download-host ARCHIVE-DOWNLOAD-HOST
gh bbs2gh generate-script --bbs-server-url BBS-SERVER-URL \
--github-org DESTINATION \
--output FILENAME \
# If you are migrating to GHE.com:
--target-api-url TARGET-API-URL
# If your Bitbucket Server instance runs on Linux:
--ssh-user SSH-USER --ssh-private-key PATH-TO-KEY
# If your Bitbucket Server instance runs on Windows:
--smb-user SMB-USER
# 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-URL | Bitbucket Server インスタンスの URL |
DESTINATION | 移行先の Organization の名前 |
FILENAME | 結果の移行スクリプトのファイル名 ターミナルを使っている場合は、生成されたスクリプトの実行に PowerShell が必要なので、 .ps1 ファイル拡張子を使います。 Mac 用または Linux 用の PowerShell をインストールできます。 |
TARGET-API-URL | エンタープライズの GHE.com のサブドメインのベース API URL。 (例: https://api.octocorp.ghe.com )。 |
SSH-USER | Bitbucket Server インスタンスが Linux 上で実行されている場合、SFTP 経由で Bitbucket Server に接続するときに使うユーザー名 |
PATH-TO-KEY | Bitbucket Server インスタンスが Linux 上で実行する場合は、SSH 秘密キーへのパス (例: ~/.ssh/id_rsa )。 SSH キーの要件については、「Bitbucket サーバーからの移行のアクセスの管理」をご覧ください。 |
SMB-USER | Bitbucket Server インスタンスが Windows 上で実行されている場合、SMB 経由で Bitbucket Server に接続するときに使うユーザー名 |
ARCHIVE-DOWNLOAD-HOST | SSH または SMB 経由で Bitbucket サーバー/データ センターのインスタンスに接続するために使うホスト。 これを指定する必要があるのは、Bitbucket Data Center クラスターを使っている場合、または Bitbucket サーバーがロード バランサーの背後にある場合のみです。 |
移行スクリプトの確認
スクリプトを生成したら、ファイルを確認し、必要に応じてスクリプトを編集します。
- 移行したくないリポジトリがある場合は、対応する行を削除するかコメントにします。
- 既定では、GitHub のリポジトリ名は
projectKey-repositoryName
規則に従います。 たとえば、キーOS
を持つopen-source
プロジェクトの一部であるairports
という名前の Bitbucket Server リポジトリは、GitHub ではOS-airports
と呼ばれます。 GitHub でリポジトリに別の名前を使う場合は、対応する--github-repo
フラグの値を更新します。
BBS2GH を GitHub CLI の拡張機能としてではなくスタンドアロン バイナリとしてダウンロードした場合は、生成されたスクリプトを更新して、gh bbs2gh
ではなくバイナリを実行する必要があります。
移行スクリプトの実行
リポジトリを移行するには、生成されたスクリプトを実行します。
以下のようにアクセスできるコンピューターからこの手順に従う必要があります。
- HTTPS 経由で Bitbucket Server インスタンス
- Bitbucket Server インスタンスが Linux 上で実行されている場合は、SFTP 経由で Bitbucket Server インスタンス。 一般に、SSH 経由でサーバーにアクセスできる場合は、SFTP を使用することもできます。
- Bitbucket Server インスタンスが Windows で実行されている場合は、SMB 経由で Bitbucket Server インスタンス
- 選んだ BLOB ストレージ プロバイダー
スクリプトを実行する前に、BLOB ストレージ プロバイダーに対する認証を行うために追加の環境変数を設定する必要があります。
- AWS S3 の場合は、次の環境変数を設定します。
AWS_ACCESS_KEY_ID
: バケットのアクセス キー IDAWS_SECRET_ACCESS_KEY
: バケットの秘密鍵AWS_REGION
: バケットが配置されている AWS リージョンAWS_SESSION_TOKEN
: AWS の一時的な資格情報を使用している場合のセッション トークン (AWS ドキュメントの「AWS リソースで一時的な資格情報を使用する」を参照してください)
- Azure Blob Storage の場合は、
AZURE_STORAGE_CONNECTION_STRING
を Azure ストレージ アカウントの接続文字列に設定します。
ストレージ アカウントのアクセス キーを使う接続文字列のみがサポートされています。 Shared Access Signature (SAS) を使う接続文字列はサポートされていません。 ストレージ アカウントのアクセス キーについて詳しくは、Azure のドキュメントの「ストレージ アカウント アクセス キーを管理する」をご覧ください。
複数のリポジトリを移行するには、上で生成したスクリプトを実行します。 次のコマンドの FILENAME を、スクリプトの生成時に指定したファイル名に置き換えます。
-
ターミナルを使っている場合は、
./
を使います。Shell ./FILENAME
./FILENAME
-
PowerShell を使っている場合は、
.\
を使います。Shell .\FILENAME
.\FILENAME