GitHub 同期

ユーザーが自分のプロジェクトを GitHub または GitHub Enterprise のリポジトリと同期できるようにします。

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

​

GitHub 同期のセットアップ

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

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

開発者設定 にアクセスして GitHub OAuth アプリケーションを作成し、CLIENT_ID と SECRET をコピーします。

注意: OAuth App を作成する際は、Authorization callback URL に ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback を入力してください。Ayakaleaf Pro は OVERLEAF_SITE_URL から同じアドレスを構築するため、config/variables.env でこれを設定する必要はありません。

次に、Overleaf の環境変数ファイルに以下の設定を追加します。

config/variables.env

# used to encrypt the user's GitHub access token.
# How to generate: `openssl rand -hex 32`
GITHUB_TOKEN_CIPHER_PASSWORD=0123456789ABCDEFG # changed to yours

# Github Sync Settings
GITHUB_SYNC_ENABLED=true
GITHUB_SYNC_CLIENT_ID=
GITHUB_SYNC_CLIENT_SECRET=

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

GitHub OAuth のコールバック URL を設定する前に、OVERLEAF_SITE_URL が正しく設定されていることを確認してください。

ネットワークアクセスが制限されている地域にいる場合は、GitHub にアクセスするためにプロキシの設定が必要になることがあります。次の環境変数を設定してください: GITHUB_SYNC_PROXY_URL=http://10.0.0.1:10808。プロキシの使用が現地の法令を遵守していることを確認してください。

GITHUB_SYNC_PROXY_URL は標準的な HTTP/HTTPS フォワードプロキシ（Clash の HTTP ポートなど）である必要があります。gh-proxy.org などの GitHub ダウンロードミラーはサポートされていません。

プロキシのホストに 127.0.0.1 を使用しないでください。プロキシがホストサーバー上で動作している場合は、サーバーの LAN IP アドレス（192.168.1.xx など）を使用し、プロキシがローカルネットワーク上のデバイスからの接続を受け付けるよう設定されていることを確認してください。

​

GitHub Enterprise

GitHub Enterprise のサポートは v6.3.1 以降で導入されています。それ以前のバージョンは github.com にのみ接続し、以下の変数は効果がありません。

デフォルトでは、GitHub 同期は github.com に接続します。GitHub Enterprise Server（セルフホスト）またはデータレジデンシー付きの GitHub Enterprise Cloud（GHE.com）を使用するには、GITHUB_SYNC_URL にインスタンスの Web アドレス（ブラウザーでリポジトリを開く際のアドレス）を設定します。

config/variables.env

# GitHub Enterprise Server
GITHUB_SYNC_URL=https://github.example.com

# or GitHub Enterprise Cloud with data residency
# GITHUB_SYNC_URL=https://octocorp.ghe.com

REST API と GraphQL API のエンドポイントは、GitHub CLI と同じ方法で GITHUB_SYNC_URL から導出されます。

GITHUB_SYNC_URL	REST API	GraphQL API
https://github.com（デフォルト）	https://api.github.com	https://api.github.com/graphql
https://SUBDOMAIN.ghe.com	https://api.SUBDOMAIN.ghe.com	https://api.SUBDOMAIN.ghe.com/graphql
https://HOST（その他）	https://HOST/api/v3	https://HOST/api/graphql

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

変数	デフォルト
GITHUB_SYNC_URL	https://github.com
GITHUB_SYNC_API_URL	GITHUB_SYNC_URL から導出（上の表を参照）
GITHUB_SYNC_GRAPHQL_URL	GITHUB_SYNC_API_URL が設定されている場合はそこから導出（/api/v3 は /api/graphql になり、それ以外の場合は /graphql が付加される）、設定されていない場合は GITHUB_SYNC_URL から導出

• OAuth アプリケーションはエンタープライズインスタンス上で作成してください（Settings → Developer settings → OAuth Apps）。github.com で作成したアプリケーションはそこでは動作しません。コールバック URL は同じく ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback です。
• GITHUB_SYNC_URL には Web アドレスのみを指定します。https://api.github.com や https://HOST/api/v3 のような API アドレスを設定したり、組織のパスを付け加えたりしないでください。
• 3 つのアドレスはすべて同じ GitHub インスタンスを指している必要があります。

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

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

​

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

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

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

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

​

Q&A

プロジェクトを GitHub に連携して同期するにはどうすればよいですか？

回答： エディターで Integrations を開き、GitHub をクリックします。GitHub アカウントがまだ連携されていない場合は、まず Link to your GitHub account をクリックします。Export Project to GitHub でリポジトリ名を入力し、Repository visibility で Private を選択して、Create a GitHub repository をクリックします。

その後、同じカードから Sync with GitHub が開き、GitHub 上の新しいコミットが一覧表示されます。Sync をクリックすると、Overleaf での変更がデフォルトブランチにコミットされ、GitHub での変更がプロジェクトに取り込まれます。同期は双方向ですが、誰かが Sync をクリックしたときにのみ実行され、定期的な同期はありません。両方で変更があった場合、Overleaf は overleaf-YYYY-MM-DD-HHMMSS という名前の一時ブランチを介してマージします。そのマージでコンフリクトが発生した場合は、GitHub 上で自分でそのブランチをマージしてから、I have manually merged. Continue をクリックしてください。

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

回答： 推奨しません。Overleaf は強制プッシュを検出して警告を表示し、書き換えられたブランチを引き継いで、前回の同期以降に Overleaf で行われた変更をマージします。予期しない事態を避けるため、リポジトリの設定でデフォルトブランチへの強制プッシュを禁止してください。

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

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

GitHub 同期で「Something wrong with GitHub request」と表示される

回答： このメッセージは、ネットワーク、DNS、TLS、プロキシの問題などにより、サーバーが GitHub にアクセスできなかったことを意味します。bin/logs web を実行して完全なエラーを確認してください。サーバーが GitHub にアクセスするためにプロキシが必要な場合は、GITHUB_SYNC_PROXY_URL を設定してください。

GitHub OAuth App の「Expire user access tokens」は無効にすべきですか？

回答： はい。GitHub 同期は期限切れのトークンを更新しません。トークンの有効期限を有効にしていると、ユーザーはトークンが期限切れになるたびに GitHub を再接続する必要があります。

インスタンスはインターネットからアクセス可能である必要がありますか？

回答： いいえ。アカウントの連携はユーザーのブラウザを経由して行われるため、OAuth コールバックのアドレスはユーザーのブラウザで開ければ十分です。サーバーは GitHub にアクセスできればよく、そのためにプロキシが必要な場合は GITHUB_SYNC_PROXY_URL を設定してください。GitHub がインスタンスを呼び出すことはありません。プロジェクトは、ユーザーがエディターで同期したときにのみ同期されます。

GitHub アカウントの連携に失敗する、または連携されずに戻されてしまう

回答： 次の項目を順に確認してください:

• OVERLEAF_SITE_URL に設定したアドレスとまったく同じアドレスで Overleaf を開いてください。GitHub は ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback に戻し、ログイン状態は操作を開始したアドレスでのみ有効なため、別のホスト、IP、ポートではログインページや「Restricted, sorry you don’t have permission to load this page」で終わってしまいます。
• OAuth App の Authorization callback URL は、スキーム、ホスト、ポートが同じ ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback である必要があります。
• Failed to obtain access token from Git server というエラーページは、GitHub がトークンを返さなかったことを意味します。GITHUB_SYNC_CLIENT_ID と GITHUB_SYNC_CLIENT_SECRET、およびサーバーが GitHub にアクセスできることを確認してください。完全なエラーを確認するには bin/logs web を実行してください。

config/variables.env を変更した後は、bin/up を実行してコンテナを再作成してください。

リポジトリのインポートが「EmptyZipFileError: empty_zip_file」または「unzip failed」で失敗する

回答： Overleaf はリポジトリのデフォルトブランチの最新コミットの zip アーカイブをインポートします。このエラーは、そのアーカイブに Overleaf がインポートできるファイルが含まれていないことを意味します。GitHub でデフォルトブランチを確認してください:

• インポート時に Overleaf がスキップするファイルだけでなく、プロジェクトファイルが含まれていること。スキップされるのは、.gitignore や .gitmodules などのドットファイル（.latexmkrc は保持されます）や、*.aux、*.log、*.bbl、*.synctex.gz、*.doc、*.docx などのビルドファイルです。
• ファイルが Git サブモジュール内にしか存在しないわけではないこと。GitHub のアーカイブでは、サブモジュールは空のフォルダーになります。
• 期待するファイルが別のブランチではなく、デフォルトブランチにあること。インポートでは常にデフォルトブランチが使用されます。

リポジトリのインポートが「sharelatex:3054」への「connect ECONNREFUSED」で失敗する

回答： V1_HISTORY_URL が http://sharelatex:3054 に設定されています。これはこのドキュメントの古いバージョンで示されていた値です。ポート 3054 は project-history サービスで、コンテナ内でのみリッスンしていますが、V1_HISTORY_URL は history-v1 を指している必要があります。Overleaf はインポートしたリポジトリのすべてのバイナリファイル（画像、PDF）を history-v1 に保存するため、インポートが失敗します。エディターでそのようなファイルをアップロードした場合も同様に失敗します。docker-compose.yml の sharelatex サービスで V1_HISTORY_URL: "http://sharelatex:3100/api" を設定し（Git 連携を参照）、コンテナを再作成してください。Toolkit はすでにこの値を設定しています。docker-compose.override.yml で上書きされていないことを確認してください。