GitHubからGitLabへの移行を、驚くほど簡単に

GitLabへの移行を検討し始めたとき、最初に浮かぶ疑問はたいてい同じです。移行はどれくらい大変なのか。多くのDevSecOpsチームにとって、「大がかりな作業になりそうだ」という不安こそが、AIネイティブな単一のDevSecOpsプラットフォームへ踏み出す最大の障壁になっています。

しかし、GitLabへの移行はかつてないほど簡単になりました。組み込みのインポーターが、プロジェクトデータの大半をバックグラウンドで自動的に移行してくれます。さらに、これまで人手を要してきたCI/CDパイプラインの書き換えも、いまやその多くをGitLab Duoが担当。AIネイティブアシスタントであるDuoが、GitHub ActionsのワークフローをGitLab CI/CDへ変換します。

本記事では、移行の全体像を最初から最後まで解説します。

• GitHubからGitLabへ移行されるデータ：自動、条件付き、手動の区分
• GitLab 18.xで実際に必要な前提要件（思っているより少なめ）
• インポートの3つの方法：UI（OAuth）、パーソナルアクセストークン、一括移行向けのREST API
• GitHub ActionsをGitLab CI/CDへ変換する方法：従来のやり方とGitLab Duoを使った近道
• GitLabがインポートに対応しているその他のプラットフォーム

さっそく始めましょう。

GitHubからGitLabへ移行されるデータ

GitLabの組み込みGitHubインポーターは、 プロジェクト作成画面から直接利用できます。処理はバックグラウンドジョブとして実行されるため、インポートを開始したらあとは待つだけ。 プロジェクトデータの大半は自動で移ります。一部の項目はオプションの切り替えになっていたり、 事前に知っておきたい注意点があったりします。

移行対象と方式を、次の表にまとめました。

ロールのマッピング

GitHubとGitLabでは命名規則が異なるため、移行時にマッピングが行われます。コラボレーターをインポートすると、GitHubのロールは次のようにGitLabのロールへ対応づけられます。

前提要件

前提要件は、年々シンプルになっています。特に大きな変化は、GitHubのすべての作成者がGitLab上で一致する公開メールアドレスを持つ必要がなくなったこと。現在はユーザーコントリビューションマッピング（GitLab 17.8以降）により、GitLabが帰属情報を自動的に処理します。詳しくは後述。

GitHub.comまたはGitHub Enterprise Serverから、GitLab.comあるいはGitLab Self-Managedインスタンスへインポートするには、次のものが必要です。

• インポート元となるGitHubプロジェクトへのアクセス権
• 移行先GitLabグループでのメンテナーまたはオーナーロール
• GitHubインポートソースが有効になっていること。GitLab.comではデフォルトで有効です。GitLab Self-Managedの場合は、管理者がインポートソースの設定から有効にします。
• GitHubのOrganizationがサードパーティアプリケーションのアクセスを制限していないこと（制限している場合は、認可時にアクセスを許可します）

状況によっては、次の条件も加わります。

• Git LFSオブジェクトを移行する場合：インポート前に、移行先プロジェクトでLFSを有効にします。
• コラボレーターを移行する場合：トークンにread:orgスコープが必要です。あわせて、GitHubプロジェクトでWriteまたはMaintain以上の権限が求められます。

メールアドレスの一致はもう不要

以前は、GitHubユーザーの公開メールアドレスとGitLabのメールアドレスが一致している場合にのみ、コントリビューション履歴がきれいに引き継がれました。現在は、一致するGitLabアカウントを持たない作成者、担当者、レビュアーについて、GitLabがプレースホルダーユーザーを作成し、そのコントリビューションを保持します。

インポート後は、グループのオーナーまたはメンテナーが 「メンバー」→「プレースホルダー」 へ進み、各プレースホルダーを実際のGitLabユーザーへ再割り当てします。あとは対象ユーザーが承認するだけ。つまり、まず移行を済ませ、帰属情報の整理は後から進められます。

インポートの実行

インポートの方法は3つあります。移行元と規模に合わせて選んでください。

方法1：GitHub OAuthを使ったUI操作（GitLab.comにおすすめ）

多くのチームにとって、これが最短ルートです。

1. グループを開き、「プロジェクトを作成」→「プロジェクトをインポート」→「GitHub」 を選択します（gitlab.com/projects/new#import_projectから直接開いても同じです）。
2. 「Authenticate with GitHub」 ボタンを押し、OAuthアプリケーションを承認します。
3. Organizationのリポジトリを扱う場合は、Organization名の横にある 「Grant」 をクリックしてアクセスを認可します。
4. 「Owner／Collaborated／Organization」 タブでリポジトリを絞り込み、インポート対象を選択します。ここで名前の変更や、移行先GitLabネームスペースの指定も行えます。
5. オプションの切り替え（下表を参照）を設定し、「Import」 をクリックします。処理はバックグラウンドジョブとして走るため、画面を離れて後から確認しても問題ありません。

オプションの切り替え

方法2：パーソナルアクセストークン（OAuth未設定の場合）

OAuthが設定されていない環境では、トークンによる認証を使います。

1. github.com/settings/tokens/newで、repoスコープを付与したクラシックパーソナルアクセストークンを作成します（コラボレーターやLFSを移行する場合はread:orgも追加）。なお、Fine-grainedトークンには対応していません。
2. GitLabでグループを開き、 「プロジェクトを作成」→「プロジェクトをインポート」→「GitHub」 を選択します。
3. トークンを貼り付けて 「Authenticate」 を選び、あとはOAuthの場合と同じ手順でリポジトリの選択と設定を進めます。

方法3：REST API（一括インポートとスクリプト化）

多数のリポジトリをまとめて移行したい場合、移行作業をスクリプト化したい場合、あるいは自分が所有していないパブリックリポジトリをインポートしたい場合は、インポートAPIを使います。

      curl --request POST \
  --url "https://gitlab.com/api/v4/import/github" \
  --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "personal_access_token": "<github_classic_pat>",
    "repo_id": 12345678,
    "target_namespace": "my-group",
    "new_name": "imported-project",
    "optional_stages": {
      "single_endpoint_notes_import": true,
      "attachments_import": true,
      "collaborators_import": true
    }
  }'

    

進捗の確認はこちらです。

      curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  "https://gitlab.com/api/v4/projects/<project_id>/import"

    

repoスコープを持つGitHubのクラシックPATと、apiスコープを持つGitLabのPATが必要になります。

インポート結果の確認

インポートが完了したら、簡単な健全性チェックを行います。

1. 新しいプロジェクトを開き、ステータスバナーがscheduled → started → finishedと進むことを確認します。 partially completedと表示された場合は、どのエンティティが失敗したのかを掘り下げます。
2. ブランチ、タグ、コミットSHA、イシュー、マージリクエスト、ラベル、マイルストーンの件数を、移行元と突き合わせます。
3. インポートされた項目に 「Imported」 バッジが付いているかを確認します。

再インポートは新しいコピーの作成になります（既存プロジェクトへのインポートは不可）。気になる点があれば、削除してやり直すのが確実です。

段階的な移行：GitHubとGitLabを並行運用する

移行は、ある日を境に一斉に切り替える必要はありません。多くのチームは段階的に進めています。GitHubを動かしたままGitLabを立ち上げ、 パイプラインを検証し、チーム単位でメンバーを移していく進め方。GitLabは移行期間中もGitHubと共存できるよう設計されているため、 一夜でスイッチを切り替えるのではなく、少しずつ導入していけます。

移行中に2つのプラットフォームを並行させる、主な方法は次のとおりです。

• プルミラーリングでリポジトリを同期する。 GitLabはGitHubリポジトリを プルミラーし、新しいブランチやコミットをスケジュールに沿って自動で取り込みます。 デベロッパーはGitHubへプッシュを続けながら、GitLab側は常に最新の状態。読み取り専用の実データを使ってCI/CDやワークフローを検証できるため、 誰の日常業務も変えずに済みます。切り替えの準備が整ったら、 プッシュミラーリングに変更すれば、GitLabでの変更が GitHubへ戻り、まだGitHubで作業しているチームにも反映されます。
• 外部リポジトリ向けCI/CDでGitHubリポジトリのパイプラインを実行する。 コードを移す前にGitLab CI/CDを評価したい場合の選択肢が、 外部リポジトリ向けCI/CD。 GitHubリポジトリをGitLabに接続し、プッシュとプルリクエストのたびにパイプラインを実行して、結果をGitHubへ返す仕組みです。 信頼できる情報源をGitHubに置いたまま、.gitlab-ci.ymlへの変換を実際のコミットで検証できます。
• CI/CDのステータスをGitHubへ返す。 GitHubインテグレーションを使うと、 GitLabがパイプラインとコミットのステータスをGitHubへ送信します。まだ移行していないデベロッパーも、使い慣れた画面でグリーンのチェックマークや ビルド結果を確認できます。
• チーム単位、リポジトリ単位で移行する。 インポーターはプロジェクト単位で動くため、まず1つのチームのリポジトリを移し、 定着を見届けてから次のグループへ進む、という順序が取れます。未移行のグループやサブグループは、その間GitHubを参照したままで問題ありません。

複数チーム・大規模リポジトリの移行を検討されている場合は、要件に合わせた移行計画をご相談いただけます。

GitHub ActionsをGitLab CI/CDへ移行する

CI/CDは、移行の中で自動化されない数少ない領域です。とはいえ、パイプラインを見直す絶好の機会。 中心となる概念の多くは、2つのプラットフォーム間できれいに対応しています。

押さえておきたい大きな違いが1つあります。GitLabではステージが順番に実行され、同一ステージ内のジョブは並列で実行されます。さらにneeds:を使えば、明示的な有向非巡回グラフ（DAG）を組み立てられます。

近道：ワークフローの変換はGitLab Duoに任せる

GitLab Duo Agent Platformには、GitHub Actionsのワークフローを.gitlab-ci.ymlへ書き換えるGitLab CI/CD変換フローが用意されています。ゼロから書き直すのではなく、できあがったドラフトをレビューするところから始められます。

GitLab Duoが役立つのは、変換だけではありません。移行の全工程が対象です。

• 計画：ワークフローファイルをもとに、リポジトリごとの移行計画と複雑度の評価を生成
• 変換：GitLab CI/CD変換フローが、マトリクスビルド、ジョブの依存関係、アーティファクト、条件付きルールを保ったまま、ActionsのワークフローをGitLab CI/CDへ書き換え
• ドキュメント：README、バッジ、リンクを更新（例：「Pull Request」→「Merge Request」）
• 検証：インポートされた件数を突き合わせ、欠けているものを洗い出し
• デバッグ：Fix CI/CD pipelineフローが失敗したジョブを分析し、原因を特定して修正案を提示
• クリーンアップ：キャッシュ、needs:によるDAG、CI/CDコンポーネントなど、GitLabらしい最適化を提案

GitLab Duo Agentic Chatは、イシュー、マージリクエスト、パイプラインからコンテキストを取り込み、プラットフォーム内で質問に答えます。Web IDEで.gitlab-ci.ymlを編集する際は、Duoコード提案も心強い味方に。

GitLab Duoを利用できない環境でも、構造化したプロンプトをフロンティアモデルに与えれば、同じ変換が十分に機能します。安定した結果が得られるプロンプトの例がこちらです。

このGitHub ActionsワークフローをGitLab CI/CDに変換してください。マトリクスビルド、ジョブの依存関係、アーティファクト、条件付きルールは保持すること。出力は有効な.gitlab-ci.ymlとします。

移行でAIアシスタントを使うときは、いくつかのガードレールを設けておきます。シークレット、トークン、社内ホスト名は絶対に貼り付けない。生成されたYAMLは必ずGitLabのCI Lintツールで検証する。そして出力は最終的なコミットではなく、レビュー前提のドラフトとして扱う。この3点です。

手作業の場合：対比で見る書き換え例

GitLab Duoにドラフトを作らせるにせよ、自分の手で書くにせよ、対応関係を目で見ておくと理解が早まります。まずは典型的なGitHub Actionsのビルド＆テストワークフローです。

      name: CI
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '18' }
      - run: npm install
      - run: npm test
      - run: npm run build

    

続いて、同じ内容をGitLab CI/CDで書いたものです。checkoutが消え（GitLabが自動でクローンします）、runs-onはimageになり、各ステップはscript:内の1行に変わります。

      stages: [test, build]

# GitLabが管理するSASTは、たった1行で追加できる
# 移行のタイミングで導入すると効果的
include:
  - template: Jobs/SAST.gitlab-ci.yml

test:
  stage: test
  image: node:18
  script:
    - npm install
    - npm test

build:
  stage: build
  image: node:18
  script:
    - npm install
    - npm run build
  artifacts:
    paths: [dist/]

    

マトリクスビルドの対応も同じくらい素直です。strategy.matrixがparallel.matrixになります。

      test:
  image: node:${NODE_VERSION}
  parallel:
    matrix:
      - NODE_VERSION: ['16', '18', '20']
  script:
    - npm install
    - npm test

    

条件付きデプロイはrules:へ対応します。

      deploy:
  stage: deploy
  script: ./deploy.sh
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

    

.gitlab-ci.ymlをコミットすれば、GitLabはすぐにパイプラインを実行します。 詳しくはGitLab CI/CDのドキュメントをご覧ください。

GitLabがインポートに対応しているその他のプラットフォーム

移行元はGitHubだけではありません。GitLabのインポーターは、次のプラットフォームからのワンクリック移行に対応しています。

• Bitbucket Cloud
• Bitbucket Server（Stash）
• FogBugz
• Gitea
• URLによるリポジトリ
• マニフェストファイル（AOSP）
• Jira（イシューのみ）

次の移行元については、ドキュメントを用意しています。

• SVN
• ClearCase
• CVS
• Perforce
• TFVC

最後までお読みいただき、ありがとうございました。新しいプラットフォームを採用するうえで、移行は必ずしも恐れるべき工程ではありません。 データの移行はGitLabが自動で行い、CI/CDの変換はGitLab Duoが引き受けます。開発チームは、本来のリリース作業に集中できるはずです。 詳しくは以下のリンクをご覧ください。

• GitLabを無料で試す
• 移行の支援サービスについて相談する
• GitHubからGitLabへのプロジェクト移行ドキュメント
• 利用できるプロジェクトインポーター
• GitLab Duo Agent Platform
• GitLab CI/CDのドキュメント