> ## Documentation Index
> Fetch the complete documentation index at: https://ayakaleaf-pro.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Синхронізація з Gitea

> [!NOTE]
>
> Цю функцію розроблено в [ayaka-notes/ayakaleaf-pro](https://github.com/ayaka-notes/ayakaleaf-pro). Вона з'явилася у v6.3.2 як рання попередня версія й буде офіційно випущена у v6.4.0, тож її конфігурація та поведінка ще можуть змінитися. Якщо у вас виникнуть проблеми, будемо вдячні за відгук.

Синхронізація з Gitea працює так само, як [синхронізація з GitHub](https://ayakaleaf-pro.mintlify.site/uk/on-premises/configuration/overleaf-toolkit/github-synchronisation.md) і [синхронізація з GitLab](https://ayakaleaf-pro.mintlify.site/uk/on-premises/configuration/overleaf-toolkit/gitlab-synchronisation.md): користувачі прив'язують свій обліковий запис Gitea, експортують проєкти в нові репозиторії Gitea, імпортують репозиторії Gitea і синхронізують зміни в обох напрямках. Вона працює з Gitea 1.23 або новішим — на gitea.com або у вашому власному екземплярі.

### Налаштування синхронізації з Gitea

> [!WARNING]
>
> Перед використанням синхронізації з Gitea потрібно спершу ввімкнути [git-bridge](https://ayakaleaf-pro.mintlify.site/uk/on-premises/configuration/overleaf-toolkit/git-integration.md).
>
> ```dotenv title="config/overleaf.rc" theme={null}
> 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.

```dotenv title="config/variables.env" wrap theme={null}
# 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
```

> [!WARNING]
>
> Перш ніж налаштовувати 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-шлюзом.

> [!WARNING]
>
> * Створюйте OAuth2-застосунок в екземплярі, заданому в `GITEA_SYNC_URL`: застосунок з іншого екземпляра не працює.
> * `GITEA_SYNC_URL` — це лише вебадреса. Не додавайте `/api/v1` чи шлях до користувача або організації.
> * Overleaf створює коміти через файловий API Gitea, для якого потрібен вебредактор: залишайте `[repository.editor]` увімкненим (так є за замовчуванням).

> [!NOTE]
>
> Якщо ваш екземпляр використовує сертифікат від приватного центру сертифікації (CA), змонтуйте сертифікат CA в контейнер і вкажіть шлях до нього в `NODE_EXTRA_CA_CERTS`, наприклад `NODE_EXTRA_CA_CERTS=/var/lib/overleaf/certs/gitea-ca.pem`.

> [!CAUTION]
>
> Прив'язані облікові записи та проєкти належать до екземпляра, з яким їх було прив'язано. Перш ніж перемкнути `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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.