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

Дозвольте користувачам синхронізувати свої проєкти з репозиторіями GitHub або GitHub Enterprise.

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

​

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

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

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

Перейдіть до налаштувань розробника, щоб створити свій застосунок GitHub OAuth, і скопіюйте CLIENT_ID та SECRET.

Примітки: під час створення OAuth App введіть ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback у полі Authorization callback URL. Ayakaleaf Pro формує ту саму адресу з OVERLEAF_SITE_URL, тож у config/variables.env для неї нічого задавати не потрібно.

Потім додайте наведені нижче налаштування до файлів змінних середовища Overleaf.

config/variables.env

# used to encrypt the user's GitHub access token.
# How to generate: `openssl rand -hex 32`
GITHUB_TOKEN_CIPHER_PASSWORD=0123456789ABCDEFG # changed to yours

# Github Sync Settings
GITHUB_SYNC_ENABLED=true
GITHUB_SYNC_CLIENT_ID=
GITHUB_SYNC_CLIENT_SECRET=

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

Перш ніж налаштовувати URL-адресу зворотного виклику GitHub OAuth, переконайтеся, що OVERLEAF_SITE_URL задано правильно.

Якщо ви перебуваєте в регіоні з обмеженим доступом до мережі, вам може знадобитися налаштувати проксі для доступу до GitHub. Встановіть таку змінну середовища: GITHUB_SYNC_PROXY_URL=http://10.0.0.1:10808. Переконайтеся, що використання проксі відповідає місцевому законодавству та нормативним актам.

GITHUB_SYNC_PROXY_URL має бути стандартним прямим HTTP/HTTPS-проксі (наприклад, HTTP-порт Clash). Дзеркала для завантаження з GitHub, як-от gh-proxy.org, не підтримуються.

Не використовуйте 127.0.0.1 як хост проксі. Якщо проксі працює на хост-сервері, використовуйте LAN IP-адресу сервера (наприклад, 192.168.1.xx) і переконайтеся, що проксі налаштовано на прийом з’єднань від пристроїв у локальній мережі.

​

GitHub Enterprise

Підтримка GitHub Enterprise доступна починаючи з v6.3.1. Попередні версії підключаються лише до github.com, і наведені нижче змінні на них не впливають.

За замовчуванням синхронізація з GitHub підключається до github.com. Щоб використовувати GitHub Enterprise Server (самостійно розміщений) або GitHub Enterprise Cloud із резидентністю даних (GHE.com), задайте в GITHUB_SYNC_URL вебадресу свого екземпляра — ту, за якою ви відкриваєте репозиторії в браузері.

config/variables.env

# GitHub Enterprise Server
GITHUB_SYNC_URL=https://github.example.com

# or GitHub Enterprise Cloud with data residency
# GITHUB_SYNC_URL=https://octocorp.ghe.com

Адреси REST і GraphQL API визначаються на основі GITHUB_SYNC_URL так само, як це робить GitHub CLI:

GITHUB_SYNC_URL	REST API	GraphQL API
https://github.com (за замовчуванням)	https://api.github.com	https://api.github.com/graphql
https://SUBDOMAIN.ghe.com	https://api.SUBDOMAIN.ghe.com	https://api.SUBDOMAIN.ghe.com/graphql
https://HOST (будь-яка інша)	https://HOST/api/v3	https://HOST/api/graphql

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

Змінна	Значення за замовчуванням
GITHUB_SYNC_URL	https://github.com
GITHUB_SYNC_API_URL	Визначається на основі GITHUB_SYNC_URL, див. таблицю вище
GITHUB_SYNC_GRAPHQL_URL	Визначається на основі GITHUB_SYNC_API_URL, якщо її задано (/api/v3 замінюється на /api/graphql, інакше додається /graphql), інакше — на основі GITHUB_SYNC_URL

• Створюйте OAuth-застосунок у своєму корпоративному екземплярі (Settings → Developer settings → OAuth Apps): застосунок із github.com там не працює. URL-адреса зворотного виклику та сама: ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback.
• GITHUB_SYNC_URL — це лише вебадреса. Не задавайте в ній адресу API, як-от https://api.github.com чи https://HOST/api/v3, і не додавайте шлях до організації.
• Усі три адреси мають вказувати на один і той самий екземпляр GitHub.

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

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

​

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

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

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

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

​

Q&A

Як прив'язати проєкт до GitHub і синхронізувати його?

Відповідь: У редакторі відкрийте Integrations і натисніть GitHub. Якщо ваш обліковий запис GitHub ще не прив’язано, спершу натисніть Link to your GitHub account. У Export Project to GitHub введіть назву репозиторію, виберіть Private у Repository visibility і натисніть Create a GitHub repository.

Після цього та сама картка відкриває Sync with GitHub, де перелічено нові коміти в GitHub. Натисніть Sync, щоб закомітити свої зміни з Overleaf у гілку за замовчуванням і перенести зміни з GitHub у проєкт. Синхронізація працює в обох напрямках, але запускається лише тоді, коли хтось натискає Sync; синхронізації за розкладом немає. Якщо зміни є з обох боків, Overleaf зливає їх через тимчасову гілку з назвою overleaf-YYYY-MM-DD-HHMMSS. Якщо під час цього злиття виникає конфлікт, злийте гілку в GitHub самостійно, а потім натисніть I have manually merged. Continue.

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

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

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

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

Синхронізація з GitHub показує «Something wrong with GitHub request»

Відповідь: Це повідомлення означає, що сервер не зміг зв’язатися з GitHub, наприклад через проблему з мережею, DNS, TLS або проксі. Виконайте bin/logs web, щоб побачити повну помилку. Якщо серверу потрібен проксі для доступу до GitHub, встановіть GITHUB_SYNC_PROXY_URL.

Чи слід вимкнути «Expire user access tokens» в GitHub OAuth App?

Відповідь: Так. Синхронізація з GitHub не поновлює прострочені токени. Якщо токени з терміном дії ввімкнено, користувачам доведеться знову підключати GitHub щоразу, коли їхній токен спливає.

Чи має мій екземпляр бути доступним з інтернету?

Відповідь: Ні. Прив’язка облікового запису відбувається через браузер користувача, тож адреса зворотного виклику OAuth має лише відкриватися в браузері користувача. Серверу потрібно лише мати доступ до GitHub; якщо для цього потрібен проксі, встановіть GITHUB_SYNC_PROXY_URL. GitHub ніколи не звертається до вашого екземпляра: проєкт синхронізується лише тоді, коли користувач синхронізує його в редакторі.

Прив'язка мого облікового запису GitHub не вдається або повертає мене назад без прив'язки

Відповідь: Перевірте по черзі:

• Відкривайте Overleaf саме за адресою, заданою в OVERLEAF_SITE_URL. GitHub повертає вас на ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback, а ваш вхід існує лише на тій адресі, з якої ви почали, тож інший хост, IP-адреса чи порт приводять на сторінку входу або до повідомлення «Restricted, sorry you don’t have permission to load this page».
• Authorization callback URL в OAuth App має бути ${OVERLEAF_SITE_URL}/user/github-sync/oauth2/callback, з тією самою схемою, хостом і портом.
• Сторінка помилки з Failed to obtain access token from Git server означає, що GitHub не повернув токен: перевірте GITHUB_SYNC_CLIENT_ID і GITHUB_SYNC_CLIENT_SECRET, а також те, що сервер має доступ до GitHub. Виконайте bin/logs web, щоб побачити повну помилку.

Після зміни config/variables.env виконайте bin/up, щоб перестворити контейнери.

Імпорт репозиторію завершується помилкою «EmptyZipFileError: empty_zip_file» або «unzip failed»

Відповідь: Overleaf імпортує zip-архів останнього коміту в гілці за замовчуванням репозиторію, і ця помилка означає, що в архіві немає жодного файлу, який Overleaf може імпортувати. Перевірте гілку за замовчуванням на GitHub:

• Вона містить файли проєкту, а не лише файли, які Overleaf пропускає під час імпорту: dot-файли, як-от .gitignore і .gitmodules (.latexmkrc зберігається), і файли збирання, як-от *.aux, *.log, *.bbl, *.synctex.gz, *.doc і *.docx.
• Файли містяться не лише в підмодулях Git. Архів GitHub залишає підмодулі порожніми папками.
• Очікувані файли містяться в гілці за замовчуванням, а не в іншій гілці. Імпорт завжди використовує гілку за замовчуванням.

Імпорт репозиторію завершується помилкою «connect ECONNREFUSED» до «sharelatex:3054»

Відповідь: V1_HISTORY_URL має значення http://sharelatex:3054, яке наводили старіші версії цієї документації. Порт 3054 належить службі project-history, яка слухає лише всередині контейнера, тоді як V1_HISTORY_URL має вказувати на history-v1. Overleaf зберігає кожен бінарний файл (зображення, PDF) імпортованого репозиторію в history-v1, тому імпорт завершується невдачею; так само не вдається й завантаження такого файлу в редакторі. У своєму docker-compose.yml задайте V1_HISTORY_URL: "http://sharelatex:3100/api" для служби sharelatex (див. Інтеграція з Git) і перестворіть контейнер. Toolkit уже задає це значення; перевірте, чи не перевизначає його docker-compose.override.yml.