> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yahont.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub

> Индексирование запросов на слияние, задач и файлов документации из ваших репозиториев GitHub

## Что индексируется

Вы выбираете любую комбинацию из трёх типов содержимого:

* **Pull requests** (запросы на слияние): заголовок и описание каждого запроса на слияние, открытого и закрытого.
  Yahont также сохраняет автора, исполнителей, метки, состояние, статус слияния,
  число коммитов и изменённых файлов и метки времени в качестве метаданных.
* **Issues** (задачи): заголовок и описание каждой задачи, открытой и закрытой,
  с автором, исполнителями, метками, состоянием и метками времени в качестве метаданных.
* **Documents** (документы): файлы документации из каждого репозитория.
  Это файлы `.md`, `.mdx`, `.markdown`, `.rst` и `.txt`, а также файлы без расширения,
  которые по соглашению являются документацией, такие как `README`, `LICENSE`, `CHANGELOG`,
  `CONTRIBUTING` и `CODEOWNERS`.

### Что не индексируется

* Комментарии к задачам и запросам на слияние, комментарии рецензентов, диффы и коммиты
* Исходный код, а также файлы данных или конфигурации, такие как `.json`, `.yaml` и `.csv`
* Файлы больше 1 МБ, бинарные файлы
  и всё в `.git`, `node_modules`, `vendor`, `dist`, `build`, `.venv` или `__pycache__`
* Вики, обсуждения, релизы и проекты

## Перед началом

Вам понадобятся:

* Аккаунт администратора Yahont.
* Персональный токен доступа GitHub — fine-grained или classic.
  Yahont аутентифицируется только с помощью токена; GitHub App и вход через OAuth не поддерживаются.
* Для [синхронизации прав](#permission-sync) — Enterprise Edition. В Yahont CE синхронизации прав нет.

## Создание токена

Создайте токен от имени пользователя, который видит каждый репозиторий, который вы хотите индексировать;
для синхронизации прав пользователю токена также нужен доступ push к каждому приватному репозиторию.
Fine-grained токены — вариант с наименьшими привилегиями. Используйте classic-токен,
если ваша организация не разрешает fine-grained токены или если один токен должен охватывать репозитории нескольких
владельцев.

Выбирайте срок действия осознанно: когда токен истекает или отзывается, индексация останавливается,
пока вы не сохраните в Yahont новый. После создания токена сразу скопируйте его — GitHub показывает его только один раз.

**Fine-grained токен**

В GitHub откройте **Settings -> Developer settings -> Personal access tokens -> Fine-grained tokens** и выберите
**Generate new token** ([руководство
GitHub](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)).

* **Resource owner**: пользователь или организация, которым принадлежат репозитории.
  Для синхронизации прав нужно разрешение уровня организации, поэтому для синхронизации прав выберите организацию,
  а не личный аккаунт. Организация должна разрешать fine-grained токены и может требовать этап одобрения,
  прежде чем токен для неё заработает.
* **Repository access**: репозитории для индексации или **All repositories**.
* **Repository permissions**: установите **Contents**, **Issues** и **Pull requests** в **Read-only**.
  GitHub добавляет **Metadata** сам.
* **Organization permissions**, только если вы используете синхронизацию прав:
  установите **Members** в **Read-only**.

> [!NOTE]
>
> Предоставьте **Contents**, даже если не индексируете документы: когда вы указываете конкретные репозитории,
> Yahont читает корень каждого репозитория при настройке, и токен без **Contents** не проходит проверку.

**Classic токен**

В GitHub откройте **Settings -> Developer settings -> Personal access tokens -> Tokens (classic)** и выберите
**Generate new token** ([руководство
GitHub](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic)).

Выберите области в зависимости от потребностей:

| Что нужно | Области |
| - | - |
| Только публичные репозитории | Нет |
| Приватные репозитории | `repo` |
| Синхронизация прав | `repo` и `read:org` |

Если организация принудительно использует единый вход SAML,
также [авторизуйте токен для
организации](https://docs.github.com/en/enterprise-cloud@latest/authentication/authenticating-with-single-sign-on/authorizing-a-personal-access-token-for-use-with-single-sign-on)
после создания.

## Настройка коннектора в Yahont

**1. Откройте коннектор GitHub**

В Yahont откройте **Панель администратора -> Добавить коннектор** и выберите **GitHub**.

**2. Создайте учётные данные**

Нажмите **Create New** и вставьте токен в **GitHub Access Token**.

Оставьте **GitHub Enterprise Server URL** пустым для github.com.
Чтобы индексировать инстанс GitHub Enterprise Server, см. [GitHub Enterprise Server](#github-enterprise-server).

**3. Задайте название коннектора и владельца**

Введите **Connector Name**, затем **Repository Owner**: логин пользователя или организации,
которым принадлежат репозитории. Для `https://github.com/onyx-dot-app/onyx` это `onyx-dot-app`.

**4. Выберите репозитории**

В разделе **What should we index from GitHub?** выберите один вариант:

* **Specific Repository**: введите одно имя репозитория в **Repository Name(s)**, например `onyx`,
  или несколько через запятую, например `onyx,docs`. Подстановочные знаки не работают.
* **Everything**: индексировать каждый репозиторий этого владельца, который видит токен.

> [!WARNING]
>
> Если указано несколько имён репозиториев, Yahont при настройке проверяет только, что один из них доступен.
> Имя с опечаткой или недоступное имя пропускается при индексации без ошибки в интерфейсе,
> поэтому проверьте каждое имя.

> [!NOTE]
>
> Если владелец — личный аккаунт, а не организация,
> **Everything** находит только публичные репозитории этого аккаунта. Используйте **Specific Repository**,
> чтобы индексировать приватные репозитории личного аккаунта.

**5. Выберите типы содержимого**

Включите хотя бы один из вариантов **Include pull requests?**, **Include Issues?** и **Include Documents?**. О том,
что включает каждый, см. [Что индексируется](#what-gets-indexed).

**6. Выберите тип доступа**

**Public** показывает каждый проиндексированный документ всем пользователям Yahont.
**Private** ограничивает их выбранными группами пользователей Yahont.
**Auto Sync Permissions** воспроизводит собственный доступ каждого ищущего на GitHub; см.
[Синхронизация прав](#permission-sync).

В Yahont CE, где нет синхронизации прав, этот переключатель не отображается, и коннектор — **Public**. Подробнее см.
[Управление доступом к документам](/admins/connectors/overview#document-access-controls).

**7. Задайте ветку (необязательно)**

В **Advanced Options** параметр **Branch** задаёт ветку, из которой читаются документы, например `gh-pages`;
пусто означает ветку по умолчанию каждого репозитория. Он влияет на индексацию,
только когда включён **Include Documents?**, хотя для одного репозитория Yahont всё равно проверяет при настройке,
что ветка существует. После изменения в существующем коннекторе выберите **Re-Index** на странице коннектора,
чтобы подхватить новую ветку.

**8. Создайте и проверьте**

Нажмите **Create Connector**. Yahont проверяет учётные данные и репозитории, затем начинает индексацию.

Откройте **Панель администратора -> Существующие коннекторы**, выберите коннектор и убедитесь,
что первая попытка индексации достигла **Succeeded**.
Затем найдите в Yahont заголовок запроса на слияние или README, которые, как вы знаете, проиндексированы.

## GitHub Enterprise Server

Чтобы индексировать инстанс GitHub Enterprise Server,
задайте **GitHub Enterprise Server URL** в учётных данных равным адресу вашего сервера.
Работают и веб-хост `https://github.example.com`, и корень API `https://github.example.com/api/v3`.
Создайте персональный токен доступа на самом инстансе Enterprise Server по тому же пути в **Settings**;
доступность там fine-grained токенов зависит от версии и конфигурации сервера.

URL должен использовать HTTPS. При [уровне защиты от SSRF](/admins/advanced_configs/security_hardening#ssrf-protection)
по умолчанию Yahont также отклоняет адреса частной сети; администратор может смягчить этот уровень,
чтобы обратиться к внутреннему серверу.

URL хранится в учётных данных,
поэтому одно развёртывание Yahont может индексировать github.com и Enterprise Server параллельно с разными учётными
данными.
Развёртывания с самостоятельным размещением могут вместо этого задать переменную окружения `GITHUB_CONNECTOR_BASE_URL`
как значение по умолчанию для всего развёртывания для учётных данных с пустым полем; см.
[Конфигурация](/deployment/configuration/configuration).

## Синхронизация прав

Задайте тип доступа **Auto Sync Permissions** при создании коннектора,
и пользователь Yahont будет видеть только то содержимое GitHub, которое он может читать на GitHub.
Для администратора по умолчанию выбрано **Public**, поэтому выбирайте этот вариант осознанно;
тип доступа нельзя изменить позже в интерфейсе администратора, поэтому для смены коннектор нужно создать заново.

* Документы из **публичных** репозиториев видны каждому пользователю Yahont.
* Документы из **приватных** репозиториев видны соавторам репозитория,
  включая людей, имеющих доступ через команду.
* Документы из **внутренних** репозиториев (GitHub Enterprise) видны членам организации,
  сопоставленным по адресу электронной почты, как описано ниже.

### Сопоставление пользователей GitHub с пользователями Yahont

Yahont сопоставляет по адресу электронной почты:
**публичный адрес электронной почты** в профиле GitHub должен совпадать с адресом для входа в Yahont,
без учёта регистра. Пользователь, у которого адрес в GitHub скрыт, не задан или отличается от адреса в Yahont,
не видит содержимого приватных и внутренних репозиториев.

Чтобы задать публичный адрес электронной почты в GitHub, откройте **Settings -> Emails**,
снимите **Keep my email addresses private**, затем выберите адрес в **Public profile -> Public email**.

### Требования к токену

* Пользователю токена нужен **доступ push** к каждому приватному репозиторию, который индексирует коннектор,
  потому что GitHub раскрывает список соавторов репозитория только пользователям с доступом push.
* Если какой-либо репозиторий коннектора не удаётся синхронизировать, запуск обновления прав останавливается,
  а остальные репозитории пропускаются. Синхронизация прав «закрывается при сбое»:
  пока запуски продолжают завершаться ошибкой,
  пользователи могут потерять доступ к документам приватных и внутренних репозиториев,
  поэтому быстро исправляйте сбойную синхронизацию.
* Для внутренних репозиториев пользователь токена должен быть членом организации.
  Не член получает только публичных членов организации, что молча исключает большинство пользователей.
* Команды GitHub не синхронизируются как группы Yahont.
  Члены команды всё равно получают доступ к приватным репозиториям через список соавторов.
  Team members still get access to private repositories through the collaborator list.

> [!NOTE]
>
> Синхронизация прав — функция Enterprise Edition. В Yahont CE переключатель типа доступа не отображается,
> а коннекторы — **Public**.

## Устранение неполадок

> **Ни один из указанных репозиториев недоступен**
>
> Владелец или имя репозитория написаны с опечаткой, либо токен не видит репозитории.
> Для fine-grained токена проверьте,
> что репозитории выбраны в **Repository access** и что предоставлен доступ на чтение **Contents**;
> Yahont читает корень репозитория при проверке, даже если документы не индексируются.

> **В вашем токене GitHub нет авторизации для доступа к организации**
>
> Организация принудительно использует единый вход SAML.
> [Авторизуйте токен для
> организации](https://docs.github.com/en/enterprise-cloud@latest/authentication/authenticating-with-single-sign-on/authorizing-a-personal-access-token-for-use-with-single-sign-on),
> затем повторите.

> **Не найдено репозиториев для организации или пользователя**
>
> Коннектор **Everything** не нашёл ничего, что токен видит для этого владельца.
> Проверьте написание владельца и дайте classic-токену область `repo` или fine-grained токену доступ к репозиториям
> владельца.

> **Приватные репозитории отсутствуют в индексе**
>
> Токен их не видит, поэтому Yahont пропускает их без ошибки: у classic-токена нет области `repo`,
> fine-grained токен не включает эти репозитории или владелец — личный аккаунт в режиме **Everything**,
> который находит только публичные репозитории.

> **Ветка не найдена**
>
> Значения **Branch** нет в репозитории. Исправьте имя ветки или оставьте поле пустым,
> чтобы использовать ветку по умолчанию каждого репозитория.

> **Пользователь не видит результатов GitHub при синхронизации прав**
>
> В профиле GitHub нет публичного адреса электронной почты, либо он отличается от адреса для входа в Yahont. См.
> [Сопоставление пользователей GitHub с пользователями Yahont](#matching-github-users-to-onyx-users).

> **Проверка не пройдена из-за превышения лимитов GitHub**
>
> Токен исчерпал часовую квоту API GitHub, обычно потому что ею пользуется что-то ещё.
> Во время индексации Yahont сам дожидается снятия лимита и повторяет; если эта ошибка возникла при настройке,
> дождитесь сброса квоты и повторите.

> **Учётные данные GitHub недействительны или просрочены**
>
> Токен отозван, истёк или вставлен неверно.
> Создайте новый токен и обновите учётные данные на странице коннектора в **Панель администратора -> Существующие
> коннекторы**.


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