Skip to main content

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

Вы выбираете любую комбинацию из трёх типов содержимого:
  • 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 не поддерживаются.
  • Для синхронизации прав — Enterprise Edition. В Yahont CE синхронизации прав нет.

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

Создайте токен от имени пользователя, который видит каждый репозиторий, который вы хотите индексировать; для синхронизации прав пользователю токена также нужен доступ push к каждому приватному репозиторию. Fine-grained токены — вариант с наименьшими привилегиями. Используйте classic-токен, если ваша организация не разрешает fine-grained токены или если один токен должен охватывать репозитории нескольких владельцев. Выбирайте срок действия осознанно: когда токен истекает или отзывается, индексация останавливается, пока вы не сохраните в Yahont новый. После создания токена сразу скопируйте его — GitHub показывает его только один раз.
В GitHub откройте Settings -> Developer settings -> Personal access tokens -> Fine-grained tokens и выберите Generate new token (руководство GitHub).
  • Resource owner: пользователь или организация, которым принадлежат репозитории. Для синхронизации прав нужно разрешение уровня организации, поэтому для синхронизации прав выберите организацию, а не личный аккаунт. Организация должна разрешать fine-grained токены и может требовать этап одобрения, прежде чем токен для неё заработает.
  • Repository access: репозитории для индексации или All repositories.
  • Repository permissions: установите Contents, Issues и Pull requests в Read-only. GitHub добавляет Metadata сам.
  • Organization permissions, только если вы используете синхронизацию прав: установите Members в Read-only.
Предоставьте Contents, даже если не индексируете документы: когда вы указываете конкретные репозитории, Yahont читает корень каждого репозитория при настройке, и токен без Contents не проходит проверку.

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

1

Откройте коннектор GitHub

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

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

Нажмите Create New и вставьте токен в GitHub Access Token.Оставьте GitHub Enterprise Server URL пустым для github.com. Чтобы индексировать инстанс 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: индексировать каждый репозиторий этого владельца, который видит токен.
Если указано несколько имён репозиториев, Yahont при настройке проверяет только, что один из них доступен. Имя с опечаткой или недоступное имя пропускается при индексации без ошибки в интерфейсе, поэтому проверьте каждое имя.
Если владелец — личный аккаунт, а не организация, Everything находит только публичные репозитории этого аккаунта. Используйте Specific Repository, чтобы индексировать приватные репозитории личного аккаунта.
5

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

Включите хотя бы один из вариантов Include pull requests?, Include Issues? и Include Documents?. О том, что включает каждый, см. Что индексируется.
6

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

Public показывает каждый проиндексированный документ всем пользователям Yahont. Private ограничивает их выбранными группами пользователей Yahont. Auto Sync Permissions воспроизводит собственный доступ каждого ищущего на GitHub; см. Синхронизация прав.В Yahont CE, где нет синхронизации прав, этот переключатель не отображается, и коннектор — Public. Подробнее см. Управление доступом к документам.
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 по умолчанию Yahont также отклоняет адреса частной сети; администратор может смягчить этот уровень, чтобы обратиться к внутреннему серверу. URL хранится в учётных данных, поэтому одно развёртывание Yahont может индексировать github.com и Enterprise Server параллельно с разными учётными данными. Развёртывания с самостоятельным размещением могут вместо этого задать переменную окружения GITHUB_CONNECTOR_BASE_URL как значение по умолчанию для всего развёртывания для учётных данных с пустым полем; см. Конфигурация.

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

Задайте тип доступа 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.
Синхронизация прав — функция Enterprise Edition. В Yahont CE переключатель типа доступа не отображается, а коннекторы — Public.

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

Владелец или имя репозитория написаны с опечаткой, либо токен не видит репозитории. Для fine-grained токена проверьте, что репозитории выбраны в Repository access и что предоставлен доступ на чтение Contents; Yahont читает корень репозитория при проверке, даже если документы не индексируются.
Организация принудительно использует единый вход SAML. Авторизуйте токен для организации, затем повторите.
Коннектор Everything не нашёл ничего, что токен видит для этого владельца. Проверьте написание владельца и дайте classic-токену область repo или fine-grained токену доступ к репозиториям владельца.
Токен их не видит, поэтому Yahont пропускает их без ошибки: у classic-токена нет области repo, fine-grained токен не включает эти репозитории или владелец — личный аккаунт в режиме Everything, который находит только публичные репозитории.
Значения Branch нет в репозитории. Исправьте имя ветки или оставьте поле пустым, чтобы использовать ветку по умолчанию каждого репозитория.
В профиле GitHub нет публичного адреса электронной почты, либо он отличается от адреса для входа в Yahont. См. Сопоставление пользователей GitHub с пользователями Yahont.
Токен исчерпал часовую квоту API GitHub, обычно потому что ею пользуется что-то ещё. Во время индексации Yahont сам дожидается снятия лимита и повторяет; если эта ошибка возникла при настройке, дождитесь сброса квоты и повторите.
Токен отозван, истёк или вставлен неверно. Создайте новый токен и обновите учётные данные на странице коннектора в Панель администратора -> Существующие коннекторы.