Синхронізація з GitLab

Цю функцію розроблено в ayaka-notes/ayakaleaf-pro. Вона доступна починаючи з v6.4.0. Функція все ще перебуває в стадії бета-тестування. Якщо у вас виникнуть проблеми, будемо вдячні за відгук.

Синхронізація з GitLab працює так само, як синхронізація з GitHub: користувачі прив’язують свій обліковий запис GitLab, експортують проєкти в нові проєкти GitLab, імпортують репозиторії GitLab і синхронізують зміни в обох напрямках. Вона працює з GitLab.com і з самостійно керованим GitLab 15.10 або новішим (Community та Enterprise Edition).

​

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

Перед використанням синхронізації з GitLab потрібно спершу ввімкнути git-bridge.

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

Створіть OAuth-застосунок у своєму екземплярі GitLab у розділі User settings → Applications (або Admin area → Applications для застосунку на рівні всього екземпляра):

• Redirect URI: ${OVERLEAF_SITE_URL}/user/gitlab-sync/oauth2/callback
• Confidential: позначено
• Scopes: api

Скопіюйте Application ID та Secret, а потім додайте наведені нижче налаштування до файлів змінних середовища Overleaf.

config/variables.env

# used to encrypt the user's GitLab access and refresh tokens.
# How to generate: `openssl rand -hex 32`
GITLAB_TOKEN_CIPHER_PASSWORD=0123456789ABCDEFG # changed to yours

# GitLab Sync Settings
GITLAB_SYNC_ENABLED=true
GITLAB_SYNC_CLIENT_ID=
GITLAB_SYNC_CLIENT_SECRET=

# Web address of your GitLab, defaults to https://gitlab.com
# GITLAB_SYNC_URL=https://gitlab.example.com

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

Перш ніж налаштовувати redirect URI для GitLab OAuth, переконайтеся, що OVERLEAF_SITE_URL задано правильно.

Токени доступу GitLab спливають через дві години. Overleaf оновлює їх за допомогою токена оновлення, який GitLab видає разом із ними, тож користувачі залишаються прив’язаними, доки не скасують прив’язку або не відкличуть доступ застосунку в GitLab.

​

Самостійно керований GitLab

Задайте в GITLAB_SYNC_URL вебадресу свого екземпляра — ту, за якою ви відкриваєте проєкти в браузері. Адреса REST API визначається на її основі:

Змінна	Значення за замовчуванням
GITLAB_SYNC_URL	https://gitlab.com
GITLAB_SYNC_API_URL	${GITLAB_SYNC_URL}/api/v4

Задавайте GITLAB_SYNC_API_URL лише тоді, коли ваш екземпляр надає API за іншою адресою, наприклад за API-шлюзом.

• Створюйте OAuth-застосунок в екземплярі, заданому в GITLAB_SYNC_URL: застосунок із gitlab.com не працює в самостійно керованому екземплярі.
• GITLAB_SYNC_URL — це лише вебадреса. Не додавайте /api/v4 чи шлях до групи.

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

Прив’язані облікові записи та проєкти належать до екземпляра, з яким їх було прив’язано. Перш ніж перемкнути GITLAB_SYNC_URL на інший екземпляр, попросіть користувачів скасувати прив’язку своїх облікових записів і проєктів GitLab.

Якщо ви перебуваєте в регіоні з обмеженим доступом до мережі, вам може знадобитися налаштувати проксі для доступу до GitLab. Встановіть таку змінну середовища: GITLAB_SYNC_PROXY_URL=http://10.0.0.1:10808. Це має бути стандартний прямий HTTP/HTTPS-проксі, і він не повинен використовувати 127.0.0.1.

​

Хто може прив’язувати та синхронізувати

Як і в Overleaf Cloud, лише власник проєкту може прив’язати проєкт до репозиторію GitLab. Після прив’язки синхронізувати його може кожен співавтор із правом редагування.

Дія	Хто може це зробити
Експорт проєкту в новий репозиторій GitLab	Власник проєкту
Імпорт репозиторію GitLab у новий проєкт	Будь-який користувач, який стає власником нового проєкту
Pull, push і злиття прив’язаного проєкту	Власник і співавтори з правом редагування
Скасування прив’язки проєкту до репозиторію	Власник проєкту

• Overleaf взаємодіє з GitLab від імені облікового запису GitLab користувача, який виконує синхронізацію, тому кожен співавтор, який синхронізує, прив’язує власний обліковий запис GitLab і повинен мати дозвіл на push у гілку за замовчуванням репозиторію.
• Співавтори з правом лише перегляду не можуть використовувати синхронізацію з GitLab для проєкту.

​

Як працює синхронізація з GitLab

• Дозволи: користувачі повинні мати дозвіл на push у гілку за замовчуванням прив’язаного проєкту. Якщо гілка за замовчуванням захищена й користувач не може виконувати в неї push, Overleaf пропонує йому звернутися до власника проєкту, як і у випадку з репозиторієм, до якого втрачено доступ.
• Злиття: якщо проєкт змінено і в Overleaf, і в GitLab, Overleaf фіксує свої зміни в тимчасовій гілці з назвою overleaf-YYYY-MM-DD-HHMMSS і зливає її через merge request, оскільки GitLab не має API для злиття гілок без нього. Після злиття Overleaf видаляє тимчасову гілку та merge request. Видаляти merge request у GitLab можуть лише адміністратори та власники проєктів, тож для інших користувачів злитий merge request залишається в проєкті.
• Правила злиття: Overleaf ніколи не обходить правила злиття проєкту. Якщо merge request має конфлікт або потребує схвалення чи успішного пайплайна, він залишається відкритим, і Overleaf пропонує користувачеві злити його в GitLab, а потім продовжити синхронізацію.
• Пайплайни: коміти з Overleaf запускають пайплайни, як і будь-які інші коміти. Якщо ваш проєкт запускає пайплайни для merge request і вимагає їх успішного проходження, злиття з Overleaf очікують на них, як описано вище.

​

Q&A

Чи можна виконувати force push у гілку за замовчуванням?

Відповідь: Будь ласка, залишайте force push у гілку за замовчуванням вимкненим. Це типова поведінка GitLab: гілка за замовчуванням нового проєкту захищена, і ніхто не може виконувати в неї force push. Overleaf може підхопити переписану гілку, але синхронізацію з GitLab розроблено для гілки за замовчуванням, історія якої лише зростає.

Чи можна перейменувати гілку за замовчуванням прив'язаного проєкту?

Відповідь: Ні. Overleaf продовжує синхронізуватися з гілкою, до якої було прив’язано проєкт, тому після перейменування або видалення цієї гілки синхронізація завершуватиметься помилкою. Щоб синхронізуватися з іншою гілкою, скасуйте прив’язку проєкту, а потім імпортуйте репозиторій у новий проєкт, який використовуватиме поточну гілку за замовчуванням.