Gitea 同期

この機能は ayaka-notes/ayakaleaf-pro によって開発されたものです。v6.3.2 でアーリープレビューとして導入され、v6.4.0 で正式リリースされる予定です。そのため、設定や動作が今後変更される可能性があります。問題があればぜひフィードバックをお寄せください。

Gitea 同期は GitHub 同期 や GitLab 同期 と同様に動作します。ユーザーは Gitea アカウントを連携し、プロジェクトを新しい Gitea リポジトリにエクスポートしたり、Gitea リポジトリをインポートしたり、双方向で変更を同期したりできます。gitea.com または独自のインスタンス上の Gitea 1.23 以降で動作します。

​

Gitea 同期のセットアップ

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

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

Gitea インスタンスの Settings → Applications → Manage OAuth2 applications（インスタンス全体のアプリケーションの場合は Site Administration → Integrations → Applications）で OAuth2 アプリケーションを作成します。

• Application name: 例: Overleaf。ユーザーがアプリケーションを承認する際に表示されます
• Redirect URIs: ${OVERLEAF_SITE_URL}/user/gitea-sync/oauth2/callback
• Confidential client: チェックを入れる

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

config/variables.env

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

# Gitea Sync Settings
GITEA_SYNC_ENABLED=true
GITEA_SYNC_CLIENT_ID=
GITEA_SYNC_CLIENT_SECRET=

# Web address of your Gitea (its ROOT_URL), defaults to https://gitea.com
# GITEA_SYNC_URL=https://gitea.example.com

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

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

Overleaf は、ユーザーがアカウントを連携する時点で同期に必要なすべての権限を要求するため、権限不足のためにユーザーが再度連携する必要はありません。

スコープ	用途
write:repository	リポジトリ、そのファイル（.gitea/workflows 以下の CI ワークフローを含む）、ブランチ、プルリクエスト
write:user	エクスポート時にユーザーのリポジトリを作成（Gitea は POST /user/repos でこれを要求します）
write:organization	ユーザーの組織の一覧取得と、エクスポート時に組織のリポジトリを作成

Gitea は、ユーザーがアプリケーションを承認する際にこれらのスコープを表示し、トークンをこれらのスコープに制限します。

Gitea のアクセストークンは 1 時間で有効期限が切れます（[oauth2] ACCESS_TOKEN_EXPIRATION_TIME）。Overleaf は Gitea がアクセストークンと一緒に発行するリフレッシュトークンを使ってトークンを更新します。Gitea がリフレッシュトークンを使い捨てにする設定（INVALIDATE_REFRESH_TOKENS = true）の場合も同様です。そのため、ユーザーは連携を解除するか Gitea でアプリケーションを取り消すまで連携された状態が維持されます。

​

Gitea インスタンス

GITEA_SYNC_URL にインスタンスの Web アドレス、つまりその ROOT_URL（ブラウザーでリポジトリを開く際のアドレス）を設定します。REST API はこのアドレスから導出されます。

変数	デフォルト
GITEA_SYNC_URL	https://gitea.com
GITEA_SYNC_API_URL	${GITEA_SYNC_URL}/api/v1

サブパスで提供されている Gitea にも対応しています。例: GITEA_SYNC_URL=https://example.com/gitea。GITEA_SYNC_API_URL は、インスタンスが別の場所（API ゲートウェイの背後など）で API を提供している場合にのみ設定してください。

• OAuth2 アプリケーションは GITEA_SYNC_URL に設定したインスタンス上で作成してください。別のインスタンスで作成したアプリケーションは動作しません。
• GITEA_SYNC_URL には Web アドレスのみを指定します。/api/v1 やユーザー・組織のパスを付け加えないでください。
• Overleaf は Gitea のファイル API を使ってコミットしますが、この API には Web エディターが必要です。[repository.editor] は有効のままにしてください（デフォルト）。

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

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

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

​

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

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

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

• Overleaf は同期を行うユーザーの Gitea アカウントを使って Gitea とやり取りします。そのため、同期を行う共同編集者はそれぞれ自分の Gitea アカウントを連携し、リポジトリのデフォルトブランチへのプッシュが許可されている必要があります。
• 閲覧のみの共同編集者は、そのプロジェクトで Gitea 同期を使用できません。
• Overleaf でアカウントの連携を解除すると、そのトークンは破棄されます。Gitea にはトークンを取り消す API がないため、必要に応じて Gitea の Settings → Applications でも承認を取り消してください。

​

Gitea での同期の仕組み

• 権限: ユーザーは、連携されたリポジトリのデフォルトブランチへのプッシュが許可されている必要があります。ブランチ保護ルールによってユーザーがプッシュできない場合、アクセス権を失ったリポジトリの場合と同様に、Overleaf はプロジェクトのオーナーに連絡するよう求めます。
• マージ: Overleaf と Gitea の両方でプロジェクトが変更された場合、Gitea にはプルリクエストなしでブランチをマージする API がないため、Overleaf は変更を overleaf-YYYY-MM-DD-HHMMSS という名前の一時ブランチにコミットし、リポジトリのデフォルトのマージスタイルでプルリクエストを通じてマージします。マージ後、Overleaf は一時ブランチを削除します。マージ済みのプルリクエストは記録としてリポジトリに残ります。
• マージルール: Overleaf がリポジトリのブランチ保護を回避することはありません。プルリクエストにコンフリクトがある場合、または承認やステータスチェックの成功が必要な場合、プルリクエストはオープンのまま残り、Overleaf はユーザーに Gitea でマージしてから同期を続行するよう求めます。
• CI ワークフロー: Overleaf は .gitea/workflows/ などのドットファイルを表示せず、リポジトリ内のものをそのまま残します。Overleaf からのコミットは、他のコミットと同様に Gitea Actions を起動します。

​

Q&A

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

回答： デフォルトブランチへの強制プッシュは、ブランチ保護ルールなどを使って無効のままにしてください。Overleaf は書き換えられたブランチを引き継ぐことができますが、Gitea 同期は履歴が増えていくだけのデフォルトブランチを前提に設計されています。

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

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

Gitea 同期は Git LFS に対応していますか？

回答： いいえ。Overleaf のプロジェクトは Git Large File Storage に対応していません。Git LFS で管理されているファイルは、その内容ではなく LFS ポインターファイルとして Overleaf に表示されます。画像や PDF は Git LFS を使わずにリポジトリへ直接コミットしてください。

SHA-256 リポジトリで動作しますか？

回答： まだ対応していません。Overleaf はファイルを SHA-1 ID で比較するため、SHA-256 オブジェクト形式で作成されたリポジトリでは、プルのたびに変更されていないファイルも含めてすべてのファイルが書き換えられます。データが失われることはありませんが、デフォルトの SHA-1 形式を使用してください。

Forgejo で動作しますか？

回答： Gitea 同期は Gitea のみを対象として開発・テストされています。