Интеграция с GitHub

Git-репозитории — основа подавляющего большинства программных проектов. Мы интегрируемся с GitHub, чтобы предоставлять аналитику Tuist прямо в ваших пул-реквестах и избавлять от части настройки, например синхронизации ветки по умолчанию.

Настройка#

Установите приложение Tuist для GitHub во вкладке Integrations вашей организации:

Вы также можете установить приложение напрямую из GitHub. При необходимости войдите в Tuist, авторизуйте приложение GitHub, чтобы Tuist мог подтвердить ваш доступ к установке, и выберите организацию Tuist для подключения. Вы должны владеть организацией GitHub (или личным аккаунтом GitHub), куда устанавливается приложение. Доступны только организации Tuist, которыми вы управляете, и ваш личный аккаунт Tuist. Если доступен только один аккаунт, Tuist подключит его автоматически, не показывая выбор. При начале работы из Tuist организация уже выбрана, и этот шаг пропускается.

После этого вы можете добавить связь проекта между вашим репозиторием GitHub и проектом Tuist:

После установки приложения вы также можете связать проект без использования панели управления:

• CLI:tuist project repository connect owner/name, а также tuist project repository disconnect для удаления связи.
• REST API: методы PUT и DELETE для /api/projects/{account_handle}/{project_handle}/vcs-connection.
• Model Context Protocol: инструменты connect_project_repository и disconnect_project_repository.

Репозиторий должен быть доступен установке приложения GitHub, а проект использует ветку по умолчанию этого репозитория. Токенам аккаунта требуется область доступа project:admin:write.

GitHub Enterprise Server#

Tuist также интегрируется с самостоятельно размещёнными экземплярами GitHub Enterprise Server (GHES). На карточке интеграции с GitHub перейдите на вкладку Enterprise server, введите базовый URL вашего GHES (например, https://github.example.com) и нажмите «Install».

Поскольку приложения GitHub привязаны к одному экземпляру GitHub, Tuist не может повторно использовать своё приложение с github.com в вашем GHES. Вместо этого кнопка установки запускает поток манифеста приложения GitHub: GHES помогает вашему администратору зарегистрировать новое приложение Tuist на экземпляре, а затем передаёт учётные данные нового приложения обратно в Tuist. Tuist хранит эти учётные данные в зашифрованном виде для каждой установки и использует их для всех вызовов API, подписей вебхуков и ссылок на ваши репозитории.

Дополнительная настройка сервера Tuist не требуется: поток манифеста автоматически генерирует и настраивает всё необходимое.

Разрешения приложения и события вебхуков#

Для комментариев к пул-реквестам и проверок размера бандла Tuist требует следующие разрешения для репозитория:

Tuist использует событие вебхука check_run для обработки действий проверки размера бандла. Поток манифеста настраивает эту подписку автоматически.

Для ручной настройки приложения на github.com с самостоятельно размещённым сервером Tuist см. руководство по самостоятельному размещению.

Отдельные URL для браузера и API#

Если инженеры получают доступ к GitHub Enterprise через внутренний хостнейм, а сторонние сервисы используют внешний прокси, настройте оба адреса перед нажатием кнопки установки:

URL API — это полный базовый URL REST API, включая /api/v3 или эквивалентный путь, предоставляемый вашим прокси. Tuist не добавляет /api/v3 к явно указанному URL API. Оставьте поле пустым, если один хостнейм работает и для вашего браузера, и для Tuist; существующие подключения продолжат использовать <Server URL>/api/v3.

Оба адреса должны направлять запросы к одному и тому же экземпляру GitHub Enterprise. Вашему браузеру нужно обращаться только к URL сервера, а не к API-прокси. Серверам Tuist нужно обращаться только к URL API, а не к внутреннему хостнейму браузера.

Для внешнего прокси:

• Используйте HTTPS с сертификатом, которому доверяют серверы Tuist, и публичным DNS, разрешающимся в публичные IP-адреса. Переопределения URL API не обходят защиты Tuist от частных IP-адресов и SSRF. Переопределение должно указывать на ваш экземпляр Enterprise, а не на github.com или конечную точку *.github.com.
• Добавьте в белый список каждый исходящий IP-адрес Tuist.
• Перенаправляйте конечные точки REST API, которые использует Tuist, включая POST /api/v3/app-manifests/{code}/conversions, POST /api/v3/app/installations/{installation_id}/access_tokens и конечные точки API репозитория для комментариев и проверок. Это upstream-пути GitHub; переведите их, если ваш прокси предоставляет другой префикс.
• Перенаправляйте запросы к GitHub без HTTP-редиректов или интерактивной страницы входа. Tuist не следует автоматически за редиректами API Enterprise, поэтому они не могут обойти проверки публичных IP-адресов. Конечная точка конвертации манифеста должна быть доступна во время настройки, до того как у Tuist появятся учетные данные приложения. Загрузка логов GitHub Actions является исключением: Tuist следует за редиректами подписанных архивов только по HTTPS, проверяет и привязывает каждое назначение к публичному IP-адресу и не пересылает токен установки.

GitHub может возвращать ссылки пагинации, используя свой внутренний хостнейм. Tuist перебазирует ссылки от настроенного экземпляра GitHub на URL API, сохраняя префикс пути вашего прокси; ссылки на нерелевантные источники отклоняются.

Отдельно, GitHub должен иметь возможность доставлять вебхуки на https://tuist.dev/webhooks/github (или /webhooks/github на вашем самостоятельно размещённом сервере Tuist). Инженеры должны иметь возможность вернуться в Tuist для завершения обратных вызовов браузера. URL API не меняет ни одно из этих назначений.

Администраторы организации также могут изменить или очистить URL API в существующей интеграции Enterprise, используя Сохранить URL API в карточке интеграции. Переустановка приложения или повторное подключение проекта не требуются. Очистка восстанавливает <Server URL>/api/v3. При сохранении проверяется формат URL, а не подключение через прокси. Обработка вебхуков может занять до одной минуты для использования измененного адреса, так как поиски установки кэшируются; запросы, уже находящиеся в процессе выполнения, могут все еще использовать предыдущий адрес.

Комментарии к пул-реквестам/merge-реквестам#

Приложение GitHub публикует отчет о запуске Tuist, который включает сводку по пул-реквесту, в том числе ссылки на последние превью или тесты:

Tuist обновляет один комментарий по мере поступления результатов. Сборки Gradle отображаются отдельно для каждого корневого проекта и набора запрошенных задач; повторный запуск тех же задач заменяет предыдущий результат этого вызова. Полная история сборок остается доступной в Tuist.

Комментарии включены по умолчанию, что сохраняет отчетность для существующих интеграций. Чтобы отключить или снова включить их для проекта, откройте Настройки проекта → Интеграции и переключите GitHub → Комментарии к отчетам о запусках. У каждого проекта своя настройка; подключения репозиториев остаются под управлением в настройках организации.

Отключение комментариев не отключает выгрузку сборок или тестов, сводки заданий GitHub Actions, подключения репозиториев или другие функции интеграции с GitHub. Существующие комментарии не удаляются.

Сводка задания GitHub Actions#

CLI Tuist и плагин Gradle записывают результаты тестов и сборок в сводку задания в GitHub Actions. Сводка содержит ссылку на полный отчет в Tuist, где доступны более подробные данные, такие как нестабильные тесты и изменения размера бандла.

Для Gradle каждый успешно загруженный отчет о сборке или тесте добавляет свою собственную сводку, сохраняя другой контент, записанный такими инструментами, как gradle/actions/setup-gradle. Для этого требуется версия плагина, поддерживающая сводки заданий; старые версии плагина Gradle сообщают результаты только через комментарий приложения GitHub к пул-реквесту. Приложение GitHub не нужно подключать для сводок заданий, и отключение Комментариев к отчетам о запусках на них не влияет.

Когда доступно назначение для сводки GitHub Actions, Gradle ожидает завершения выгрузок и формирования сводок перед выходом, даже если включено uploadInBackground. GitHub фиксирует сводку при завершении шага рабочего процесса.

Это особенно полезно при использовании очередей слияния. Запуск из очереди слияния не привязан к пул-реквесту, поэтому комментарий не публикуется, но сводка задания все равно отображает результаты.