- 前提条件
- GitHub リポジトリを GitLab にインポートしてください。
- リポジトリをミラーしてパイプラインステータスを共有
- セルフマネージドインスタンスでのインポート速度の向上
- インポートデータ
- 内部ネットワーク上の GitHub Enterprise からのインポート
- グループとプロジェクトのインポートを自動化
- トラブルシューティング
GitHubからGitLabにプロジェクトをインポートします。
- GitLab 15.8で導入されたGitLabは、存在しない名前空間やグループを自動的に作成しなくなりました。GitLabはまた、名前空間やグループ名が取られた場合に、ユーザーの個人的な名前空間を使うようにフォールバックすることもなくなりました。
- GitLab 15.10で導入された、GitLabの親グループにユーザーを追加しなくても、ブランチのインポートを成功させることができるようになりました。Require a pull request before merg - 指定されたアクターがrequired pull requestsブランチ保護ルールをバイパスすることを許可します。
- GitLab 15.11で導入された、プロキシの背後にあるGitLabインスタンスは、ローカルリクエストのallowlistで
github.com
、api.github.com
エントリを必要としなくなりました。
GitHub プロジェクトは GitHub.com または GitHub Enterprise からインポートすることができます。プロジェクトをインポートしても、GitHubからGitLabへのグループや組織のマイグレーションやインポートは行われません。
ネームスペースとはGitLabのユーザーやグループのことで、gitlab.com/sidney-jones
やgitlab.com/customer-success
のようなものです。 railsコンソールでバルクアクションを使用すると、プロジェクトを異なるネームスペースに移動することができます。
- 自分で管理している GitLab インスタンスにインポートする場合は、代わりにGitHub Rake タスクを使うことができます。Rakeタスクは、Sidekiqワーカーの制約なしにプロジェクトをインポートします。
- GitHub EnterpriseからGitLab.comにインポートする場合は、代わりにGitLab Import APIGitHubエンドポイントを使用してください。これにより、プロジェクトをインポートする別のドメインを指定できます。UIを使用すると、GitHubインポーターは常に
github.com
ドメインからインポートします。
プロジェクトをインポートする場合:
- プロジェクトで参照されているユーザーがGitLabデータベースに見つからない場合、プロジェクト作成者が作成者・担当者として設定されます。プロジェクト作成者は通常、インポートプロセスを開始したユーザーです。イシューに元のGitHub作成者のメモが追加されます。
- GitLab に存在しない GitHub プルリクエストに割り当てられたレビュアーはインポートされません。この場合、インポートは存在しないユーザーがレビュアーや承認者として追加されたことを示すコメントを作成します。しかし、実際のレビュアー・ステータスと承認者は GitLab のマージリクエストには適用されません。
- インポートする前に、対象の名前空間と対象のリポジトリ名を変更することができます。
- インポーターは、オープンなプルリクエストに関連するプロジェクトのフォーク上のブランチもインポートします。これらのブランチは、
GH-SHA-username/pull-request-number/fork-name/branch
に似た命名スキームでインポートされます。このため、GitHub リポジトリのブランチと食い違うことがあります。 - リポジトリが所属する組織は、インポート先の GitLab インスタンスにサードパーティアプリケーションのアクセスポリシーの制限を課してはいけません。
インポートプロセスの概要については、アクションを含むGitHubからGitLabへのマイグレーション方法をご覧ください。
前提条件
GitLab16.0で導入され、GitLab15.11.1とGitLab15.10.5にバックポートされたDeveloperロールの代わりにMaintainerロールの要件。
GitHubからプロジェクトをインポートするには:
- GitHubインポートソースが有効になっている必要があります。有効になっていない場合は、GitLab管理者に有効にしてもらうよう依頼してください。GitLab.comではGitHubインポートソースはデフォルトで有効になっています。
- インポート先のグループで少なくともメンテナーのロールを持っている必要があります。
-
リポジトリ内の各 GitHub 作成者と担当者は、GitLab のメールアドレスと一致する GitHub の公開メールアドレスを持っている必要があります(アカウントの作成方法は問いません)。GitHub のメールアドレスが GitLab のセカンダリメールアドレスとして設定されている場合は、それを確認する必要があります。
イシューやプルリクエストをインポートする際、インポーターは GitLab インスタンスのデータベースから GitHub の作成者や担当者を見つけようとします。プルリクエストはGitLabでは_マージリクエストと_呼ばれています。インポートを成功させるには、メールアドレスが一致する必要があります。
- GitHubアカウントには、GitHub公開用のメールアドレスが入力されている必要があります。これは、すべてのコメントと貢献者がGitLabの同じユーザーに適切にマッピングされることを意味します。GitHub Enterpriseはこのフィールドを入力する必要がないので、既存のアカウントに追加する必要があるかもしれません。
GitHub Enterpriseから自己管理のGitLabへのインポート
GitHub EnterpriseからセルフマネジメントのGitLabインスタンスにインポートする場合:
- まずGitHub インテグレーションを有効にする必要があります。
- GitHub は管理エリアでインポートソースとして有効にする必要があります。
- GitLab 15.10以前では、ローカルリクエストのallowlistに
github.com
とapi.github.com
エントリを追加する必要があります。
GitHub.comから自分で管理するGitLabへのインポート
GitHub.comからセルフマネジメントのGitLabインスタンスにインポートする場合:
- GitHubインテグレーションを有効にする必要はありません。
- GitHub は管理エリアでインポートソースとして有効にする必要があります。
既知のイシュー
- 2017年以前に作成されたGitHubのプルリクエストコメント(GitLabでは差分ノートとして知られています)は、別々のスレッドでインポートされます。これはGitHub APIの制限により、2017年以前のコメントには
in_reply_to_id
。 - 既知のイシューのため、OmniAuthプロバイダとしてGitHubを使用している場合は、OmniAuth設定でURL周辺が指定されていることを確認してください。
GitHub リポジトリを GitLab にインポートしてください。
GitHub インテグレーションを使う
始める前に、GitLabユーザーにマッピングしたいGitHubユーザーのGitLabメールアドレスが、GitHubで公開されているメールアドレスと一致していることを確認してください。
GitLab.com にインポートする場合は、個人アクセストークンを使って GitHub リポジトリをインポートすることもできます。
GitHubユーザーの公開メールアドレスがGitLabユーザーのメールアドレスと一致しない場合、そのユーザーのアクティビティはインポートを行うユーザーアカウントと関連付けられます。
- 左サイドバーの上部にある「新規作成({plus})」と「新規プロジェクト/リポジトリ」を選択します。
- プロジェクトのインポートを選択し、GitHubを選択します。
- これで
- 個人アクセストークンを追加し、認証を選択します。
- インスタンスに GitHub が設定されている場合は、[Authorize with GitHub] を選択します。
- Authorize GitlabHQを選択します。GitLab Importページにリダイレクトされ、GitHubリポジトリがすべてリストアップされます。
- インポートするリポジトリの選択に進みます。
GitHub トークンを使う
前提条件
- 管理者権限のある認証トークン。
GitLab.comユーザーであれば、個人アクセストークンを使ってGitHubからプロジェクトをインポートすることができます。セルフマネジメントのGitLabインスタンスの管理者である場合、またはGitHub Enterpriseからインポートする場合は、個人アクセストークンを使用することはできません。すべてのユーザーにはGitHubインテグレーション(上記)の方法をお勧めします。
GitHubインテグレーションを使用しない場合でも、GitLabにリポジトリへのアクセスを許可するためにGitHubで認証を行うことができます:
- 以下にアクセスしてください。https://github.com/settings/tokens/new
- トークンの説明を入力します。
- リポジトリスコープを選択します。
- トークンの生成 を選択します。
- トークンのハッシュをコピーします。
- GitLabに戻り、GitHubインポーターにトークンを提供します。
- List Your GitHub Repositoriesを選択し、GitLabがリポジトリの情報を読み込むまで待ちます。完了すると、インポートページに移動してインポートするリポジトリを選択します。
これらの手順を行った後にインポートで新しいパーソナルアクセストークンを使用するには、GitLabアカウントからサインアウトして再度サインインするか、GitHubで古いパーソナルアクセストークンを失効させてください。
リポジトリリストのフィルタリング
GitLab 16.0 で導入されました。
GitHubリポジトリへのアクセスを作成者が認証すると、GitLabはインポーターページにリダイレクトし、GitHubリポジトリがリストアップされます。
以下のタブのいずれかを使って、リポジトリのリストをフィルタリングしてください:
- オーナー(デフォルト):自分がオーナーであるリポジトリにリストを絞り込みます。
- 共同作業者貢献したリポジトリに絞り込みます。
- 組織:あなたが所属する組織に属するリポジトリにリストを絞り込みます。
組織] タブを選択すると、ドロップダウンリストから利用可能な GitHub 組織を選択することで、さらに絞り込むことができます。
インポートする項目を追加選択します。
インポートを可能な限り高速化するため、以下の項目はデフォルトではGitHubからインポートされません:
- イシューやプルリクエストのイベント。例えば、オープンや クローズ、名前の変更、ラベルの _有無など_です。
- すべてのコメント。大規模なリポジトリの通常のインポートでは、GitHub API の制限により一部のコメントがスキップされることがあります。
- リポジトリのコメント、リリースの投稿、イシューの説明、プルリクエストの説明のマークダウンの添付ファイル。これらには、画像、テキスト、バイナリの添付ファイルを含めることができます。インポートしない場合、GitHub から添付ファイルを削除すると、添付ファイルへの Markdown のリンクが壊れてしまいます。
これらのアイテムをインポートすることもできますが、インポート時間が大幅に長くなる可能性があります。これらのアイテムをインポートするには、UI で適切なフィールドを選択してください:
- イシューイベントとプルリクエストイベントをインポートします。
- 別のコメントインポート方法を使用してください。
- Markdownの添付ファイルをインポートします。
- 共同作業者のインポート(デフォルトで選択されています)。選択したままにしておくと、新しいユーザーがグループやネームスペースのシートを使用し、プロジェクトオーナーと同等の権限が付与される可能性があります。直接の共同作業者のみがインポートされます。外部の共同作業者はインポートされません。
インポートするリポジトリを選択します。
デフォルトでは、提案されるリポジトリの名前空間はGitHubに存在する名前と一致しますが、権限に基づいて、これらの名前をインポートに進む前に編集することができます。
インポートするリポジトリを選択するには、任意の数のリポジトリの横にあるImportを選択するか、Import all repositories を選択します。
さらに、プロジェクトを名前でフィルタリングすることもできます。フィルターが適用されている場合、Import all repositoriesは一致したリポジトリのみをインポートします。
ステータス列には、各リポジトリのインポート状況が表示されます。ページを開いたままリアルタイムで更新を見るか、後で戻るかを選択できます。
保留中または進行中のインポートをキャンセルするには、インポートしたプロジェクトの横にあるキャンセル を選択します。インポートが既に開始されている場合、インポートされたファイルは保持されます。
インポート後にGitLab URLでリポジトリを開くには、そのGitLabパスを選択します。
完了したインポートは、Re-importを選択して新しい名前を指定することで再インポートできます。これにより、ソースプロジェクトの新しいコピーが作成されます。
インポートのステータスの確認
GitLab 16.1で導入されたインポートに失敗したエンティティのリストと、部分的に完了したインポートの詳細。
インポートが完了した後、3つの状態のいずれかになります:
- 完了:GitLabはすべてのリポジトリエンティティをインポートしました。
- 部分的に完了しました:GitLab はいくつかのリポジトリエンティティのインポートに失敗しました。
- 失敗しました:GitLab はクリティカルエラーが発生した後、インポートを中止しました。
Detailsを展開すると、インポートに失敗したリポジトリエンティティの一覧が表示されます。
リポジトリをミラーしてパイプラインステータスを共有
GitLabの階層によっては、リポジトリのミラーリングを設定することで、インポートしたリポジトリをGitHubのコピーと同期させることができます。
さらに、GitHub Project Integrationを使ってパイプラインステータスの更新をGitHubに送り返すようにGitLabを設定することができます。
CI/CD for external repositoryを使ってプロジェクトをインポートした場合、上記の両方が自動的に設定されます。
セルフマネージドインスタンスでのインポート速度の向上
この処理には GitLab サーバーの管理者権限が必要です。
大規模なプロジェクトでは、すべてのデータをインポートするのに時間がかかる場合があります。必要な時間を短縮するために、以下のキューを処理するSidekiqワーカーの数を増やすことができます:
github_importer
github_importer_advance_stage
最適なエクスペリエンスのためには、これらのキューのみを処理するSidekiqプロセス(それぞれがCPUコア数と同じ数のスレッドを実行)を少なくとも4つ持つことを推奨します。また、これらのプロセスは別々のサーバーで実行することを推奨します。8コアのサーバーを4台使用する場合、最大32個のオブジェクト(イシューなど)を並行してインポートできることになります。
リポジトリのクローンにかかる時間を短縮するには、(GitLabインスタンスの)Gitリポジトリを保存するディスクのネットワークスループット、CPU容量、ディスク性能(高性能SSDの使用など)を向上させます。Sidekiq ワーカーの数を増やしても、リポジトリのクローン作成にかかる時間は短縮されません。
インポートデータ
プロジェクトの以下の項目がインポートされます:
- リポジトリの説明。
- Git リポジトリのデータ。
- ブランチ保護ルール。GitLab 15.4で導入。
- 共同作業者(メンバー)。GitLab 15.10から導入。GitLab 16.0からは追加項目としてインポート可能。
- イシュー
- プルリクエスト
- Wiki ページ。
- マイルストーン
- ラベル
- リリースノートの内容。
- 添付ファイル
- リリースノートGitLab 15.4 で導入されました。
- コメント。GitLab 15.5 で導入。
- イシューの説明。GitLab 15.5 で導入されました。
- プルリクエストの説明。GitLab 15.5 で導入。
全ての添付ファイルのインポートは、
github_importer_attachments_import
機能フラグの後ろではデフォルトで無効になっています。GitLab 15.5から、追加アイテムとしてインポートできるようになりました。機能フラグは削除されました。 - プルリクエストのレビューコメント。
- 通常のイシューとプルリクエストのコメント。
- Git 大容量ファイルストレージ(LFS) オブジェクト。
- プルリクエストレビュー。
- プルリクエストに割り当てられたレビュアー。GitLab 15.6 で導入されました。
- プルリクエストの “merged by” 情報。
- ディスカッションでのプルリクエストコメントの返信。GitLab 14.5 で導入されました。
- プルリクエストのレビューコメントの提案。GitLab 14.7 で導入。
- イシューイベントとプルリクエストイベント。GitLab 15.4で導入され、
github_importer_issue_events_import
機能フラグはデフォルトで無効になっています。GitLab 15.5から、追加項目としてインポートできるようになりました。機能フラグは削除されました。
プルリクエストやイシューへの参照は保持されます。インポートされたリポジトリは、可視性のレベルが制限されていない限り、可視性のレベルを維持します。
ブランチ保護ルールとプロジェクト設定
インポートされると、サポートされている GitHub ブランチ保護ルールは次のいずれかにマップされます:
- GitLab ブランチ保護ルール。
- プロジェクト全体のGitLab設定。
GitHub ルール | GitLabルール | 次で導入されました |
---|---|---|
プロジェクトのデフォルトブランチでマージ前に会話解決を要求 | すべてのスレッドが解決されている必要があります。 プロジェクト設定 | GitLab 15.5 |
マージ前にプルリクエストを要求 | ブランチ保護設定の プッシュ・マージ許可リストにオプションが一つもないこと | GitLab 15.5 |
プロジェクトのデフォルトブランチに署名付きコミットを要求 | 署名のないコミットを拒否GitLabのプッシュルール | GitLab 15.5 |
強制プッシュの許可 - 全員 | 強制プッシュを許可 ブランチ保護設定 | GitLab 15.6 |
マージ前にプルリクエストが必要 - コードオーナーのレビュアーが必要 | コードオーナーの承認が必要 ブランチ保護設定 | GitLab 15.6 |
マージ前にプルリクエストを必須とする - 指定したアクターによるプルリクエストの回避を許可 | ブランチ保護設定のプッシュとマージを許可するユーザーのリスト .Premiumサブスクリプションがない場合、プッシュとマージを許可するユーザーリストはロールに限定されます。 | GitLab 15.8 |
GitHubのルールRequire status checks to pass before mergingを外部のステータスチェックにマッピングすることがイシュー370948で検討されました。しかし、このルールは技術的な問題によりGitLabへのプロジェクトのインポート時にインポートされません。外部ステータスチェックを手動で作成することはできます。
共同作業者 (メンバー)
GitLab 15.10 で導入されました。
これらのGitHubコラボレーターロールは、これらのGitLabメンバーロールにマッピングされています:
GitHub ロール | マッピングされたGitLabロール |
---|---|
読む | ゲスト |
トリアージ | レポーター |
書く | 開発者 |
メンテナー | メンテナー |
管理者 | オーナー |
GitHub Enterprise Cloud にはカスタムリポジトリロールがあります。これらのロールはサポートされていないため、部分的にインポートが完了します。
GitHub 共同作業者をインポートするには、GitHub プロジェクトで少なくとも Write ロールが必要です。そうでない場合、共同作業者のインポートはスキップされます。
内部ネットワーク上の 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>
グループとプロジェクトのインポートを自動化
ユーザー、グループ、プロジェクトのインポートAPIコールの自動化については、グループとプロジェクトのインポートの自動化を参照してください。
トラブルシューティング
以前に失敗したインポートプロセスを手動で続行する方法
GitHub インポート処理でリポジトリのインポートに失敗する場合があります。この場合、GitLab はプロジェクトのインポート処理を中断し、リポジトリを手動でインポートする必要があります。管理者はインポートに失敗したリポジトリのインポートを手動で行うことができます:
- Rails コンソールを開きます。
-
コンソールで以下の一連のコマンドを実行します:
project_id = <PROJECT_ID> github_access_token = <GITHUB_ACCESS_TOKEN> github_repository_path = '<GROUP>/<REPOSITORY>' github_repository_url = "https://#{github_access_token}@github.com/#{github_repository_path}.git" # Find project by ID project = Project.find(project_id) # Set import URL and credentials project.import_url = github_repository_url project.import_type = 'github' project.import_source = github_repository_path project.save! # Create an import state if the project was created manually and not from a failed import project.create_import_state if project.import_state.blank? # Set state to start project.import_state.force_start # Trigger import from second step Gitlab::GithubImport::Stage::ImportRepositoryWorker.perform_async(project.id)
大規模プロジェクトのインポート時のエラー
GitHub インポーターは、大きなプロジェクトをインポートする際にエラーが発生することがあります。
ノートと差分ノートをインポートする別の方法
GitHub インポーターを非常に大規模なプロジェクトで実行すると、GitHub APIissues_comments
やpull_requests_comments
のエンドポイントの制限により、すべてのノートや差分ノートをインポートできないことがあります。
すべてのページを取得できない場合、GitHub API は次のようなエラーを返すことがあります:
In order to keep the API fast for everyone, pagination is limited for this resource. Check the rel=last link relation in the Link response header to see how far back you can traverse.
コメントのインポートには別の方法があります。
issues_comments
とpull_requests_comments
を使用する代わりに、個々のリソースを使用して、1度に1つのオブジェクトからノートを取り込みます。この方法では、欠落しているコメントを引き継ぐことができます。ただし、この方法ではインポートの実行に必要なネットワーク・リクエストの数が増えるため、実行に時間がかかります。
ページあたりの GitHub API リクエストオブジェクトを減らす
GitHub API のエンドポイントによっては、大きなリポジトリからプロジェクトをインポートする際に500
や502
というエラーを返すことがあります。このようなエラーの可能性を減らすには、データをインポートするグループプロジェクトでgithub_importer_lower_per_page_limit
機能フラグを有効にします。このフラグを有効にすると、ページサイズが100
から50
に縮小されます。
この機能フラグを有効にするには、以下の手順に従います:
- Railsコンソールを起動します。
-
以下の
enable
コマンドを実行します:group = Group.find_by_full_path('my/group/fullpath') # Enable Feature.enable(:github_importer_lower_per_page_limit, group)
機能フラグを無効にするには、次のコマンドを実行します:
# Disable
Feature.disable(:github_importer_lower_per_page_limit, group)