Синхронизация с Gitea

Эта функция разработана в ayaka-notes/ayakaleaf-pro. Она появилась в v6.3.2 как ранняя предварительная версия и будет официально выпущена в v6.4.0, поэтому её конфигурация и поведение ещё могут измениться. Если у вас возникнут проблемы, пожалуйста, сообщите нам.

Синхронизация с Gitea работает так же, как синхронизация с GitHub и синхронизация с GitLab: пользователи привязывают свою учётную запись Gitea, экспортируют проекты в новые репозитории Gitea, импортируют репозитории Gitea и синхронизируют изменения в обоих направлениях. Функция работает с Gitea версии 1.23 или новее — на gitea.com или в вашем собственном экземпляре.

​

Настройка синхронизации с Gitea

Перед использованием синхронизации с Gitea необходимо сначала включить git-bridge.

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

Создайте OAuth2-приложение в вашем экземпляре Gitea в разделе Settings → Applications → Manage OAuth2 applications (или Site Administration → Integrations → Applications для приложения на уровне всего экземпляра):

• 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

Перед настройкой Redirect URI в Gitea убедитесь, что OVERLEAF_SITE_URL задан правильно.

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

Область	Для чего используется
write:repository	Репозитории, их файлы (включая CI-воркфлоу в .gitea/workflows), ветки и pull requests
write:user	Создание репозитория пользователя при экспорте (Gitea требует её для POST /user/repos)
write:organization	Получение списка организаций пользователя и создание в одной из них репозитория при экспорте

Gitea показывает эти области, когда пользователь авторизует приложение, и ограничивает ими токен.

Токены доступа Gitea истекают через час ([oauth2] ACCESS_TOKEN_EXPIRATION_TIME). Overleaf обновляет их с помощью токена обновления, который Gitea выдаёт вместе с ними, в том числе когда Gitea делает токены обновления одноразовыми (INVALIDATE_REFRESH_TOKENS = true), поэтому пользователи остаются привязанными, пока не отвяжут учётную запись или не отзовут доступ приложения в Gitea.

​

Ваш экземпляр Gitea

Задайте в GITEA_SYNC_URL веб-адрес вашего экземпляра — его 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 — это только веб-адрес. Не добавляйте к нему /api/v1 или путь пользователя либо организации.
• Overleaf создаёт коммиты через файловый API Gitea, которому нужен веб-редактор: оставьте [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 в новый проект	Любой пользователь, который становится владельцем нового проекта
Pull, push и слияние привязанного проекта	Владелец и соавторы с правами на редактирование
Отвязка проекта от репозитория	Владелец проекта

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

​

Как работает синхронизация с Gitea

• Права доступа: пользователи должны иметь право на push в ветку по умолчанию привязанного репозитория. Если правило защиты ветки не позволяет пользователю выполнить push в неё, Overleaf предлагает ему связаться с владельцем проекта — так же, как в случае с репозиторием, к которому был утрачен доступ.
• Слияние: если проект изменился и в Overleaf, и в Gitea, Overleaf фиксирует свои изменения во временной ветке с именем overleaf-YYYY-MM-DD-HHMMSS и выполняет её слияние через pull request со стилем слияния по умолчанию для репозитория, поскольку в Gitea нет API для слияния веток без него. После слияния Overleaf удаляет временную ветку; слитый pull request остаётся в репозитории в качестве записи.
• Правила слияния: Overleaf никогда не обходит защиту веток репозитория. Если в pull request есть конфликт или для него требуются одобрения либо успешные проверки статуса, он остаётся открытым, и Overleaf предлагает пользователю выполнить слияние в Gitea, а затем продолжить синхронизацию.
• CI-воркфлоу: Overleaf не показывает dotfiles, такие как .gitea/workflows/, и оставляет их в репозитории без изменений. Коммиты из Overleaf запускают Gitea Actions, как и любые другие коммиты.

​

Q&A

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

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

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

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

Поддерживает ли синхронизация с Gitea Git LFS?

Ответ: Нет. Проекты Overleaf не поддерживают Git Large File Storage. Файлы, отслеживаемые Git LFS, отображаются в Overleaf как файлы-указатели LFS, а не как их содержимое. Вместо этого добавляйте изображения и PDF в репозиторий напрямую.

Работает ли она с репозиториями SHA-256?

Ответ: Пока нет. Overleaf сравнивает файлы по их идентификаторам SHA-1, поэтому в репозитории, созданном с форматом объектов SHA-256, каждый pull перезаписывает все файлы, даже неизменённые. Ничего не теряется, но, пожалуйста, используйте формат SHA-1 по умолчанию.

Работает ли она с Forgejo?

Ответ: Синхронизация с Gitea разработана и протестирована только для Gitea.