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インポーターは、 プロジェクト作成画面から直接利用できます。処理はバックグラウンドジョブとして実行されるため、インポートを開始したらあとは待つだけ。 プロジェクトデータの大半は自動で移ります。一部の項目はオプションの切り替えになっていたり、 事前に知っておきたい注意点があったりします。
移行対象と方式を、次の表にまとめました。
| データ | 状態 |
|---|---|
| Gitリポジトリ、ブランチ、タグ、コミット履歴 | ✅ 自動。オープンなプルリクエストのフォークブランチも含みます。 |
| イシュー | ✅ 自動 |
| プルリクエスト(マージリクエストに変換) | ✅ 自動。レビュー、レビューコメント、提案、アサインされたレビュアー、「マージした人」の情報も含みます。 |
| イシューとプルリクエストのコメント | ✅ 自動 |
| ラベルとマイルストーン | ✅ 自動 |
| リリースノートの内容 | ✅ 自動 |
| Wikiページ | ✅ 自動 |
| ブランチ保護ルール | ✅ 自動 |
| イシューとプルリクエストのイベント | ✅ 自動 |
| コラボレーター(メンバー) | ⚠️ 条件付き。オプションの切り替え(デフォルトでオン)。read:orgスコープが必要で、GitHubのロールはGitLabのロールにマッピングされます(下記参照)。GitHub Enterprise Cloudのカスタムロールは非対応のため、手動で追加します。 |
| Markdownの添付ファイル(説明、コメント、リリース内) | ⚠️ 条件付き。オプションの切り替え。プライベートリポジトリでは、2023年5月より前の添付ファイルはインポートできません(GitHub側の制限)。GitHub Enterprise Serverでは画像と動画のみが対象です。 |
| 大量のコメント(約30,000件以上) | ⚠️ 条件付き。GitHubのイシューごとのAPI制限を回避するため、代替コメントインポートを有効にします。2017年より前のコメントは別スレッドとしてインポートされる場合があります。 |
| Git LFSオブジェクト | ⚠️ 条件付き。インポート実行前に、移行先プロジェクトでLFSを有効にする必要があります。有効になっていないと、オブジェクトは通知なくスキップされます。 |
| GitHub Actionsのワークフロー | 🛠️ 手動(AI支援あり)。.gitlab-ci.ymlに変換します。大部分はGitLab Duoに任せられます。 |
| シークレット → CI/CD変数 | 🛠️ 手動。パイプラインを実行する前に、シークレットをCI/CD変数として再作成します(マスク/保護の指定を忘れずに)。 |
| 必須ステータスチェック | 🛠️ 手動。外部ステータスチェックとして再作成します。 |
| GitHubのOrganization/グループ構成 | ❌ 移行対象外。同等の構造になるよう、GitLab側でグループとサブグループを作成します。 |
ロールのマッピング
GitHubとGitLabでは命名規則が異なるため、移行時にマッピングが行われます。コラボレーターをインポートすると、GitHubのロールは次のようにGitLabのロールへ対応づけられます。
| GitHubのロール | GitLabのロール |
|---|---|
| Read | ゲスト |
| Triage | レポーター |
| Write | デベロッパー |
| Maintain | メンテナー |
| Admin | オーナー |
前提要件
前提要件は、年々シンプルになっています。特に大きな変化は、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におすすめ)
多くのチームにとって、これが最短ルートです。
- グループを開き、「プロジェクトを作成」→「プロジェクトをインポート」→「GitHub」 を選択します(gitlab.com/projects/new#import_projectから直接開いても同じです)。
- 「Authenticate with GitHub」 ボタンを押し、OAuthアプリケーションを承認します。
- Organizationのリポジトリを扱う場合は、Organization名の横にある 「Grant」 をクリックしてアクセスを認可します。
- 「Owner/Collaborated/Organization」 タブでリポジトリを絞り込み、インポート対象を選択します。ここで名前の変更や、移行先GitLabネームスペースの指定も行えます。
- オプションの切り替え(下表を参照)を設定し、「Import」 をクリックします。処理はバックグラウンドジョブとして走るため、画面を離れて後から確認しても問題ありません。
オプションの切り替え
| 切り替え | デフォルト | 使うタイミング |
|---|---|---|
| コラボレーターをインポート | オン | プロジェクトメンバーをロールマッピング付きで移行したいとき |
| Markdown添付ファイルをインポート | オフ | 説明、コメント、リリースに埋め込まれた画像やファイルも移したいとき |
| 代替コメントインポートを使用 | オフ | コメントが約30,000件以上あり、GitHubのAPI制限に達しているとき |
方法2:パーソナルアクセストークン(OAuth未設定の場合)
OAuthが設定されていない環境では、トークンによる認証を使います。
github.com/settings/tokens/newで、repoスコープを付与したクラシックパーソナルアクセストークンを作成します(コラボレーターやLFSを移行する場合はread:orgも追加)。なお、Fine-grainedトークンには対応していません。- GitLabでグループを開き、 「プロジェクトを作成」→「プロジェクトをインポート」→「GitHub」 を選択します。
- トークンを貼り付けて 「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が必要になります。
インポート結果の確認
インポートが完了したら、簡単な健全性チェックを行います。
- 新しいプロジェクトを開き、ステータスバナーがscheduled → started → finishedと進むことを確認します。 partially completedと表示された場合は、どのエンティティが失敗したのかを掘り下げます。
- ブランチ、タグ、コミットSHA、イシュー、マージリクエスト、ラベル、マイルストーンの件数を、移行元と突き合わせます。
- インポートされた項目に 「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つのプラットフォーム間できれいに対応しています。
| GitHub Actions | GitLab CI/CD |
|---|---|
.github/workflows/*.yml | .gitlab-ci.yml |
| ワークフロー | パイプライン |
| ジョブ | ジョブ |
| ジョブ内のステップ | script:内の1行 |
イベントトリガー(on:) | rules:/workflow: |
runs-on:/container: | image:とRunnerのtags: |
| Actions Marketplace | CI/CDコンポーネント |
| シークレット | CI/CD変数 |
strategy.matrix | parallel.matrix |
actions/checkout | 組み込み(GitLabが自動でクローン) |
actions/cache | cache:キーワード |
actions/upload-artifact | artifacts:キーワード |
押さえておきたい大きな違いが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のインポーターは、次のプラットフォームからのワンクリック移行に対応しています。
次の移行元については、ドキュメントを用意しています。
最後までお読みいただき、ありがとうございました。新しいプラットフォームを採用するうえで、移行は必ずしも恐れるべき工程ではありません。 データの移行はGitLabが自動で行い、CI/CDの変換はGitLab Duoが引き受けます。開発チームは、本来のリリース作業に集中できるはずです。 詳しくは以下のリンクをご覧ください。




