GitHubからの移行

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 GitHubエンドポイントを、apiスコープを持つGitLabアクセストークンで使用してください。

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

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

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

GitHubからのインポートはそれぞれ異なるため、実行するインポートの所要時間に影響します。しかし、テストでは、GitLabは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インスタンスにサードパーティアプリケーションのアクセスポリシーの制限を課してはなりません。

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

既知の問題

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

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

• SAMLシングルサインオン（SSO）が有効になっているGitHubアカウントからインポートする場合、Markdown添付ファイルはインポートに失敗する可能性があります。このイシューは、SSOが強制されている場合に、パーソナルアクセストークンを使用してアセットをダウンロードできないというGitHub APIの制限が原因で発生します。このイシューの回避策として、インポートを実行するGitLabユーザーを外部コラボレーターとしてGitHubリポジトリに追加します。これにより、インポート中にプライベート添付ファイルへのアクセスが許可されます。

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. GitHubで認証を選択します。
4. インポートするリポジトリを選択するに進みます。

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

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

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

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

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

APIを使用する

インポート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. トークンを生成を選択します。
2. インポートAPIを使用して、あなたのGitHubリポジトリをインポートしてください。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ユーザー名のメンション

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

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

GitHubインポーターは、GitLab.com、GitLab Self-Managed、およびGitLab Dedicated向けに、ユーザーのコントリビュートをマッピングする移行後手法を使用します。

代替のマッピング方法

GitLab 18.7およびそれ以前では、github_user_mapping機能フラグを無効にして、インポートの代替ユーザーコントリビュートマッピング手法を使用できます。

要件:

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

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

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

• プロジェクト作成者は、イシューとマージリクエストの作成者と担当者に設定されます。プロジェクト作成者は通常、インポートプロセスを開始したユーザーとなります。プルリクエスト、イシュー、ノートなど、説明またはノートがある一部のコントリビューションの場合、インポータ―は最初にコントリビューションを作成したユーザーの詳細を含むテキストを修正します。
• 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でのサインインを無効にすることができます。

インポートされたデータ

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

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

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

• 次の添付ファイル:

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

• ブランチ保護ルール

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

• Git 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>

関連トピック

• インポートとエクスポートの設定。
• インポートに関するSidekiqの設定。
• 複数のSidekiqプロセスの実行。
• 特定のジョブクラスの処理。