GitHubからGitLabへプロジェクトをインポートする

GitHub.comまたはGitHub EnterpriseからGitHubプロジェクトをインポートできます。プロジェクトをインポートしても、グループや組織の種類がGitHubからGitLabに移行またはインポートされることはありません。

インポートされたイシュー、マージリクエスト、コメント、およびイベントには、GitLabにインポート済みバッジが付いています。

ネームスペースは、gitlab.com/sidney-jonesやgitlab.com/customer-successなど、GitLabのユーザーまたはグループです。

GitLab UIを使用すると、GitHubインポーターは常にgithub.comドメインからインポートします。セルフホストのGitHub Enterprise Serverドメインからインポートする場合は、apiスコープを持つGitLabのアクセストークンを使用して、GitLabインポートAPI GitHubエンドポイントを使用します。

インポートする前に、ターゲットのネームスペースとターゲットのリポジトリ名を変更できます。

インポートプロセスの概要については、アクションを含むGitHubからGitLabへの移行方法を参照してください。

インポート期間を見積もる

GitHubからのすべてのインポートは異なり、実行するインポートの期間に影響します。ただし、テストでは、https://github.com/kubernetes/kubernetesを76時間でインポートしました。テスト時、そのプロジェクトは以下で構成されていました:

• 80,000件のプルリクエスト。
• 45,000件のイシュー。
• 約150万件のコメント。

前提要件

GitHubからプロジェクトをインポートするには、GitHubインポートソースを有効にする必要があります。そのインポートソースが有効になっていない場合は、GitLab管理者に有効にするように依頼してください。GitHubインポートソースは、GitLab.comでデフォルトで有効になっています。

権限とロール

GitHubインポータ―を使用するには、以下が必要です:

• ソースGitHubプロジェクトへのアクセス
• 宛先GitLabグループのメンテナーロール以上（GitLab 16.0で導入）

また、GitHubリポジトリが属する組織は、インポート先のGitLabインスタンスにサードパーティアプリケーションのアクセスポリシーの制限を課してはなりません。

ユーザーコントリビューションマッピングのアカウント

GitLab Self-ManagedおよびGitLab Dedicatedへのインポートにユーザーコントリビューションマッピングの古いメソッドを使用する前に、特定の要件を満たす必要があります。GitLab.comへのインポートでは、準備を必要としない改善されたメソッドを使用します。

これらの要件は次のとおりです:

• リポジトリ内の各GitHubの作成者と担当者は、公開されているメールアドレスを持っている必要があります。
• GitHubユーザーのメールアドレスは、GitLabのメールアドレスと一致している必要があります。
• GitHubのユーザーのメールアドレスがGitLabの2つ目のメールアドレスとして設定されている場合は、そのメールアドレスの確認を行う必要があります。

GitHub Enterpriseでは公開メールアドレスは不要なため、既存のアカウントに追加する必要がある場合があります。

既知の問題

• 2017年より前に作成されたGitHubのプルリクエストのコメント(GitLabでは差分ノートとして知られています)は、個別のスレッドでインポートされます。これは、2017年より前のコメントにはin_reply_to_idが含まれていないGitHub APIの制限が原因で発生します。

• GitLab 18.3以前では、GitHub Enterprise Serverインスタンス上のリポジトリからのMarkdown添付ファイルはインポートされません。GitLab 18.4以降:

  • Markdown添付ファイルのビデオファイルと画像ファイルのみがインポートされます。
  • その他のファイル添付ファイルはインポートされません。

• 既知の問題のため、GitHub自動マージを使用したプロジェクトをインポートする場合、コミットがGitHub内部GPGキーで署名されていると、GitLabにインポートされたプロジェクトにはunverifiedとラベル付けされたマージコミットが含まれている可能性があります。

• GitLabでは、2023年5月9日より前にプライベートリポジトリにアップロードされたGitHub Markdown画像添付ファイルをインポートできません。この問題が発生した際に問題の解決にご協力いただける場合、サンプルリポジトリを提供の上、イシュー424046にコメントを追加してください。こちらから改めてご連絡いたします。

• GitLab固有の参照の場合、GitLabはイシューに#文字、マージリクエストに!文字を使用します。ただし、GitHubでは、イシューとプルリクエストの両方に#文字のみを使用します。インポート時は、:

  • コメントノートの場合、GitLabは参照がイシューとマージリクエストのどちらを指しているかを判断できないため、GitLabはイシューへのリンクのみを作成します。
  • イシューまたはマージリクエストの説明の場合、GitLabはインポートされた対応するものがまだ宛先に作成されていない可能性があるため、参照へのリンクを作成しません。

GitHubリポジトリをGitLabにインポートする

GitHubリポジトリは、次のいずれかの方法でインポートできます:

• GitHub OAuthを使用する
• GitHubパーソナルアクセストークンを使用する
• APIを使用する

github.comからインポートする場合は、任意のメソッドでインポートできます。Self-Hosted GitHub Enterprise Serverのお客様は、APIを使用する必要があります。

GitHub OAuthを使用する

GitLab.comまたはGitHub OAuthが設定されているGitLab Self-Managedにインポートする場合は、GitHub OAuthを使用してリポジトリをインポートできます。

この方法には、バックエンドが適切な権限でアクセストークンを交換することから、パーソナルアクセストークン（PAT）を使用するよりも利点があります。

1. 左側のサイドバーの上部にある新規作成（ ）と新規プロジェクト/リポジトリを選択します。
2. プロジェクトのインポートを選択し、GitHubを選択します。
3. Authorize with GitHub（GitHubで認証）を選択します。
4. インポートするリポジトリを選択するに進みます。

これらの手順を以前に実行した後、別の方法を使用してインポートを実行するには、GitLabアカウントからサインアウトして再度サインインしてください。

GitHubパーソナルアクセストークンを使用する

GitHubパーソナルアクセストークンを使用してGitHubリポジトリをインポートするには、次の手順に従います:

1. GitHubパーソナルアクセストークンを生成します。従来のパーソナルアクセストークンのみがサポートされています。
   1. https://github.com/settings/tokens/newに移動します。
   2. メモフィールドに、トークンの説明を入力します。
   3. repoスコープを選択します。
   4. オプション。コラボレーターをインポートするか、プロジェクトにGit LFSファイルがある場合は、read:orgスコープを選択します。
   5. Generate token（トークンを生成）を選択します。
2. GitLabの左側のサイドバーの上部で、新規作成( )を選択し、新規プロジェクト/リポジトリを選択します。
3. プロジェクトのインポートを選択し、GitHubを選択します。
4. Authorize with GitHub（GitHubで認証）を選択します。
5. パーソナルアクセストークンフィールドに、GitHubパーソナルアクセストークンを貼り付けます。
6. 認証を選択します。
7. インポートするリポジトリを選択するに進みます。

これらの手順を以前に実行した後、別のトークンを使用してインポートを実行するには、GitLabアカウントからサインアウトして再度サインインするか、GitHubで古いトークンを失効させてください。

APIを使用する

GitLab REST APIを使用して、GitHubリポジトリをインポートできます。GitLab UIを使用するよりも、次のようないくつかの利点があります:

• 所有していないGitHubリポジトリが公開されている場合、インポートするために使用できます。
• Self-HostedのGitHub Enterprise Serverからのインポートに使用できます。
• UIで使用できないtimeout_strategyオプションを設定するために使用できます。

REST APIは、GitLabパーソナルアクセストークンでの認証に制限されています。

GitLab REST APIを使用してGitHubリポジトリをインポートするには、次の手順に従います:

1. GitHubパーソナルアクセストークンを生成します。従来のパーソナルアクセストークンのみがサポートされています。
   1. https://github.com/settings/tokens/newに移動します。
   2. メモフィールドに、トークンの説明を入力します。
   3. repoスコープを選択します。
   4. オプション。コラボレーターをインポートするか、プロジェクトにGit LFSファイルがある場合は、read:orgスコープを選択します。
   5. Generate token（トークンを生成）を選択します。
2. GitLab REST APIを使用して、GitHubリポジトリをインポートします。

リポジトリリストをフィルタリングする

GitHubリポジトリへのアクセスを承認すると、GitLabはインポータ―ページにリダイレクトし、GitHubリポジトリが一覧表示されます。

次のいずれかのタブを使用して、リポジトリのリストをフィルタリングします:

• オーナー(デフォルト): 自分がオーナーのリポジトリにリストをフィルタリングします。
• 共同作業: 自分がコントリビュートしたリポジトリにリストをフィルタリングします。
• 組織: 自分がメンバーである組織に属するリポジトリにリストをフィルタリングします。

組織タブを選択すると、ドロップダウンリストから利用可能なGitHub組織を選択して、検索をさらに絞り込むことができます。

インポートする追加アイテムを選択する

インポートを可能な限り高速化するために、次の項目はデフォルトではGitHubからインポートされません:

• 約30,000件を超えるコメント。GitHub APIの制限によるものです。
• リポジトリのコメント、リリース投稿、イシューの説明、およびプルリクエストの説明からのMarkdown添付ファイル。これらには、画像、テキスト、またはバイナリ添付ファイルを含めることができます。インポートしない場合、GitHubから添付ファイルを削除すると、Markdownの添付ファイルへのリンクが壊れます。

これらのアイテムをインポートすることもできますが、それによりインポート時間が大幅に増加する可能性があります。これらのアイテムをインポートするには、次のようにUIで適切なフィールドを選択します:

• Use alternative comments import method（代替コメントインポートメソッドの使用）。GitHub APIには制限があることから、すべてのイシューとプルリクエストで約30,000件を超えるコメントを含むGitHubプロジェクトをインポートする場合、このメソッドを有効にする必要があります。
• Import Markdown attachments（Markdown添付ファイルのインポート）。
• Import collaborators（コラボレーターのインポート）(デフォルトで選択されています)。選択したままにすると、新しいユーザーがグループまたはネームスペースのシートを使用し、プロジェクトオーナーと同じくらい高い権限が付与される可能性があります。直接のコラボレーターのみがインポートされます。外部のコラボレーターはインポートされません。GitLab 18.4以降では 、コラボレーターをインポートするときに、このグループのプロジェクトにユーザーを追加することはできません設定が優先されます。

インポートするリポジトリを選択する

デフォルトでは、提案されたリポジトリのネームスペースはGitHubに存在する名前と一致しますが、権限に基づいて、インポートに進む前にこれらの名前を編集することもできます。

インポートするリポジトリを選択するには、任意のリポジトリの横にあるインポートを選択するか、Import all repositories（すべてのリポジトリをインポート）を選択します。

さらに、プロジェクトを名前でフィルタリングできます。フィルターが適用されている場合、Import all repositories（すべてのリポジトリをインポート）は、一致するリポジトリのみをインポートします。

ステータス列には、各リポジトリのインポートステータスが表示されます。ページを開いたままにしてリアルタイムで更新を監視するか、後で戻ることができます。

保留中または進行中のインポートをキャンセルするには、インポートされたプロジェクトの横にあるキャンセルを選択します。インポートがすでに開始されている場合、インポートされたファイルは保持されます。

インポート後にGitLab URLでリポジトリを開くには、そのGitLabパスを選択します。

完了したインポートは、再インポートを選択し、新しい名前を指定することで再インポートできます。これにより、ソースプロジェクトの新しいコピーが作成されます。

インポートのステータスを確認する

インポートが完了すると、次の3つのステータスのいずれかになります:

• 完了: GitLabがすべてのリポジトリエンティティをインポートしました。
• 一部のみが完了: GitLabが一部のリポジトリエンティティのインポートに失敗しました。
• 失敗: 重大なエラーが発生した後、GitLabがインポートを中断しました。

詳細を展開すると、インポートに失敗したリポジトリエンティティのリストを表示できます。

ユーザー名のメンション

GitLabは、イシュー、マージリクエスト、およびノートのユーザー名メンションにバッククォートを追加します。これらのバッククォートは、GitLabインスタンスで同じユーザー名を持つ誤ったユーザーへのリンクを防止します。

ユーザーコントリビューションとメンバーシップのマッピング

GitHubインポーターは、GitLab.com、GitLab Self-Managed、およびGitLab Dedicated向けのユーザーコントリビューションのマッピングの改善されたメソッドを使用します。

古いユーザーコントリビューションマッピングメソッド

GitLab Self-ManagedおよびGitLab Dedicatedインスタンスへのインポートには、ユーザーコントリビューションマッピングの古いメソッドを使用できます。このメソッドを使用するには、github_user_mappingを無効にする必要があります。GitLab.comへのインポートでは、代わりに改善されたメソッドを使用する必要があります。

古いメソッドを使用すると、ユーザーアカウントが正しくプロビジョニングされている場合、インポート中にユーザーがマッピングされます。

要件が満たされていない場合、インポータ―は特定のユーザーのコントリビューションをマッピングできません。その場合は、次の通りとなります:

• プロジェクト作成者は、イシューとマージリクエストの作成者と担当者に設定されます。プロジェクト作成者は通常、インポートプロセスを開始したユーザーとなります。プルリクエスト、イシュー、ノートなど、説明またはノートがある一部のコントリビューションの場合、インポータ―は最初にコントリビューションを作成したユーザーの詳細を含むテキストを修正します。
• GitHubのプルリクエストに追加されたレビュアーと承認はインポートできません。この場合、インポータ―は存在しないユーザーがレビュアーおよび承認者として追加されたことを説明するコメントを作成します。ただし、実際のレビュアーステータスと承認は、GitLabのマージリクエストには適用されません。

リポジトリのミラーリングとパイプラインステータスを共有する

GitLabのリポジトリのミラーリングプランによっては、インポートされたリポジトリをGitHubのコピーと同期するように設定できます。

さらに、GitHubプロジェクトインテグレーションを使用して、パイプラインの状態の更新をGitHubに送信するようにGitLabを設定できます。

外部リポジトリのCI/CDを使用してプロジェクトをインポートする場合、両方の機能が自動的に設定されます。

GitLab Self-Managedインスタンスでのインポートのスピードを改善する

これらの手順を実行するには、GitLabサーバーに対する管理者アクセスが必要です。

Sidekiqワーカーの数を増やす

大規模なプロジェクトの場合、すべてのデータのインポートに時間がかかることがあります。必要な時間を短縮するために、次のキューを処理するSidekiqワーカー:

• github_importer
• github_importer_advance_stage

最適なエクスペリエンスを得るには、これらのキューのみを処理する少なくとも4つのSidekiqプロセス（それぞれがCPUコア数と同じ数のスレッドを実行）を用意することをお勧めします。これらのプロセスを個別のサーバー上で実行することもお勧めします。8コアの4台のサーバーの場合、最大32個のオブジェクト (イシューなど) を並行してインポートできます。

リポジトリのクローンにかかる時間を短縮するには、Gitリポジトリ (GitLabインスタンス用) を保存するディスクのネットワークスループット、CPU容量、およびディスクパフォーマンス (パフォーマンスの高いSSDを使用するなど) を向上させることで実現できます。Sidekiqワーカーの数を増やしても、リポジトリの複製にかかる時間は短縮されません。

GitHub Enterprise Cloud OAuth Appを使用してGitHub OAuthを有効にする

GitHub Enterprise Cloud組織に所属している場合は、より高いGitHub APIレート制限を取得するようにGitLab Self-Managedを設定できます。

GitHub APIリクエストは通常、1時間あたり5,000リクエストのレート制限の対象となります。以下の手順を使用すると、1時間あたり15,000リクエストというより高いレート制限が得られ、全体的なインポート時間が短縮されます。

前提要件:

• GitHub Enterprise Cloud組織へのアクセス権を持っている。
• GitLabがGitHub OAuthを有効にするように設定されている。

より高いレート制限を有効にするには、次を実行します:

• GitHubでOAuthアプリを作成します。OAuthアプリが個人のGitHubアカウントではなく、Enterprise Cloudの組織によって保持されることを確認してください。
• GitHub OAuthを使用してプロジェクトのインポートを実行します。
• オプション。デフォルトでは、サインインは設定済みのすべてのOAuthプロバイダーで有効になっています。インポートにGitHub OAuthを有効にするが、ユーザーがGitHubを使用してGitLabインスタンスにサインインできないようにする場合は、GitHubでのサインインを無効にすることができます。

インポートされたデータ

プロジェクトの次の項目がインポートされます:

• オープンプルリクエストに関連するプロジェクトのすべてのフォークブランチ

  フォークからのブランチは、GH-SHA-username/pull-request-number/fork-name/branchのような命名規則でインポートされます。

• すべてのプロジェクトブランチ。

• 次の添付ファイル:

  • コメント
  • イシューの説明。
  • プルリクエストの説明。
  • リリースノート。

• ブランチ保護ルール。

• コラボレーター(メンバー)

• LFSオブジェクト

• Gitリポジトリデータ。

• イシューとプルリクエストのコメント。

• イシューとプルリクエストのイベント（追加項目としてインポートできます）

• イシュー

• ラベル

• マイルストーン

• プルリクエストに割り当てられたレビュアー。

• プルリクエストのマージしたユーザーの情報。

• プルリクエストのレビュー。

• プルリクエストのレビューコメント。

• ディスカッションに対するプルリクエストレビューの返信

• プルリクエストレビューの提案

• プルリクエスト。

• リリースノートのコンテンツ。

• リポジトリの説明。

• Wikiページ

プルリクエストとイシューへの参照は保持される。インポートされた各リポジトリは、表示レベルが制限されている場合を除き、表示レベルを維持します。制限されている場合は、デフォルトのプロジェクト表示レベルにデフォルト設定されます。

ブランチ保護ルールとプロジェクト設定

インポートされたGitHubブランチ保護ルールは、次のいずれかにマップされます:

• GitLabブランチ保護ルール。
• プロジェクト全体のGitLab設定。

Require status checks to pass before merging（マージする前にステータスチェックに合格させる） GitHubルールはインポートされません。外部ステータスチェックは手動で作成できます。詳細については、イシュー370948を参照してください。

コラボレーター（メンバー）

これらのGitHubコラボレーターのロールは、これらのGitLab メンバーのロールにマッピングされます:

GitHub Enterprise Cloudには、カスタムリポジトリのロールがあります。これらのロールはサポートされておらず、インポートが一部しか完了しなくなる原因となります。

GitHubコラボレーターをインポートするには、GitHubプロジェクトで少なくとも書き込みのロールが必要です。それ以外の場合、コラボレーターのインポートはスキップされます。

内部ネットワーク上のGitHub Enterpriseからインポートする

GitHub Enterpriseインスタンスがインターネットにアクセスできない内部ネットワーク上にある場合は、リバースプロキシを使用してGitLab.comがインスタンスにアクセスできるようにすることができます。

プロキシは次のことを行う必要があります:

• GitHub Enterpriseインスタンスにリクエストを転送します。
• 次の内部ホスト名のすべてのオカレンスをパブリックプロキシホスト名に変換します:
  • API応答のボディ。
  • API応答のLinkヘッダー。

GitHub APIは、ページネーションにLinkヘッダーを使用します。

プロキシを設定したら、APIリクエストを作成してテストします。以下に、APIをテストするためのコマンドの例をいくつか示します:

curl --header "Authorization: Bearer <YOUR-TOKEN>" "https://{PROXY_HOSTNAME}/user"

### URLs in the response body should use the proxy hostname

{
  "login": "example_username",
  "id": 1,
  "url": "https://{PROXY_HOSTNAME}/users/example_username",
  "html_url": "https://{PROXY_HOSTNAME}/example_username",
  "followers_url": "https://{PROXY_HOSTNAME}/api/v3/users/example_username/followers",
  ...
  "created_at": "2014-02-11T17:03:25Z",
  "updated_at": "2022-10-18T14:36:27Z"
}

curl --head --header "Authorization: Bearer <YOUR-TOKEN>" "https://{PROXY_DOMAIN}/api/v3/repos/{repository_path}/pulls?states=all&sort=created&direction=asc"

### Link header should use the proxy hostname

HTTP/1.1 200 OK
Date: Tue, 18 Oct 2022 21:42:55 GMT
Server: GitHub.com
Content-Type: application/json; charset=utf-8
Cache-Control: private, max-age=60, s-maxage=60
...
X-OAuth-Scopes: repo
X-Accepted-OAuth-Scopes:
github-authentication-token-expiration: 2022-11-22 18:13:46 UTC
X-GitHub-Media-Type: github.v3; format=json
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4997
X-RateLimit-Reset: 1666132381
X-RateLimit-Used: 3
X-RateLimit-Resource: core
Link: <https://{PROXY_DOMAIN}/api/v3/repositories/1/pulls?page=2>; rel="next", <https://{PROXY_DOMAIN}/api/v3/repositories/1/pulls?page=11>; rel="last"

次の通り、プロキシを使用してリポジトリをクローンしても失敗しないこともテストしてください:

git clone -c http.extraHeader="Authorization: basic <base64 encode YOUR-TOKEN>" --mirror https://{PROXY_DOMAIN}/{REPOSITORY_PATH}.git

サンプルリバースプロキシ設定

次は、Apache HTTPサーバーをリバースプロキシとして設定する方法の例です。

# Required modules
LoadModule filter_module lib/httpd/modules/mod_filter.so
LoadModule reflector_module lib/httpd/modules/mod_reflector.so
LoadModule substitute_module lib/httpd/modules/mod_substitute.so
LoadModule deflate_module lib/httpd/modules/mod_deflate.so
LoadModule headers_module lib/httpd/modules/mod_headers.so
LoadModule proxy_module lib/httpd/modules/mod_proxy.so
LoadModule proxy_connect_module lib/httpd/modules/mod_proxy_connect.so
LoadModule proxy_http_module lib/httpd/modules/mod_proxy_http.so
LoadModule ssl_module lib/httpd/modules/mod_ssl.so

<VirtualHost GITHUB_ENTERPRISE_HOSTNAME:80>
  ServerName GITHUB_ENTERPRISE_HOSTNAME

  # Enables reverse-proxy configuration with SSL support
  SSLProxyEngine On
  ProxyPass "/" "https://GITHUB_ENTERPRISE_HOSTNAME/"
  ProxyPassReverse "/" "https://GITHUB_ENTERPRISE_HOSTNAME/"

  # Replaces occurrences of the local GitHub Enterprise URL with the Proxy URL
  # GitHub Enterprise compresses the responses, the filters INFLATE and DEFLATE needs to be used to
  # decompress and compress the response back
  AddOutputFilterByType INFLATE;SUBSTITUTE;DEFLATE application/json
  Substitute "s|https://GITHUB_ENTERPRISE_HOSTNAME|https://PROXY_HOSTNAME|ni"
  SubstituteMaxLineLength 50M

  # GitHub API uses the response header "Link" for the API pagination
  # For example:
  #   <https://example.com/api/v3/repositories/1/issues?page=2>; rel="next", <https://example.com/api/v3/repositories/1/issues?page=3>; rel="last"
  # The directive below replaces all occurrences of the GitHub Enterprise URL with the Proxy URL if the
  # response header Link is present
  Header edit* Link "https://GITHUB_ENTERPRISE_HOSTNAME" "https://PROXY_HOSTNAME"
</VirtualHost>