Синхронізація з 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 не показує dot-файли, як-от .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.