> ## 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.

# Синхронизация с GitHub

> Позвольте пользователям синхронизировать свои проекты с репозиториями GitHub или GitHub Enterprise.

> [!NOTE]
>
> Эта функция разработана в [ayaka-notes/ayakaleaf-pro](https://github.com/ayaka-notes/ayakaleaf-pro) и доработана в [yu-i-i/overleaf-cep](https://github.com/yu-i-i/overleaf-cep). Она доступна начиная с версии v6.2.0 и всё ещё находится в статусе бета. Если у вас возникнут проблемы, пожалуйста, сообщите нам.

![](https://mintcdn.com/ayakaleaf-pro/UZ_4Jfz7cU6MnXtE/images/on-premises/image-36.png?fit=max\&auto=format\&n=UZ_4Jfz7cU6MnXtE\&q=85\&s=fd5305cbb4ea8505b5eab6f41f90a57c)

![](https://mintcdn.com/ayakaleaf-pro/UZ_4Jfz7cU6MnXtE/images/on-premises/image-39.png?fit=max\&auto=format\&n=UZ_4Jfz7cU6MnXtE\&q=85\&s=1d8103102915872ba94119bb00fa58e0)

![](https://mintcdn.com/ayakaleaf-pro/UZ_4Jfz7cU6MnXtE/images/on-premises/image-35.png?fit=max\&auto=format\&n=UZ_4Jfz7cU6MnXtE\&q=85\&s=18c0d0917b5c3768593a608a53b6c19c)

![](https://mintcdn.com/ayakaleaf-pro/UZ_4Jfz7cU6MnXtE/images/on-premises/image-40.png?fit=max\&auto=format\&n=UZ_4Jfz7cU6MnXtE\&q=85\&s=7ebf71a5528a1b22e1e2c7f17a71b49a)

### Настройка синхронизации с GitHub

> [!WARNING]
>
> Перед использованием синхронизации с GitHub необходимо сначала включить [git-bridge](https://ayakaleaf-pro.mintlify.site/ru/on-premises/configuration/overleaf-toolkit/integrations/git-integration.md).
>
> ```dotenv title="config/overleaf.rc" theme={null}
> GIT_BRIDGE_ENABLED=true
> ```

Перейдите в [настройки разработчика](https://github.com/settings/developers), чтобы создать OAuth-приложение GitHub, и скопируйте ваши `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.

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

> [!WARNING]
>
> Перед настройкой URL обратного вызова OAuth в GitHub убедитесь, что `OVERLEAF_SITE_URL` задан правильно.

Если вы находитесь в регионе с ограниченным доступом к сети, для доступа к GitHub может потребоваться прокси. Задайте следующую переменную окружения: `GITHUB_SYNC_PROXY_URL=http://10.0.0.1:10808`. Убедитесь, что использование прокси соответствует местному законодательству и нормативным актам.

> [!WARNING]
>
> `GITHUB_SYNC_PROXY_URL` должен быть стандартным прямым HTTP/HTTPS-прокси (например, HTTP-порт Clash). Зеркала для загрузки с GitHub, такие как `gh-proxy.org`, не поддерживаются.

> [!WARNING]
>
> Не используйте `127.0.0.1` в качестве хоста прокси. Если прокси работает на хост-сервере, используйте IP-адрес сервера в локальной сети (например, `192.168.1.xx`) и убедитесь, что прокси настроен на приём подключений от устройств локальной сети.

### GitHub Enterprise

> [!NOTE]
>
> Поддержка GitHub Enterprise доступна начиная с версии v6.3.1. Более ранние версии подключаются только к `github.com`, и перечисленные ниже переменные в них не действуют.

По умолчанию синхронизация с GitHub подключается к `github.com`. Чтобы использовать GitHub Enterprise Server (самостоятельно размещённый) или GitHub Enterprise Cloud с размещением данных в выбранном регионе (`GHE.com`), задайте в `GITHUB_SYNC_URL` веб-адрес вашего экземпляра — тот, по которому вы открываете репозитории в браузере.

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

> [!WARNING]
>
> * Создайте 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.

> [!NOTE]
>
> Если ваш экземпляр использует сертификат частного центра сертификации (CA), смонтируйте сертификат CA в контейнер и укажите путь к нему в `NODE_EXTRA_CA_CERTS`, например `NODE_EXTRA_CA_CERTS=/var/lib/overleaf/certs/github-ca.pem`.

> [!CAUTION]
>
> Привязанные учётные записи и проекты относятся к тому экземпляру, с которым они были привязаны. Прежде чем переключать `GITHUB_SYNC_URL` на другой экземпляр, попросите пользователей отвязать свои учётные записи GitHub и проекты.

### Кто может привязывать и синхронизировать

Как и в Overleaf Cloud, привязать проект к репозиторию GitHub может только владелец проекта. После привязки синхронизировать проект может любой соавтор с правами на редактирование.

| Действие | Кто может это сделать |
| - | - |
| Экспорт проекта в новый репозиторий GitHub | Владелец проекта |
| Импорт репозитория GitHub в новый проект | Любой пользователь, который становится владельцем нового проекта |
| Pull, push и слияние привязанного проекта | Владелец и соавторы с правами на редактирование |
| Отвязка проекта от репозитория | Владелец проекта |

* Overleaf взаимодействует с GitHub от имени учётной записи GitHub пользователя, выполняющего синхронизацию, поэтому каждый соавтор, который синхронизирует проект, привязывает собственную учётную запись GitHub и должен иметь право на push в ветку по умолчанию репозитория.
* Соавторы с правами только на просмотр не могут использовать синхронизацию с GitHub для этого проекта.

### Q\&A

> [accordion] Как привязать проект к 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**.

> [accordion] Можно ли выполнять force push в ветку по умолчанию?
>
> **Ответ:** Мы не рекомендуем этого делать. Overleaf обнаруживает force push, предупреждает о нём и принимает переписанную ветку, выполняя слияние изменений, сделанных в Overleaf с момента последней синхронизации. Чтобы избежать неожиданностей, защитите ветку по умолчанию от force push в настройках репозитория.

> [accordion] Можно ли переименовать ветку по умолчанию привязанного проекта?
>
> **Ответ:** Пожалуйста, не делайте этого. Overleaf продолжает синхронизацию с той веткой, к которой был привязан проект. Чтобы синхронизироваться с другой веткой, отвяжите проект, а затем импортируйте репозиторий в новый проект — он будет использовать текущую ветку по умолчанию.

> [accordion] Синхронизация с GitHub показывает «Something wrong with GitHub request»
>
> **Ответ:** Это сообщение означает, что серверу не удалось связаться с GitHub, например из-за проблемы с сетью, DNS, TLS или прокси. Выполните `bin/logs web`, чтобы увидеть полную ошибку. Если серверу нужен прокси для доступа к GitHub, задайте `GITHUB_SYNC_PROXY_URL`.

> [accordion] Нужно ли отключать «Expire user access tokens» в GitHub OAuth App?
>
> **Ответ:** Да. Синхронизация с GitHub не обновляет истёкшие токены. Если истечение токенов включено, пользователям придётся заново подключать GitHub каждый раз, когда истекает их токен.

> [accordion] Должен ли мой экземпляр быть доступен из интернета?
>
> **Ответ:** Нет. Привязка учётной записи выполняется через браузер пользователя, поэтому адрес обратного вызова OAuth должен лишь открываться в браузере пользователя. Серверу нужен только доступ к GitHub; если для этого нужен прокси, задайте `GITHUB_SYNC_PROXY_URL`. GitHub никогда не обращается к вашему экземпляру: проект синхронизируется только тогда, когда пользователь синхронизирует его в редакторе.

> [accordion] Привязка учётной записи 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`, чтобы пересоздать контейнеры.

> [accordion] Импорт репозитория завершается ошибкой «EmptyZipFileError: empty\_zip\_file» или «unzip failed»
>
> **Ответ:** Overleaf импортирует zip-архив последнего коммита ветки по умолчанию репозитория, и эта ошибка означает, что в архиве нет ни одного файла, который Overleaf может импортировать. Проверьте ветку по умолчанию в GitHub:
>
> * Она содержит файлы проекта, а не только файлы, которые Overleaf пропускает при импорте: dot-файлы, такие как `.gitignore` и `.gitmodules` (`.latexmkrc` сохраняется), и файлы сборки, такие как `*.aux`, `*.log`, `*.bbl`, `*.synctex.gz`, `*.doc` и `*.docx`.
> * Файлы находятся не только внутри подмодулей Git. В архиве GitHub подмодули остаются пустыми папками.
> * Нужные вам файлы находятся в ветке по умолчанию, а не в другой ветке. Импорт всегда использует ветку по умолчанию.

> [accordion] Импорт репозитория завершается ошибкой «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](https://ayakaleaf-pro.mintlify.site/ru/on-premises/configuration/overleaf-toolkit/integrations/git-integration.md)) и пересоздайте контейнер. Toolkit уже задаёт это значение; проверьте, что `docker-compose.override.yml` его не переопределяет.


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