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

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

Синхронизация с GitLab работает так же, как синхронизация с GitHub: пользователи привязывают свою учётную запись GitLab, экспортируют проекты в новые проекты GitLab, импортируют репозитории GitLab и синхронизируют изменения в обоих направлениях. Функция работает с GitLab.com и с самостоятельно размещённым GitLab версии 15.10 или новее (Community Edition и 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 для OAuth в GitLab убедитесь, что 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 есть конфликт или для него требуется одобрение либо успешный pipeline, он остаётся открытым, и Overleaf предлагает пользователю выполнить слияние в GitLab, а затем продолжить синхронизацию.
• Pipelines: коммиты из Overleaf запускают pipelines, как и любые другие коммиты. Если в вашем проекте pipelines запускаются для merge request и их успешное прохождение обязательно, слияния из Overleaf ожидают их завершения, как описано выше.

​

Q&A

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

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

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

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