Синхронизация с 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

Перейдите в настройки разработчика, чтобы создать OAuth-приложение GitHub, и скопируйте ваши CLIENT_ID и SECRET.

Примечание: при создании OAuth App укажите ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback в поле Authorization callback URL. 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

Перед настройкой URL обратного вызова OAuth в GitHub убедитесь, что OVERLEAF_SITE_URL задан правильно.

Если вы находитесь в регионе с ограниченным доступом к сети, для доступа к GitHub может потребоваться прокси. Задайте следующую переменную окружения: GITHUB_SYNC_PROXY_URL=http://10.0.0.1:10808. Убедитесь, что использование прокси соответствует местному законодательству и нормативным актам.

GITHUB_SYNC_PROXY_URL должен быть стандартным прямым HTTP/HTTPS-прокси (например, HTTP-порт Clash). Зеркала для загрузки с GitHub, такие как gh-proxy.org, не поддерживаются.

Не используйте 127.0.0.1 в качестве хоста прокси. Если прокси работает на хост-сервере, используйте 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 веб-адрес вашего экземпляра — тот, по которому вы открываете репозитории в браузере.

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 и GraphQL API определяются на основе GITHUB_SYNC_URL так же, как это делает GitHub CLI:

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-шлюзом:

Переменная	Значение по умолчанию
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 — это только веб-адрес. Не указывайте в нём адрес API, например https://api.github.com или https://HOST/api/v3, и не добавляйте путь организации.
• Все три адреса должны указывать на один и тот же экземпляр 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 в новый проект	Любой пользователь, который становится владельцем нового проекта
Pull, push и слияние привязанного проекта	Владелец и соавторы с правами на редактирование
Отвязка проекта от репозитория	Владелец проекта

• Overleaf взаимодействует с GitHub от имени учётной записи GitHub пользователя, выполняющего синхронизацию, поэтому каждый соавтор, который синхронизирует проект, привязывает собственную учётную запись GitHub и должен иметь право на push в ветку по умолчанию репозитория.
• Соавторы с правами только на просмотр не могут использовать синхронизацию с GitHub для этого проекта.

​

Q&A

Как привязать проект к GitHub и синхронизировать его?

Ответ: В редакторе откройте Integrations и нажмите GitHub. Если ваша учётная запись GitHub ещё не привязана, сначала нажмите Link to your GitHub account. В разделе Export Project to GitHub введите имя репозитория, выберите Private в разделе Repository visibility и нажмите Create a GitHub repository.

После этого та же карточка открывает Sync with GitHub, где перечислены новые коммиты в GitHub. Нажмите Sync, чтобы закоммитить изменения из Overleaf в ветку по умолчанию и перенести изменения из GitHub в проект. Синхронизация работает в обе стороны, но выполняется только тогда, когда кто-то нажимает Sync; синхронизации по расписанию нет. Если изменения есть с обеих сторон, Overleaf выполняет слияние через временную ветку с именем overleaf-YYYY-MM-DD-HHMMSS. Если при этом слиянии возникает конфликт, слейте эту ветку в GitHub самостоятельно, а затем нажмите I have manually merged. Continue.

Можно ли выполнять force push в ветку по умолчанию?

Ответ: Мы не рекомендуем этого делать. Overleaf обнаруживает force push, предупреждает о нём и принимает переписанную ветку, выполняя слияние изменений, сделанных в Overleaf с момента последней синхронизации. Чтобы избежать неожиданностей, защитите ветку по умолчанию от force push в настройках репозитория.

Можно ли переименовать ветку по умолчанию привязанного проекта?

Ответ: Пожалуйста, не делайте этого. Overleaf продолжает синхронизацию с той веткой, к которой был привязан проект. Чтобы синхронизироваться с другой веткой, отвяжите проект, а затем импортируйте репозиторий в новый проект — он будет использовать текущую ветку по умолчанию.

Синхронизация с GitHub показывает «Something wrong with GitHub request»

Ответ: Это сообщение означает, что серверу не удалось связаться с GitHub, например из-за проблемы с сетью, DNS, TLS или прокси. Выполните bin/logs web, чтобы увидеть полную ошибку. Если серверу нужен прокси для доступа к GitHub, задайте GITHUB_SYNC_PROXY_URL.

Нужно ли отключать «Expire user access tokens» в GitHub OAuth App?

Ответ: Да. Синхронизация с GitHub не обновляет истёкшие токены. Если истечение токенов включено, пользователям придётся заново подключать GitHub каждый раз, когда истекает их токен.

Должен ли мой экземпляр быть доступен из интернета?

Ответ: Нет. Привязка учётной записи выполняется через браузер пользователя, поэтому адрес обратного вызова OAuth должен лишь открываться в браузере пользователя. Серверу нужен только доступ к GitHub; если для этого нужен прокси, задайте GITHUB_SYNC_PROXY_URL. GitHub никогда не обращается к вашему экземпляру: проект синхронизируется только тогда, когда пользователь синхронизирует его в редакторе.

Привязка учётной записи GitHub завершается ошибкой или возвращает меня назад без привязки

Ответ: Проверьте по порядку:

• Открывайте Overleaf точно по адресу, заданному в OVERLEAF_SITE_URL. GitHub возвращает вас на ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback, а ваш вход существует только на том адресе, с которого вы начали, поэтому другой хост, IP-адрес или порт приводит на страницу входа или к сообщению «Restricted, sorry you don’t have permission to load this page».
• Authorization callback URL в OAuth App должен быть ${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 пропускает при импорте: dot-файлы, такие как .gitignore и .gitmodules (.latexmkrc сохраняется), и файлы сборки, такие как *.aux, *.log, *.bbl, *.synctex.gz, *.doc и *.docx.
• Файлы находятся не только внутри подмодулей Git. В архиве GitHub подмодули остаются пустыми папками.
• Нужные вам файлы находятся в ветке по умолчанию, а не в другой ветке. Импорт всегда использует ветку по умолчанию.

Импорт репозитория завершается ошибкой «connect ECONNREFUSED» к «sharelatex:3054»

Ответ: V1_HISTORY_URL задана как http://sharelatex:3054 — значение, которое приводилось в старых версиях этой документации. Порт 3054 принадлежит сервису project-history, который слушает только внутри контейнера, тогда как V1_HISTORY_URL должна указывать на history-v1. Overleaf сохраняет каждый двоичный файл (изображения, PDF) импортируемого репозитория в history-v1, поэтому импорт завершается ошибкой; загрузка такого файла в редакторе завершается ошибкой точно так же. В вашем docker-compose.yml задайте V1_HISTORY_URL: "http://sharelatex:3100/api" для сервиса sharelatex (см. Интеграция с Git) и пересоздайте контейнер. Toolkit уже задаёт это значение; проверьте, что docker-compose.override.yml его не переопределяет.