BitbucketからGitLabへの移行ガイド
参考ドキュメント: GitLab ドキュメント
ドキュメントURL:
- Bitbucket Cloud: https://docs.gitlab.com/user/import/bitbucket_cloud/
- Bitbucket Server: https://docs.gitlab.com/user/import/bitbucket_server/
対象: GitLab.com、GitLab Self-Managed、GitLab Dedicated（Free、Premium、Ultimate）
1. まず確認: どのBitbucketを使っていますか？
2. 移行で何ができるか/できないか
Bitbucket Cloud からの移行
✅ 移行される項目:
- リポジトリの説明
- Gitリポジトリデータ（コード、コミット履歴、ブランチ、タグ）
- Issues（コメント含む）
- Pull Requests（コメント含む）
- マイルストーン
- Wiki
- ラベル
- LFSオブジェクト（大容量ファイル）
❌ 移行されない項目:
- Pull Requestの承認（Approval）
- 承認ルール（Approval Rules）
- CI/CD設定（Bitbucket Pipelines）
- Webhooks
- デプロイキー
- 環境変数・シークレット
⚠️ 制限事項:
- フォークからのPull Requestは空のMerge Requestになる
Bitbucket Server からの移行
✅ 移行される項目:
- リポジトリの説明
- Gitリポジトリデータ（コード、コミット履歴、ブランチ、タグ）
- Pull Requests（コメント、ユーザーメンション、レビュアー、マージイベント含む）
- コードコメント（範囲外のコメントはMerge Requestのコメントとして挿入）
- スレッド（複数レベルは統合される）
- プロジェクトフィルター（部分一致検索は非対応、前方一致のみ）
- LFSオブジェクト
❌ 移行されない項目:
- Issues（Bitbucket Serverには存在しない）
- Wiki
- マイルストーン（Bitbucket Serverには存在しない）
- Markdown内の添付ファイル
- タスクリスト
- 絵文字リアクション
- Pull Requestの承認
- 承認ルール
- CI/CD設定（Jenkins、Bamboo統合）
- Webhooks
- デプロイキー
- 環境変数・シークレット
比較表
| カテゴリ | Bitbucket Cloud | Bitbucket Server |
|---|---|---|
| 基本データ | ||
| リポジトリ・コード | ✅ | ✅ |
| Pull Requests | ✅ | ✅ |
| コードコメント | ✅ | ✅ |
| LFSオブジェクト | ✅ | ✅ |
| Issue管理 | ||
| Issues | ✅ | ❌（存在しない） |
| マイルストーン | ✅ | ❌（存在しない） |
| ラベル | ✅ | ❌ |
| ドキュメント | ||
| Wiki | ✅ | ❌ |
| 添付ファイル | ✅ | ❌ |
| 承認・レビュー | ||
| PR承認 | ❌ | ❌ |
| 承認ルール | ❌ | ❌ |
| レビュアー情報 | ✅ | ✅ |
| 設定・統合 | ||
| CI/CD | ❌ | ❌ |
| Webhooks | ❌ | ❌ |
| デプロイキー | ❌ | ❌ |
| 事前準備 | ||
| 重要度 | ユーザー連携（必須） | 管理者トークン（必須） |
| ユーザーマッピング | 事前設定必須 | 移行後に設定可能 |
| 所要時間（中規模） | 30分-1時間 | 30分-2時間 |
3. 移行の全体フロー
Bitbucket Cloud
Bitbucket Server
4. 事前準備チェックリスト
Bitbucket Cloud
必須タスク（移行2-3日前）:
- 全メンバー: Bitbucketアカウント設定でユーザー名を確認
- 全メンバー: Atlassianアカウント設定で公開名がBitbucketユーザー名と一致するよう修正
- 全メンバー: GitLabプロフィール(https://gitlab.com/-/profile/account) でBitbucketアカウント連携
- 実行者: GitLabでMaintainerロールを確認
重要: ユーザー連携を忘れると、全ての履歴がインポート実行者の名前になります。
注意事項:
- フォークからのPRは空のMerge Requestになる
- PR承認と承認ルールは移行されない
Bitbucket Server
必須タスク（移行1-2日前）:
- 管理者: Bitbucket Serverで管理者権限を持つPersonal Access Tokenを生成
- 管理者: GitLabからBitbucket Serverへのネットワーク接続を確認
- 実行者: GitLabでMaintainerロールを確認
推奨タスク:
- ユーザーのメールアドレス対応表を準備（移行後マッピング用）
注意事項:
- 管理者権限トークンがないと一部データが移行されない
- 大規模プロジェクト（数千PR、数百GiB）は数時間かかる
5. インポート手順
共通手順
- GitLabで「Create new」(+) → 「New project/repository」
- 「Import project」を選択
- 「Bitbucket Cloud」または「Bitbucket Server」を選択
- 認証して接続
- プロジェクトを選択して「Import」をクリック
Bitbucket Server のみ: 移行後マッピング（推奨）
インポート完了後:
- GitLab管理画面 → 「Import and export」→「Import contributions」
- 「Map users by email」で自動マッピング
- 失敗したユーザーは手動で調整
- 「Save mappings」で保存
詳細: https://docs.gitlab.com/user/import/mapping/
6. 移行後の確認
基本確認（両方）
- すべてのリポジトリがインポートされた
- コミット履歴が保持されている
- Merge Requestが正しくインポートされた
- プライベート/パブリック設定が正しい
Cloudのみ
- Issuesがインポートされた
- Wikiがインポートされた
- フォークからのPRが空MRになっていることを確認（該当する場合）
Serverのみ
- ユーザーマッピングを完了した
- コードコメントが正しくインポートされた
- LFSオブジェクトが正しくダウンロードできる
再設定が必要な項目（両方）
- CI/CDパイプライン（Bitbucket Pipelines/Jenkins/Bambooから移行）
- Webhooks
- デプロイキー
- ブランチ保護ルール
- 環境変数
7. よくあるトラブルと対処法
Cloud: ユーザーマッピングが失敗する
原因: Bitbucketアカウント連携後にユーザー名を変更した
対処:
- GitLab APIで「extern_uid」が現在のBitbucket公開名と一致するか確認
- 一致しない場合、GitLabでBitbucketアカウントを再連携
- プロジェクトを削除して再インポート
Server: LFSオブジェクトがダウンロードできない
原因: トークンに特殊文字が含まれている
対処: 特殊文字を含まないトークンを使用して再インポート
共通: インポートが途中で止まる
対処:
- 30分待ってもインポートが完了しない場合
- 「Re-import」で再実行
- それでも解決しない場合はGitLabサポートに連絡
Server: 「Import URL is blocked」エラー
原因: Bitbucket Serverのプロキシ設定の問題
対処: Bitbucket Serverのserver.xmlでプロキシ設定を確認
詳細: https://confluence.atlassian.com/bitbucketserver/proxy-and-secure-bitbucket-776640099.html
8. 移行後のBitbucket処理
推奨スケジュール
Week 1-2: GitLabで作業、Bitbucketは参照用として保持
Week 3-4: Bitbucketを読み取り専用化
1-2ヶ月後: Bitbucketをアーカイブまたは削除
アーカイブ方法
Cloud: リポジトリ設定 → 「Archive repository」
Server: 管理者がプロジェクトをアーカイブまたは読み取り専用化
9. まとめ
成功のポイント
Bitbucket Cloud:
- ✅ 全メンバーがBitbucketアカウント連携を完了（最重要）
- ✅ フォークからのPRは空MRになることを理解
- ✅ 所要時間を事前に見積もる
Bitbucket Server:
- ✅ 管理者権限トークンを準備（最重要）
- ✅ ネットワーク接続を確認
- ✅ 移行後マッピングを活用（GitLab 17.8以降）
- ✅ 大規模プロジェクトは時間に余裕を持つ
共通:
- ✅ 移行後にCI/CD、Webhooksなどを再設定
- ✅ チームに事前通知と移行後の案内
- ✅ データの完全性を確認してから本格運用
次のステップ
移行完了後:
- GitLab CI/CDでパイプラインを構築
- Merge Requestの承認ルールを設定
- ブランチ保護ルールを設定
- GitLabの高度な機能を探索（Auto DevOps、Container Registry等）
10. 関連リソース
公式ドキュメント:
- Bitbucket Cloud移行: https://docs.gitlab.com/user/import/bitbucket_cloud/
- Bitbucket Server移行: https://docs.gitlab.com/user/import/bitbucket_server/
- 移行後マッピング: https://docs.gitlab.com/user/import/mapping/
サポート:
- GitLab Forum: https://forum.gitlab.com/c/gitlab-administration/import-migration/
- GitLabサポート: https://support.gitlab.com/
トレーニング:
- GitLab University: https://university.gitlab.com/
- GitLab 101コース: https://university.gitlab.com/learn/course/external/view/elearning/2/gitlab-101