GitLab 同期

この機能は ayaka-notes/ayakaleaf-pro によって開発されたものです。v6.4.0 以降で導入されています。まだベータ版のため、問題があればぜひフィードバックをお寄せください。

GitLab 同期は GitHub 同期 と同様に動作します。ユーザーは GitLab アカウントを連携し、プロジェクトを新しい GitLab プロジェクトにエクスポートしたり、GitLab リポジトリをインポートしたり、双方向で変更を同期したりできます。GitLab.com と、GitLab 15.10 以降のセルフマネージド GitLab（Community Edition および Enterprise Edition）で動作します。

​

GitLab 同期のセットアップ

GitLab 同期を使用する前に、まず git-bridge を有効にする必要があります。

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

GitLab インスタンスの User settings → Applications（インスタンス全体のアプリケーションの場合は Admin area → Applications）で OAuth アプリケーションを作成します。

• Redirect URI: ${OVERLEAF_SITE_URL}/user/gitlab-sync/oauth2/callback
• Confidential: チェックを入れる
• Scopes: api

Application ID と Secret をコピーし、Overleaf の環境変数ファイルに以下の設定を追加します。

config/variables.env

# used to encrypt the user's GitLab access and refresh tokens.
# How to generate: `openssl rand -hex 32`
GITLAB_TOKEN_CIPHER_PASSWORD=0123456789ABCDEFG # changed to yours

# GitLab Sync Settings
GITLAB_SYNC_ENABLED=true
GITLAB_SYNC_CLIENT_ID=
GITLAB_SYNC_CLIENT_SECRET=

# Web address of your GitLab, defaults to https://gitlab.com
# GITLAB_SYNC_URL=https://gitlab.example.com

# OAuth callback is: ${OVERLEAF_SITE_URL}/user/gitlab-sync/oauth2/callback
# (Optional) GITLAB_SYNC_PROXY_URL=http://10.0.0.1:10808

GitLab OAuth のリダイレクト URI を設定する前に、OVERLEAF_SITE_URL が正しく設定されていることを確認してください。

GitLab のアクセストークンは 2 時間で有効期限が切れます。Overleaf は GitLab がアクセストークンと一緒に発行するリフレッシュトークンを使ってトークンを更新するため、ユーザーは連携を解除するか GitLab でアプリケーションを取り消すまで連携された状態が維持されます。

​

セルフマネージド GitLab

GITLAB_SYNC_URL にインスタンスの Web アドレス（ブラウザーでプロジェクトを開く際のアドレス）を設定します。REST API はこのアドレスから導出されます。

変数	デフォルト
GITLAB_SYNC_URL	https://gitlab.com
GITLAB_SYNC_API_URL	${GITLAB_SYNC_URL}/api/v4

GITLAB_SYNC_API_URL は、インスタンスが別の場所（API ゲートウェイの背後など）で API を提供している場合にのみ設定してください。

• OAuth アプリケーションは GITLAB_SYNC_URL に設定したインスタンス上で作成してください。gitlab.com で作成したアプリケーションはセルフマネージドインスタンスでは動作しません。
• GITLAB_SYNC_URL には Web アドレスのみを指定します。/api/v4 やグループのパスを付け加えないでください。

インスタンスがプライベート CA の証明書を使用している場合は、CA 証明書をコンテナにマウントし、NODE_EXTRA_CA_CERTS でそれを指定してください。例: NODE_EXTRA_CA_CERTS=/var/lib/overleaf/certs/gitlab-ca.pem。

連携されたアカウントとプロジェクトは、連携時のインスタンスに属します。GITLAB_SYNC_URL を別のインスタンスに切り替える前に、ユーザーに GitLab アカウントとプロジェクトの連携を解除するよう依頼してください。

ネットワークアクセスが制限されている地域にいる場合は、GitLab にアクセスするためにプロキシの設定が必要になることがあります。次の環境変数を設定してください: GITLAB_SYNC_PROXY_URL=http://10.0.0.1:10808。プロキシは標準的な HTTP/HTTPS フォワードプロキシである必要があり、127.0.0.1 を使用してはいけません。

​

連携と同期を行えるユーザー

Overleaf Cloud と同様に、プロジェクトを GitLab リポジトリに連携できるのはプロジェクトのオーナーのみです。連携後は、編集権限を持つすべての共同編集者が同期できます。

操作	実行できるユーザー
プロジェクトを新しい GitLab リポジトリにエクスポート	プロジェクトのオーナー
GitLab リポジトリを新しいプロジェクトにインポート	すべてのユーザー（新しいプロジェクトのオーナーになります）
連携済みプロジェクトのプル、プッシュ、マージ	オーナーと編集権限を持つ共同編集者
プロジェクトとリポジトリの連携解除	プロジェクトのオーナー

• Overleaf は同期を行うユーザーの GitLab アカウントを使って GitLab とやり取りします。そのため、同期を行う共同編集者はそれぞれ自分の GitLab アカウントを連携し、リポジトリのデフォルトブランチへのプッシュが許可されている必要があります。
• 閲覧のみの共同編集者は、そのプロジェクトで GitLab 同期を使用できません。

​

GitLab での同期の仕組み

• 権限: ユーザーは、連携されたプロジェクトのデフォルトブランチへのプッシュが許可されている必要があります。デフォルトブランチが保護されていてユーザーがプッシュできない場合、アクセス権を失ったリポジトリの場合と同様に、Overleaf はプロジェクトのオーナーに連絡するよう求めます。
• マージ: Overleaf と GitLab の両方でプロジェクトが変更された場合、GitLab にはマージリクエストなしでブランチをマージする API がないため、Overleaf は変更を overleaf-YYYY-MM-DD-HHMMSS という名前の一時ブランチにコミットし、マージリクエストを通じてマージします。マージ後、Overleaf は一時ブランチとマージリクエストを削除します。GitLab でマージリクエストを削除できるのは管理者とプロジェクトのオーナーのみのため、それ以外のユーザーの場合、マージ済みのマージリクエストはプロジェクトに残ります。
• マージルール: Overleaf がプロジェクトのマージルールを回避することはありません。マージリクエストにコンフリクトがある場合、または承認やパイプラインの成功が必要な場合、マージリクエストはオープンのまま残り、Overleaf はユーザーに GitLab でマージしてから同期を続行するよう求めます。
• パイプライン: Overleaf からのコミットは、他のコミットと同様にパイプラインを起動します。プロジェクトでマージリクエストに対してパイプラインを実行し、その成功を必須としている場合、上記のとおり Overleaf からのマージはパイプラインの完了を待ちます。

​

Q&A

デフォルトブランチに強制プッシュできますか？

回答： デフォルトブランチへの強制プッシュは無効のままにしてください。これは GitLab のデフォルト設定で、新しいプロジェクトのデフォルトブランチは保護されており、誰も強制プッシュできません。Overleaf は書き換えられたブランチを引き継ぐことができますが、GitLab 同期は履歴が増えていくだけのデフォルトブランチを前提に設計されています。

連携済みプロジェクトのデフォルトブランチ名を変更できますか？

回答： できません。Overleaf はプロジェクトを連携したときのブランチと同期し続けるため、そのブランチ名が変更または削除されると同期は失敗します。別のブランチと同期するには、プロジェクトの連携を解除してから、リポジトリを新しいプロジェクトにインポートしてください。新しいプロジェクトでは現在のデフォルトブランチが使用されます。